API Evangelist conversational phrasing for Statsig 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 Statsig Segments API
  version: 1.0.0
extends: openapi/statsig-segments-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 20
- target: $.paths['/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List user segments
      effect: read
      questions:
      - Which user segments exist in my Statsig project?
      - Can I page through all our targeting segments?
      instructions:
      - text: List all segments in my project.
      - text: Show page {page} of segments, {limit} per page.
        slots:
          page: query.page
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user segment
      effect: write
      questions:
      - How do I create a reusable user segment for targeting?
      - What segment type do I need to pick when creating a segment?
      instructions:
      - text: Create a segment named {name} of type {type}.
        slots:
          name: requestBody.name
          type: requestBody.type
      - text: Create segment {name} of type {type} with membership rules {rules}.
        slots:
          name: requestBody.name
          type: requestBody.type
          rules: requestBody.rules
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment's configuration
      effect: read
      questions:
      - What rules define membership in a specific segment?
      - Can I look up one segment's full configuration by name?
      instructions:
      - text: Show the configuration of segment {id}.
        slots:
          id: path.id
      - text: Get segment {id} and its membership rules.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segments/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user segment
      effect: destructive
      questions:
      - How do I permanently remove a segment we no longer target?
      - Is deleting a user segment permanent?
      instructions:
      - text: Delete segment {id}.
        slots:
          id: path.id
      - text: Permanently remove user segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segments/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing user segment
      effect: write
      questions:
      - Can I change the membership rules of an existing segment?
      - Is it possible to rename a segment that already exists?
      instructions:
      - text: 'Update segment {id}: name {name}, type {type}, rules {rules}.'
        slots:
          id: path.id
          name: requestBody.name
          type: requestBody.type
          rules: requestBody.rules
      - text: Rename existing segment {id} to {name}, keeping type {type}.
        slots:
          id: path.id
          name: requestBody.name
          type: requestBody.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/console/v1/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List segments via the Console API v1
      effect: read
      questions:
      - Can the Console API v1 list every segment in the project?
      - Which segments does the v1 console endpoint return on each page?
      instructions:
      - text: List segments from the v1 console.
      - text: Fetch segments page {page} from Console API v1 at {limit} per page.
        slots:
          page: query.page
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a segment with an ID type and tags
      effect: write
      questions:
      - Can I set a custom ID for a new segment instead of using its name?
      - Can I assign a new segment to a team and tag it when creating it?
      - Which ID type should a new ID-list segment use?
      instructions:
      - text: Create segment {name} of type {type} with ID type {idType} through the v1 console.
        slots:
          name: requestBody.name
          type: requestBody.type
          idType: requestBody.idType
      - text: Create segment {name} of type {type}, ID {id}, owned by team {teamID}.
        slots:
          name: requestBody.name
          type: requestBody.type
          id: requestBody.id
          teamID: requestBody.teamID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment via the Console API v1
      effect: read
      questions:
      - Can the Console API v1 return one segment's details?
      - Who created a given segment and what ID type does it use?
      instructions:
      - text: Fetch segment {id} from the v1 console.
        slots:
          id: path.id
      - text: Look up the creator and ID type of segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment via the Console API v1
      effect: destructive
      questions:
      - Can I delete a segment through the Console API v1?
      - Which v1 console call removes a segment entirely rather than archiving it?
      instructions:
      - text: Delete segment {id} with the v1 console endpoint.
        slots:
          id: path.id
      - text: Remove segment {id} for good via Console API v1.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/add_ids'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add IDs to a User Store ID list segment
      effect: write
      questions:
      - Can I add IDs to a segment backed by the User Store ID list?
      - How many IDs can one User Store add request include?
      instructions:
      - text: Add IDs {ids} to the User Store ID list of segment {id}.
        slots:
          ids: requestBody.ids
          id: path.id
      - text: Append {ids} to User Store segment {id} at version {version}.
        slots:
          ids: requestBody.ids
          id: path.id
          version: requestBody.version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/archive'].put
  update:
    x-apievangelist-phrasing:
      intent: Archive a segment
      effect: write
      questions:
      - Can I archive a segment instead of deleting it?
      - Is there a way to retire a segment we no longer target without losing it?
      instructions:
      - text: Archive segment {id}.
        slots:
          id: path.id
      - text: Retire segment {id} by archiving it.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/conditional'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a segment's conditional rules
      effect: write
      questions:
      - Can I replace the conditional rules on a rule-based segment?
      - Is there an endpoint for just the rules of a conditional segment?
      instructions:
      - text: Update the conditional rules on segment {id}.
        slots:
          id: path.id
      - text: Rewrite the targeting conditions of segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/id_list'].get
  update:
    x-apievangelist-phrasing:
      intent: List the IDs in an ID list segment
      effect: read
      questions:
      - Which user IDs are in a particular ID list segment?
      - Is reading a segment's IDs rate limited?
      instructions:
      - text: List the IDs in segment {id}.
        slots:
          id: path.id
      - text: Show page {page} of IDs in segment {id}, {limit} per page.
        slots:
          page: query.page
          id: path.id
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/id_list'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove IDs from an ID list segment
      effect: destructive
      questions:
      - Can I remove specific users from an ID list segment?
      - What is the rate limit for removing IDs from a segment?
      instructions:
      - text: Remove IDs {ids} from segment {id}.
        slots:
          ids: requestBody.ids
          id: path.id
      - text: Take {ids} out of ID list segment {id}.
        slots:
          ids: requestBody.ids
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/id_list'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add IDs to an ID list segment
      effect: write
      questions:
      - Can I add more user IDs to an existing ID list segment?
      - How often can I call the endpoint that adds IDs to a segment?
      instructions:
      - text: Add IDs {ids} to ID list segment {id}.
        slots:
          ids: requestBody.ids
          id: path.id
      - text: Put {ids} into segment {id}'s ID list.
        slots:
          ids: requestBody.ids
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/id_list/reset'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace all IDs in an ID list segment
      effect: destructive
      questions:
      - Can I overwrite a segment's entire ID list with a new set?
      - Is resetting a large ID list atomic?
      instructions:
      - text: Reset segment {id} so its ID list is exactly {ids}.
        slots:
          id: path.id
          ids: requestBody.ids
      - text: Replace every ID in segment {id} with {ids}.
        slots:
          id: path.id
          ids: requestBody.ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/idlist_metadata'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an ID list segment's metadata
      effect: read
      questions:
      - What metadata is stored about a segment's ID list?
      - Can I check an ID list's metadata without downloading the IDs?
      instructions:
      - text: Get ID list metadata for segment {id}.
        slots:
          id: path.id
      - text: Show the metadata of segment {id}'s ID list.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/remove_ids'].patch
  update:
    x-apievangelist-phrasing:
      intent: Remove IDs from a User Store ID list segment
      effect: write
      questions:
      - Can I remove IDs from a segment stored in the User Store?
      - What is the per-request ID limit when removing from a User Store list?
      instructions:
      - text: Remove IDs {ids} from the User Store ID list of segment {id}.
        slots:
          ids: requestBody.ids
          id: path.id
      - text: Drop {ids} from User Store segment {id} at version {version}.
        slots:
          ids: requestBody.ids
          id: path.id
          version: requestBody.version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/reviews/{reviewID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel a segment review
      effect: destructive
      questions:
      - Can I withdraw a pending change review on a segment?
      - Is there a way to cancel a segment review nobody needs anymore?
      instructions:
      - text: Cancel review {reviewID} on segment {id}.
        slots:
          reviewID: path.reviewID
          id: path.id
      - text: Withdraw pending review {reviewID} for segment {id}.
        slots:
          reviewID: path.reviewID
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/segments/{id}/reviews/{reviewID}/commit'].put
  update:
    x-apievangelist-phrasing:
      intent: Commit an approved segment review
      effect: write
      questions:
      - Can I apply an approved review so the segment change takes effect?
      - What call commits a reviewed change to a segment?
      instructions:
      - text: Commit review {reviewID} on segment {id}.
        slots:
          reviewID: path.reviewID
          id: path.id
      - text: Apply the approved change from review {reviewID} to segment {id}.
        slots:
          reviewID: path.reviewID
          id: path.id
      method: generated
      generated: '2026-10-01'