openapi: 3.2.0 info: title: V1 Prompts API version: v1 servers: - url: https://api.airops.com variables: defaultHost: default: api.airops.com tags: - name: Prompts x-parent: Brand Kits paths: /public_api/brand_kits/{brand_kit_id}/prompts/list: post: summary: List Prompts description: Questions are the AI prompts that can be asked about a brand. They are used to get AI answers with citations and mentions. tags: - Prompts operationId: listBrandKitsPrompts security: - bearer: [] responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: - integer - 'null' description: Unique identifier for the prompt text: type: - string - 'null' description: The prompt text keyword: type: - string - 'null' description: Associated keyword for the prompt brand_mentioned: type: - boolean - 'null' description: Whether the brand is mentioned in the prompt prompt_volume: type: - string - 'null' description: Prompt volume level enum: - very_low - low - medium - high - null search_volume: type: - number - 'null' description: Actual search volume behind the prompt_volume level topic_id: type: - integer - 'null' description: ID of the associated topic created_at: type: - string - 'null' description: When the prompt was created updated_at: type: - string - 'null' description: When the prompt was last updated mention_rate: type: - number - 'null' description: Percentage of AI answers mentioning the brand (0-100) positive_answer_rate: type: - number - 'null' description: Percentage of answers where your brand is positively mentioned, out of all answers where you have been mentioned and sentiment is determined citation_rate: type: - number - 'null' description: Percentage of AI answers citing the brand (0-100) mention_rate_trend: type: - number - 'null' description: Change in mention_rate vs previous period positive_answer_rate_trend: type: - number - 'null' description: Change in positive_answer_rate vs previous period citation_rate_trend: type: - number - 'null' description: Change in citation_rate vs previous period query_fanouts: type: - array - 'null' items: type: object description: Search queries the AI ran internally when answering this question. Each entry has text (the raw query), normalized_text (lowercase/trimmed), and observations_count (how many times it appeared — higher = stronger signal). Empty if query fanout capture is not enabled for your workspace or if we do not support it for this provider. countries: type: - array - 'null' items: type: string description: ISO alpha-2 country codes currently assigned to the prompt (live). persona_ids: type: - array - 'null' items: type: integer description: IDs of personas currently assigned to the prompt (live). Use `list_personas` to resolve to titles. platforms: type: - array - 'null' items: type: string description: AI platforms currently assigned to the prompt (live). est_answers_mo: type: - integer - 'null' description: Estimated monthly answer credits this prompt will consume given its current live country, persona, and platform assignments. topic: type: - object - 'null' description: Included topic - all model attributes tags: type: - array - 'null' description: Included tags collection (when requested via includes param) items: type: object meta: type: object properties: page: type: integer per_page: type: integer total_count: type: integer total_pages: type: integer required: - data - meta '400': description: Bad request - invalid parameters, filters, or sort options '401': description: Unauthorized - invalid or missing authentication token '404': description: Not found - resource does not exist '412': description: Precondition failed - AEO not configured for this brand kit parameters: - name: brand_kit_id in: path required: true schema: type: integer description: The Brand Kit ID requestBody: required: true content: application/json: schema: type: object properties: brand_kit_id: type: integer description: The ID of the Brand Kit tags: type: object description: 'Filter by tags. Object form { "operator": "IN" | "HAS_ALL" | "NOT_IN", "value": [tag ids] }. IN matches items tagged with ANY of the tags; HAS_ALL matches only items tagged with ALL; NOT_IN matches only items tagged with NONE.' properties: operator: type: string description: IN matches items tagged with ANY of the tags; HAS_ALL matches only items tagged with ALL of them; NOT_IN matches only items tagged with NONE of them. enum: - IN - HAS_ALL - NOT_IN value: type: array description: Tag IDs to filter by. items: type: integer required: - operator - value start_date: type: string description: Start date for metrics (ISO 8601). Defaults to 1 month ago. end_date: type: string description: End date for metrics (ISO 8601). Defaults to today. providers: type: array description: Filter metrics by AI providers items: type: string enum: - chat_gpt - gemini - perplexity - google_ai_mode - google_ai_overview - claude - grok - microsoft_copilot countries: type: array description: Filter metrics by country codes items: type: string enum: - AE - AR - AT - AU - BE - BR - CA - CH - CL - CN - CO - CZ - DE - DK - ES - FI - FR - GB - GR - HR - HU - ID - IE - IL - IN - IS - IT - JP - KR - MX - MY - NL - 'NO' - NZ - PE - PH - PL - PT - SE - SG - TH - TR - US - VN personas: type: array description: Filter metrics by persona IDs items: type: integer filters: type: array description: 'Filter results. Nested fields (e.g. `writing_rules.text`) filter within an included association and require that association in `includes`. **Available fields:** - **text** (EQUALS, CONTAINS): Filter by prompt text - **strategy** (EQ, IN): Filter by strategy: 0 = manual, 1 = deep_research - **brand_mentioned** (EQ): Filter by whether brand is mentioned - **topic_id** (EQ, IN): Filter by topic ID - **prompt_volume** (EQUALS, IN): Filter by prompt volume level - **mention_rate** (EQ, NEQ, GT, LT, GEQ, LEQ): Filter by mention rate percentage (0-100) - **positive_answer_rate** (EQ, NEQ, GT, LT, GEQ, LEQ): Filter by positive answer rate percentage (0-100) - **citation_rate** (EQ, NEQ, GT, LT, GEQ, LEQ): Filter by citation rate percentage (0-100) - **country** (EQ, IN): Filter prompts by an assigned country (ISO alpha-2). EQ matches a single code; IN matches any in the list. - **persona_id** (EQ, IN): Filter prompts by an assigned persona ID. Use `list_personas` to discover persona IDs. - **platform** (EQ, IN): Filter prompts by an assigned AI platform.' items: type: object properties: field: type: string enum: - text - strategy - brand_mentioned - topic_id - prompt_volume - mention_rate - positive_answer_rate - citation_rate - country - persona_id - platform description: 'Field to filter on. text: Filter by prompt text; strategy: Filter by strategy: 0 = manual, 1 = deep_research; brand_mentioned: Filter by whether brand is mentioned; topic_id: Filter by topic ID; prompt_volume: Filter by prompt volume level (values: very_low, low, medium, high); mention_rate: Filter by mention rate percentage (0-100); positive_answer_rate: Filter by positive answer rate percentage (0-100); citation_rate: Filter by citation rate percentage (0-100); country: Filter prompts by an assigned country (ISO alpha-2). EQ matches a single code; IN matches any in the list. (values: AE, AR, AT, AU, BE, BR, CA, CH, CL, CN, CO, CZ, DE, DK, ES, FI, FR, GB, GR, HR, HU, ID, IE, IL, IN, IS, IT, JP, KR, MX, MY, NL, NO, NZ, PE, PH, PL, PT, SE, SG, TH, TR, US, VN); persona_id: Filter prompts by an assigned persona ID. Use `list_personas` to discover persona IDs.; platform: Filter prompts by an assigned AI platform. (values: chat_gpt, gemini, perplexity, google_ai_mode, google_ai_overview, claude, grok, microsoft_copilot)' operator: type: string enum: - EQUALS - CONTAINS - EQ - IN - NEQ - GT - LT - GEQ - LEQ description: 'Filter operator. - **EQ/EQUALS**: Exact match - **NEQ**: Not equal - **GT/GEQ/LT/LEQ**: Numeric/date comparisons - **CONTAINS**: Partial text match - **STARTS_WITH**: Text prefix match - **IN**: Match any value in array - **HAS_ALL**: (tags filter) match only items having every listed value - **NOT_IN**: (tags filter) match only items having none of the listed values' value: description: Filter value (type depends on field and operator) required: - field - operator - value includes: type: array description: 'Include related resources. **Available includes:** - **topic**: Include the associated topic - **tags**: Include the associated tags' items: type: string enum: - topic - tags fields: type: array description: 'Select additional fields to return. **Optional fields:** - **id**: Unique identifier for the prompt - **text**: The prompt text - **keyword**: Associated keyword for the prompt - **brand_mentioned**: Whether the brand is mentioned in the prompt - **prompt_volume**: Prompt volume level - **search_volume**: Actual search volume behind the prompt_volume level - **topic_id**: ID of the associated topic - **created_at**: When the prompt was created - **updated_at**: When the prompt was last updated - **mention_rate**: Percentage of AI answers mentioning the brand (0-100) - **positive_answer_rate**: Percentage of answers where your brand is positively mentioned, out of all answers where you have been mentioned and sentiment is determined - **citation_rate**: Percentage of AI answers citing the brand (0-100) - **mention_rate_trend**: Change in mention_rate vs previous period - **positive_answer_rate_trend**: Change in positive_answer_rate vs previous period - **citation_rate_trend**: Change in citation_rate vs previous period - **query_fanouts**: Search queries the AI ran internally when answering this question. Each entry has text (the raw query), normalized_text (lowercase/trimmed), and observations_count (how many times it appeared — higher = stronger signal). Empty if query fanout capture is not enabled for your workspace or if we do not support it for this provider. - **countries**: ISO alpha-2 country codes currently assigned to the prompt (live). - **persona_ids**: IDs of personas currently assigned to the prompt (live). Use `list_personas` to resolve to titles. - **platforms**: AI platforms currently assigned to the prompt (live). - **est_answers_mo**: Estimated monthly answer credits this prompt will consume given its current live country, persona, and platform assignments.' items: type: string enum: - id - text - keyword - brand_mentioned - prompt_volume - search_volume - topic_id - created_at - updated_at - mention_rate - positive_answer_rate - citation_rate - mention_rate_trend - positive_answer_rate_trend - citation_rate_trend - query_fanouts - countries - persona_ids - platforms - est_answers_mo sort: type: string enum: - text - -text - created_at - -created_at - prompt_volume - -prompt_volume - mention_rate - -mention_rate - positive_answer_rate - -positive_answer_rate - citation_rate - -citation_rate description: 'Sort field. Prefix with - for descending. **Available sort fields:** - **text/-text**: Sort alphabetically by prompt text - **created_at/-created_at**: Sort by creation date - **prompt_volume/-prompt_volume**: Sort by prompt volume level - **mention_rate/-mention_rate**: Sort by mention rate - **positive_answer_rate/-positive_answer_rate**: Sort by positive answer rate - **citation_rate/-citation_rate**: Sort by citation rate' page: type: integer default: 1 description: Page number per_page: type: integer default: 25 maximum: 100 description: Items per page required: - brand_kit_id /public_api/brand_kits/{brand_kit_id}/prompts/{id}: get: summary: Get Prompt description: Questions are the AI prompts that can be asked about a brand. They are used to get AI answers with citations and mentions. tags: - Prompts operationId: getBrandKitsPrompt security: - bearer: [] responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: object properties: id: type: - integer - 'null' description: Unique identifier for the prompt text: type: - string - 'null' description: The prompt text keyword: type: - string - 'null' description: Associated keyword for the prompt brand_mentioned: type: - boolean - 'null' description: Whether the brand is mentioned in the prompt prompt_volume: type: - string - 'null' description: Prompt volume level enum: - very_low - low - medium - high - null search_volume: type: - number - 'null' description: Actual search volume behind the prompt_volume level topic_id: type: - integer - 'null' description: ID of the associated topic created_at: type: - string - 'null' description: When the prompt was created updated_at: type: - string - 'null' description: When the prompt was last updated mention_rate: type: - number - 'null' description: Percentage of AI answers mentioning the brand (0-100) positive_answer_rate: type: - number - 'null' description: Percentage of answers where your brand is positively mentioned, out of all answers where you have been mentioned and sentiment is determined citation_rate: type: - number - 'null' description: Percentage of AI answers citing the brand (0-100) mention_rate_trend: type: - number - 'null' description: Change in mention_rate vs previous period positive_answer_rate_trend: type: - number - 'null' description: Change in positive_answer_rate vs previous period citation_rate_trend: type: - number - 'null' description: Change in citation_rate vs previous period query_fanouts: type: - array - 'null' items: type: object description: Search queries the AI ran internally when answering this question. Each entry has text (the raw query), normalized_text (lowercase/trimmed), and observations_count (how many times it appeared — higher = stronger signal). Empty if query fanout capture is not enabled for your workspace or if we do not support it for this provider. countries: type: - array - 'null' items: type: string description: ISO alpha-2 country codes currently assigned to the prompt (live). persona_ids: type: - array - 'null' items: type: integer description: IDs of personas currently assigned to the prompt (live). Use `list_personas` to resolve to titles. platforms: type: - array - 'null' items: type: string description: AI platforms currently assigned to the prompt (live). est_answers_mo: type: - integer - 'null' description: Estimated monthly answer credits this prompt will consume given its current live country, persona, and platform assignments. topic: type: - object - 'null' description: Included topic - all model attributes tags: type: - array - 'null' description: Included tags collection (when requested via includes param) items: type: object required: - data '400': description: Bad request - invalid parameters, filters, or sort options '401': description: Unauthorized - invalid or missing authentication token '404': description: Not found - resource does not exist '412': description: Precondition failed - AEO not configured for this brand kit parameters: - name: brand_kit_id in: path required: true schema: type: integer description: The Brand Kit ID - name: id in: path required: true schema: type: integer description: The resource ID components: securitySchemes: bearer: type: http scheme: bearer