Every API here is available over the APIs.io API and to AI agents over MCP.
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