API Evangelist conversational phrasing for External Categories API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for External Categories API
  version: 1.0.0
extends: openapi/profound-categories-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: 12
- target: $.paths['/v1/org/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List the organization's categories
      effect: read
      questions:
      - Which tracking categories are set up for my organization?
      - Can I list categories for several organizations at once?
      instructions:
      - text: List all of my categories.
      - text: Show the categories belonging to organizations {organization_ids}.
        slots:
          organization_ids: query.organization_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/topics'].get
  update:
    x-apievangelist-phrasing:
      intent: List the topics in a category
      effect: read
      questions:
      - What topics are defined under one of my categories?
      - Where do I find topic IDs to filter a category's prompts by?
      instructions:
      - text: List the topics in category {category_id}.
        slots:
          category_id: path.category_id
      - text: Show me every topic configured for category {category_id}.
        slots:
          category_id: path.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List the prompt tags in a category
      effect: read
      questions:
      - What tags are used to label prompts in my category?
      - Can I get the tag IDs for a single category?
      instructions:
      - text: List the tags for category {category_id}.
        slots:
          category_id: path.category_id
      - text: Get every prompt tag defined in category {category_id}.
        slots:
          category_id: path.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/regions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the regions tracked in a category
      effect: read
      questions:
      - Which geographic regions does one of my categories track?
      - Can I find region IDs scoped to a single category?
      instructions:
      - text: List the regions for category {category_id}.
        slots:
          category_id: path.category_id
      - text: Which countries or regions are enabled in category {category_id}? List them.
        slots:
          category_id: path.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/citation-categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List citation buckets for a category
      effect: read
      questions:
      - How are cited sources grouped into buckets in my category?
      - Does a category have custom citation categories on top of the built-in ones?
      instructions:
      - text: List the citation categories for category {category_id}.
        slots:
          category_id: path.category_id
      - text: Show built-in and custom source buckets used by category {category_id}.
        slots:
          category_id: path.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/citation-tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom citation tags for a category
      effect: read
      questions:
      - What custom labels have we defined for cited sources in a category?
      - Can I see the citation tags my team created for one category?
      instructions:
      - text: List the custom citation tags in category {category_id}.
        slots:
          category_id: path.category_id
      - text: Get the source labels our team defined for citations in category {category_id}.
        slots:
          category_id: path.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/prompts'].get
  update:
    x-apievangelist-phrasing:
      intent: List prompts tracked in a category
      effect: read
      questions:
      - Which prompts are we tracking in a category?
      - Can I filter a category's prompts by topic, region, platform or persona?
      - Is it possible to list only disabled prompts?
      instructions:
      - text: List the prompts in category {category_id}.
        slots:
          category_id: path.category_id
      - text: Show prompts in category {category_id} with status {status} for topic {topic_id}.
        slots:
          category_id: path.category_id
          status: query.status
          topic_id: query.topic_id
      - text: Page through {limit} prompts in category {category_id} after cursor {cursor}.
        slots:
          category_id: path.category_id
          limit: query.limit
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/prompts'].post
  update:
    x-apievangelist-phrasing:
      intent: Add new prompts to a category
      effect: write
      questions:
      - How do I start tracking new prompts in a category?
      - Can I preview new prompts with a dry run before they're saved?
      - Will topics and tags I reference by name be created automatically?
      instructions:
      - text: Add these prompts {prompts} to category {category_id}.
        slots:
          prompts: requestBody.prompts
          category_id: path.category_id
      - text: Dry-run adding prompts {prompts} to category {category_id} (dry_run {dry_run}) without saving.
        slots:
          prompts: requestBody.prompts
          category_id: path.category_id
          dry_run: requestBody.dry_run
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/prompts'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit existing prompts in a category
      effect: write
      questions:
      - Can I change the wording or tags of prompts already in a category?
      - If I send new regions for an existing prompt, do they replace the old set?
      instructions:
      - text: Apply these edits {prompts} to existing prompts in category {category_id}.
        slots:
          prompts: requestBody.prompts
          category_id: path.category_id
      - text: Preview changing existing prompts {prompts} in category {category_id} with dry_run {dry_run}.
        slots:
          prompts: requestBody.prompts
          category_id: path.category_id
          dry_run: requestBody.dry_run
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/prompts/status'].patch
  update:
    x-apievangelist-phrasing:
      intent: Activate, disable or delete prompts
      effect: destructive
      questions:
      - How can I pause prompts so they stop running daily but keep their history?
      - What happens to historical data when I mark prompts as deleted?
      instructions:
      - text: Set prompts {prompt_ids} in category {category_id} to {status}.
        slots:
          prompt_ids: requestBody.prompt_ids
          category_id: path.category_id
          status: requestBody.status
      - text: Disable prompts {prompt_ids} in category {category_id} so they stop running.
        slots:
          prompt_ids: requestBody.prompt_ids
          category_id: path.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List the brands tracked in a category
      effect: read
      questions:
      - Which brands or assets are being compared within one category?
      - Can I get the asset IDs for a single category?
      instructions:
      - text: List the assets in category {category_id}.
        slots:
          category_id: path.category_id
      - text: Show the brands tracked under category {category_id}.
        slots:
          category_id: path.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/org/categories/{category_id}/personas'].get
  update:
    x-apievangelist-phrasing:
      intent: List the personas in a category
      effect: read
      questions:
      - Which audience personas are prompts run as in one category?
      - Can I fetch persona IDs for a specific category?
      instructions:
      - text: List the personas for category {category_id}.
        slots:
          category_id: path.category_id
      - text: Show the audience personas configured in category {category_id}.
        slots:
          category_id: path.category_id
      method: generated
      generated: '2026-10-01'