API Evangelist conversational phrasing for Flagsmith Segments 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 Segments API
  version: 1.0.0
extends: openapi/flagsmith-segments-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: 11
- target: $.paths['/projects/{project_id}/segments/'].get
  update:
    x-apievangelist-phrasing:
      intent: List a project's segments
      effect: read
      questions:
      - Which user segments are defined in my project?
      - What segments can I target flags at in this project?
      instructions:
      - text: List all segments in project {project_id}.
        slots:
          project_id: path.project_id
      - text: Show me the segment names defined for project {project_id}.
        slots:
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/segments/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a segment from trait rules
      effect: write
      questions:
      - How do I create a segment of users based on trait rules for targeted flags?
      - Can I define a new segment like 'beta testers' with conditions on user traits?
      instructions:
      - text: Create segment {name} in project {project_id} with rules {rules}.
        slots:
          name: requestBody.name
          project_id: path.project_id
          rules: requestBody.rules
      - text: Add a new segment {name} described as {description} to project {project_id}.
        slots:
          name: requestBody.name
          description: requestBody.description
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/segments/{segment_id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment's rules and conditions
      effect: read
      questions:
      - What rules and conditions make up a particular segment?
      - Can I inspect how one segment decides which users belong to it?
      instructions:
      - text: Show segment {segment_id} in project {project_id} with its rules.
        slots:
          segment_id: path.segment_id
          project_id: path.project_id
      - text: Get the conditions for segment {segment_id} in project {project_id}.
        slots:
          project_id: path.project_id
          segment_id: path.segment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/segments/{segment_id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a segment's name, description and rules
      effect: write
      questions:
      - How do I rewrite the full rule set of an existing segment?
      - Can I rename a segment and replace its rules in one update?
      instructions:
      - text: Update segment {segment_id} in project {project_id} to name {name} with rules {rules}.
        slots:
          segment_id: path.segment_id
          project_id: path.project_id
          name: requestBody.name
          rules: requestBody.rules
      - text: Replace the rules on segment {segment_id} in project {project_id} with {rules}.
        slots:
          segment_id: path.segment_id
          project_id: path.project_id
          rules: requestBody.rules
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/segments/{segment_id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a segment
      effect: destructive
      questions:
      - What happens to segment overrides when I delete a segment?
      - Can I undo deleting a segment from a project?
      instructions:
      - text: Delete segment {segment_id} from project {project_id} along with its overrides.
        slots:
          segment_id: path.segment_id
          project_id: path.project_id
      - text: Permanently remove segment {segment_id} in project {project_id}.
        slots:
          project_id: path.project_id
          segment_id: path.segment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/segments/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment via the v1 project endpoint
      effect: destructive
      questions:
      - Is there a v1 API path under /api/v1/projects for deleting a segment?
      - Can I remove a segment using the project_pk-based v1 route?
      instructions:
      - text: Delete segment {id} from project {project_pk} using the v1 segments endpoint.
        slots:
          id: path.id
          project_pk: path.project_pk
      - text: Use the v1 API to remove segment {id} in project {project_pk}.
        slots:
          project_pk: path.project_pk
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/segments/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change some fields on a segment
      effect: write
      questions:
      - Can I change just a segment's description without resending its rules?
      - Is it possible to attach metadata to an existing segment?
      instructions:
      - text: Change only the description of segment {id} in project {project_pk} to {description}.
        slots:
          id: path.id
          project_pk: path.project_pk
          description: requestBody.description
      - text: Set metadata {metadata} on segment {id} in project {project_pk}.
        slots:
          metadata: requestBody.metadata
          id: path.id
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/segments/{id}/associated-features/'].get
  update:
    x-apievangelist-phrasing:
      intent: See which features a segment is used by
      effect: read
      questions:
      - Which features have overrides that depend on this segment?
      - Can I check what features a segment affects in one environment before I change it?
      instructions:
      - text: List the features associated with segment {id} in project {project_pk}.
        slots:
          id: path.id
          project_pk: path.project_pk
      - text: Show features using segment {id} of project {project_pk} in environment {environment}.
        slots:
          id: path.id
          project_pk: path.project_pk
          environment: query.environment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/segments/{id}/clone/'].post
  update:
    x-apievangelist-phrasing:
      intent: Clone a segment under a new name
      effect: write
      questions:
      - How do I duplicate an existing segment so I can tweak the copy?
      - Can I copy a segment's rules into a new segment with a different name?
      instructions:
      - text: Clone segment {id} in project {project_pk} as {name}.
        slots:
          id: path.id
          project_pk: path.project_pk
          name: requestBody.name
      - text: Make a copy of segment {id} from project {project_pk} called {name}.
        slots:
          project_pk: path.project_pk
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/segments/{id}/members/'].get
  update:
    x-apievangelist-phrasing:
      intent: List the identities in a segment
      effect: read
      questions:
      - Which users currently fall into a given segment in an environment?
      - Can I search a segment's members by identifier and page through them?
      instructions:
      - text: List members of segment {id} in project {project_pk} for environment {environment}.
        slots:
          id: path.id
          project_pk: path.project_pk
          environment: query.environment
      - text: Find members matching {q} in segment {id} of project {project_pk}, environment {environment}.
        slots:
          q: query.q
          id: path.id
          project_pk: path.project_pk
          environment: query.environment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/segments/get-by-uuid/{uuid}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a segment by its UUID
      effect: read
      questions:
      - Can I find a segment when all I have is its UUID, not the project or numeric ID?
      - Which segment does this UUID belong to?
      instructions:
      - text: Get the segment with UUID {uuid}.
        slots:
          uuid: path.uuid
      - text: Resolve segment UUID {uuid} to its project and name.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-09-26'