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