API Evangelist conversational phrasing for Flagsmith Metadata API

# 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'