Prompts

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

Authorization

string

required

Bearer token. Example: Bearer qw-api-xxx

GET /api/v1/brands/{brandId}/prompts

Path Parameters

brandId

string

required

The unique identifier of the brand

Query Parameters

period

number

Number of days to include (based on last generated date). If not specified, returns all data.

startDate

string

Start date (ISO 8601 format)

endDate

string

End date (ISO 8601 format)

topic

string

Filter by topic ID (keywordId). Supports comma-separated multi-select (e.g., id1,id2).

tag

string

Filter by tag ID. Supports comma-separated multi-select (e.g., id1,id2).

type

string

Filter by prompt type: TOFU, MOFU, BOFU

limit

number

default:"50"

Maximum number of prompts to return (max: 100)

offset

number

default:"0"

Pagination offset

sort

string

default:"lastGeneratedAt"

Field to sort by: lastGeneratedAt, answersCount, text, createdAt

order

string

default:"desc"

Sort order: asc or desc

include

string

Set to details to enrich each prompt with aggregated competitors, sources, brand mentions, and source stability metrics. When omitted, the response includes only the base fields listed below.

Response

success

boolean

Indicates if the request was successful

pagination

object

Show Pagination info

prompts

array

Show Prompt object

string

Prompt ID

text

string

Prompt text

topic

string

Associated topic name

type

string

Prompt type (TOFU/MOFU/BOFU)

Example Request

curl -X GET "https://www.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"
    }
  ]
}

Example with `include=details`

curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/prompts?include=details&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"

{
  "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",
      "competitors": [
        { "name": "My Brand", "mentions": 3, "relationship": "SELF" },
        { "name": "Competitor A", "mentions": 8, "relationship": "DIRECT" },
        { "name": "Competitor B", "mentions": 5, "relationship": "DIRECT" }
      ],
      "competitorsCount": 3,
      "competitorMentionsTotal": 16,
      "brandMentioned": true,
      "brandMentionCount": 3,
      "sources": [
        { "domain": "mybrand.com", "citations": 2, "isSelf": true },
        { "domain": "expert-reviews.com", "citations": 4, "isSelf": false },
        { "domain": "industry-news.com", "citations": 3, "isSelf": false }
      ],
      "sourcesCount": 3,
      "sourceCitationsTotal": 9,
      "sourceStability": 33.33,
      "createdAt": "2024-12-01T10:00:00.000Z"
    }
  ]
}

Get Prompt Details

GET /api/v1/brands/{brandId}/prompts/{promptId}

Path Parameters

brandId

string

required

The unique identifier of the brand

promptId

string

required

The unique identifier of the prompt

Query Parameters

include

string

Set to details to enrich the prompt with aggregated competitors, sources, brand mentions, and source stability metrics. When omitted, returns the base fields only.

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,
    "createdAt": "2024-12-01T10:00:00.000Z",
    "lastGeneratedAt": "2024-12-19T10:00:00.000Z"
  }
}

Example with `include=details`

{
  "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,
    "createdAt": "2024-12-01T10:00:00.000Z",
    "lastGeneratedAt": "2024-12-19T10:00:00.000Z",
    "competitors": [
      { "name": "My Brand", "mentions": 3, "relationship": "SELF" },
      { "name": "Competitor A", "mentions": 8, "relationship": "DIRECT" }
    ],
    "competitorsCount": 2,
    "competitorMentionsTotal": 11,
    "brandMentioned": true,
    "brandMentionCount": 3,
    "sources": [
      { "domain": "mybrand.com", "citations": 2, "isSelf": true },
      { "domain": "expert-reviews.com", "citations": 4, "isSelf": false }
    ],
    "sourcesCount": 2,
    "sourceCitationsTotal": 6,
    "sourceStability": 50.0
  }
}

Get Prompt Answers

Retrieve all AI-generated responses for a specific prompt.

GET /api/v1/brands/{brandId}/prompts/{promptId}/answers

Path Parameters

brandId

string

required

The unique identifier of the brand

promptId

string

required

The unique identifier of the prompt

Query Parameters

provider

string

Filter by AI provider. Supports comma-separated multi-select (e.g., chatgpt,claude).

Example Request

curl -X GET "https://www.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,
      "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,
      "createdAt": "2024-12-19T10:05:00.000Z"
    }
  ]
}

Get Prompt Evolution

Track how a prompt’s metrics change over time.

GET /api/v1/brands/{brandId}/prompts/{promptId}/evolution

Path Parameters

brandId

string

required

The unique identifier of the brand

promptId

string

required

The unique identifier of the prompt

Query Parameters

period

number

Number of days to include. If not specified, returns all data.

startDate

string

Start date (ISO 8601 format)

endDate

string

End date (ISO 8601 format)

provider

string

Filter by AI provider. Supports comma-separated multi-select (e.g., chatgpt,claude).

tag

string

Filter by tag ID. Supports comma-separated multi-select (e.g., id1,id2).

Example Request

curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/prompts/q1/evolution?period=7" \
  -H "Authorization: Bearer qw-api-your-token-here"

Example Response

{
  "success": true,
  "prompt": {
    "id": "q1",
    "text": "What are the best products in this category?"
  },
  "evolution": [
    {
      "date": "2024-12-01",
      "answers": 5,
      "mentionRate": 80.0,
      "sourceRate": 60.0,
      "avgSentiment": 78.5
    },
    {
      "date": "2024-12-02",
      "answers": 8,
      "mentionRate": 75.0,
      "sourceRate": 62.5,
      "avgSentiment": 80.1
    }
  ]
}

Error Responses

Status	Code	Description
400	`INVALID_PARAMETER`	Invalid query parameter
401	`INVALID_TOKEN`	Authentication failed
404	`BRAND_NOT_FOUND`	Brand doesn’t exist or not accessible
404	`PROMPT_NOT_FOUND`	Prompt doesn’t exist

Getting Started

Endpoints

Use Cases

List Prompts

Path Parameters

Query Parameters

Response

Example Request

Example Response

Example with `include=details`

Get Prompt Details

Path Parameters

Query Parameters

Response

Example Response

Example with `include=details`

Get Prompt Answers

Path Parameters

Query Parameters

Example Request

Example Response

Get Prompt Evolution

Path Parameters

Query Parameters

Example Request

Example Response

Error Responses

Getting Started

Endpoints

Use Cases

​List Prompts

​Path Parameters

​Query Parameters

​Response

​Example Request

​Example Response

​Example with include=details

​Get Prompt Details

​Path Parameters

​Query Parameters

​Response

​Example Response

​Example with include=details

​Get Prompt Answers

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​Get Prompt Evolution

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​Error Responses

List Prompts

Path Parameters

Query Parameters

Response

Example Request

Example Response

Example with `include=details`

Get Prompt Details

Path Parameters

Query Parameters

Response

Example Response

Example with `include=details`

Get Prompt Answers

Path Parameters

Query Parameters

Example Request

Example Response

Get Prompt Evolution

Path Parameters

Query Parameters

Example Request

Example Response

Error Responses