Prompts are the questions Qwairy monitors across AI platforms. Each prompt is categorized by funnel stage (TOFU/MOFU/BOFU), tagged for organization, and linked to a topic. Track which prompts generate mentions and source citations for your brand.
See Entities for the complete Prompt object structure, and Topic / Tag for classification objects. List Prompts Bearer token. Example: Bearer qw-api-xxx
GET /api/v1/brands/{brandId}/prompts
Path Parameters The unique identifier of the brand
Query Parameters Number of days to include (based on last generated date)
Start date (ISO 8601 format)
End date (ISO 8601 format)
Filter by topic ID (keywordId)
Filter by prompt type: TOFU, MOFU, BOFU
Maximum number of prompts to return (max: 100)
sort
string
default: "lastGeneratedAt"
Field to sort by: lastGeneratedAt, answersCount, text, createdAt
Response Indicates if the request was successful
Total number of prompts matching filters
Number of prompts in this response
Prompt type (TOFU/MOFU/BOFU)
Number of generated answers
Last generation timestamp (ISO 8601)
Example Request curl -X GET "https://qwairy.co/api/v1/brands/cm1234567890abcdef/prompts?type=TOFU&limit=10" \ -H "Authorization: Bearer qw-api-your-token-here"
Example Response { "success" : true , "pagination" : { "total" : 156 , "count" : 1 , "limit" : 10 , "offset" : 0 }, "prompts" : [ { "id" : "q1" , "text" : "What are the best products in this category?" , "topic" : "Product Reviews" , "type" : "TOFU" , "tags" : [ "reviews" , "comparison" ], "answersCount" : 2 , "mentionRate" : 50.0 , "sourceRate" : 25.0 , "lastGeneratedAt" : "2024-12-19T10:00:00.000Z" } ] }
Get Prompt Details GET /api/v1/brands/{brandId}/prompts/{promptId}
Path Parameters The unique identifier of the brand
The unique identifier of the prompt
Response Returns detailed prompt information with aggregated metrics.
Example Response { "success" : true , "prompt" : { "id" : "q1" , "text" : "What are the best products in this category?" , "topic" : { "id" : "topic1" , "name" : "Product Reviews" }, "type" : "TOFU" , "tags" : [ { "id" : "tag1" , "name" : "reviews" }, { "id" : "tag2" , "name" : "comparison" } ], "answersCount" : 2 , "mentionRate" : 50.0 , "sourceRate" : 25.0 , "avgSentiment" : 78.5 , "avgRelevance" : 72.0 , "createdAt" : "2024-12-01T10:00:00.000Z" , "lastGeneratedAt" : "2024-12-19T10:00:00.000Z" } }
Get Prompt Answers Retrieve all AI-generated responses for a specific prompt.
GET /api/v1/brands/{brandId}/prompts/{promptId}/answers
Path Parameters The unique identifier of the brand
The unique identifier of the prompt
Query Parameters Example Request curl -X GET "https://qwairy.co/api/v1/brands/cm1234567890abcdef/prompts/q1/answers" \ -H "Authorization: Bearer qw-api-your-token-here"
Example Response { "success" : true , "prompt" : { "id" : "q1" , "text" : "What are the best products in this category?" }, "total" : 2 , "answers" : [ { "id" : "ans1" , "provider" : "ChatGPT" , "model" : "GPT-4o" , "text" : "Based on recent reviews and comparisons..." , "hasSelfMention" : true , "selfMentionPosition" : 3 , "hasSelfSource" : false , "competitorsMentioned" : [ "My Brand" , "Competitor A" , "Competitor B" ], "sourcesCited" : [ "industry-news.com" , "expert-reviews.com" ], "sentiment" : 82 , "relevance" : 75 , "createdAt" : "2024-12-19T10:00:00.000Z" }, { "id" : "ans2" , "provider" : "Perplexity" , "model" : "Sonar Large" , "text" : "According to expert reviews and user feedback..." , "hasSelfMention" : true , "selfMentionPosition" : 2 , "hasSelfSource" : true , "competitorsMentioned" : [ "My Brand" , "Competitor C" , "Competitor D" ], "sourcesCited" : [ "mybrand.com" , "consumer-reports.com" ], "sentiment" : 78 , "relevance" : 80 , "createdAt" : "2024-12-19T10:05:00.000Z" } ] }
Error Responses Status Code Description 400 INVALID_PARAMETERInvalid query parameter 401 INVALID_TOKENAuthentication failed 404 BRAND_NOT_FOUNDBrand doesn’t exist or not accessible 404 PROMPT_NOT_FOUNDPrompt doesn’t exist
