# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand. overlay: 1.0.0 info: title: API Evangelist conversational phrasing for Flagsmith Metadata API version: 1.0.0 extends: openapi/flagsmith-metadata-api-openapi.yml actions: - target: $.info update: x-apievangelist-phrasing: method: generated generated: '2026-09-26' generator: build-phrasing.py label: Generated by API Evangelist operations: 9 - target: $.paths['/api/v1/auth/saml/{name}/metadata/'].get update: x-apievangelist-phrasing: intent: Download SAML service provider metadata effect: read questions: - Where do I get the SAML metadata to give my identity provider? - Can the SAML metadata be returned in a different format? instructions: - text: Get the SAML metadata for configuration {name}. slots: name: path.name - text: Download SAML config {name}'s metadata in format {format}. slots: name: path.name format: query.format method: generated generated: '2026-09-26' - target: $.paths['/api/v1/metadata/fields/'].get update: x-apievangelist-phrasing: intent: List an organisation's custom metadata fields effect: read questions: - What custom metadata fields has my organisation defined? - Can I page through metadata fields for one organisation? instructions: - text: List metadata fields for organisation {organisation}. slots: organisation: query.organisation - text: Show {page_size} metadata fields per page for organisation {organisation}, page {page}. slots: page_size: query.page_size organisation: query.organisation page: query.page method: generated generated: '2026-09-26' - target: $.paths['/api/v1/metadata/fields/'].post update: x-apievangelist-phrasing: intent: Define a new custom metadata field effect: write questions: - How do I add a custom field such as a Jira ticket URL to my flags? - Which data types can a metadata field hold? instructions: - text: Create metadata field {name} in organisation {organisation}. slots: name: requestBody.name organisation: requestBody.organisation - text: Add a {type} metadata field {name} to organisation {organisation}, scoped to project {project}. slots: type: requestBody.type name: requestBody.name organisation: requestBody.organisation project: requestBody.project method: generated generated: '2026-09-26' - target: $.paths['/api/v1/metadata/fields/{id}/'].get update: x-apievangelist-phrasing: intent: Get one metadata field definition effect: read questions: - What type and description does a given metadata field have? - Which entities is a metadata field attached to? instructions: - text: Fetch metadata field {field_id}. slots: field_id: path.id - text: Show the definition of custom field {field_id}. slots: field_id: path.id method: generated generated: '2026-09-26' - target: $.paths['/api/v1/metadata/fields/{id}/'].put update: x-apievangelist-phrasing: intent: Replace a metadata field definition effect: write questions: - Can I redefine a metadata field completely in one update? - Does a full metadata field update require the name and organisation again? instructions: - text: Replace metadata field {field_id} with name {name} in organisation {organisation}. slots: field_id: path.id name: requestBody.name organisation: requestBody.organisation - text: 'Overwrite field {field_id}: name {name}, type {type}, description {description}, organisation {organisation}.' slots: field_id: path.id name: requestBody.name type: requestBody.type description: requestBody.description organisation: requestBody.organisation method: generated generated: '2026-09-26' - target: $.paths['/api/v1/metadata/fields/{id}/'].delete update: x-apievangelist-phrasing: intent: Delete a metadata field effect: destructive questions: - How do I remove a custom metadata field we no longer use? - Are values stored against a metadata field lost when it is deleted? instructions: - text: Delete metadata field {field_id}. slots: field_id: path.id - text: Remove custom field {field_id} permanently. slots: field_id: path.id method: generated generated: '2026-09-26' - target: $.paths['/api/v1/metadata/fields/{id}/'].patch update: x-apievangelist-phrasing: intent: Edit part of a metadata field effect: write questions: - Can I just rename a metadata field? - Is changing only a field's description possible? instructions: - text: Rename metadata field {field_id} to {name}. slots: field_id: path.id name: requestBody.name - text: Set only the description of field {field_id} to {description}. slots: field_id: path.id description: requestBody.description method: generated generated: '2026-09-26' - target: $.paths['/api/v1/projects/{project_pk}/metadata/fields/'].get update: x-apievangelist-phrasing: intent: List metadata fields available to a project effect: read questions: - Which custom fields can I fill in on a project's features? - Can I include organisation-level fields that a project inherits? - Is it possible to see only the metadata fields for segments? instructions: - text: List metadata fields for project {project}. slots: project: path.project_pk - text: 'Show project {project}''s {entity} metadata fields, including inherited organisation ones: {include_organisation}.' slots: project: path.project_pk entity: query.entity include_organisation: query.include_organisation method: generated generated: '2026-09-26' - target: $.paths['/api/v1/projects/{project_pk}/metadata/fields/{id}/'].get update: x-apievangelist-phrasing: intent: Get a metadata field within a project effect: read questions: - What does a specific metadata field look like in the context of one project? - Can I read a project's metadata field by its id? instructions: - text: Fetch metadata field {field_id} in project {project}. slots: field_id: path.id project: path.project_pk - text: Show project {project}'s view of custom field {field_id}. slots: project: path.project_pk field_id: path.id method: generated generated: '2026-09-26'