Waikay Brand Visibility API — Developer Documentation
Welcome! This guide shows you how to fetch your projects, track brand-visibility data (overview, sources, rankings, scores), and manage your tracked prompts programmatically.
Base URL
https://app.waikay.io or the one mentioned in your dashboard
Authentication
Your API key is available in the Waikay dashboard . Pass it as the key query parameter on every request:
Copy code
?key=YOUR_API_KEY
Alternatively, the API key may be passed via the X-API-Key HTTP header. Header-based auth is recommended for write operations (POST/PATCH/DELETE) to keep secrets out of server logs and URL history.
Resources & Endpoints
1) List Projects
Retrieve all projects you have access to.
GET /api/projects?key=YOUR_API_KEY
Query Parameters
Name Type Required Description
key string Yes Your API key.
Sample Request
Copy code
curl "https://app.waikay.io/api/projects?key=YOUR_API_KEY"
Sample Response
{
"code":"200","customer_id":1,"projects":[
{"project_id":20217,"project_url":"example1.com"},
{"project_id":20234,"project_url":"example2.com"},
{"project_id":20242,"project_url":"example3.com"}
]}
2) Track Brand Visibility - Project Level
Fetch brand-visibility data for a project, targeted to one of the sources: overview, sources, rankings, or scores.
GET /api/track?key=API_KEY&project=PROJECT_ID&source=overview|sources|rankings|scores
Query Parameters
Name Type Required Description
key string Yes Your API key. project integer Yes Project ID from List Projects . source enum Yes One of overview, sources, rankings, scores.
Overview (All prompts) — Sample Response
API Response includes the list of running prompts for this project and the list of topic reports/action plans available
{
"code": "200",
"project_id": 20242,
"prompt_id": null,
"source": "Overview",
"data": {
"meta": {
"exported_at_utc": "2025-10-01T14:32:50+00:00",
"window_current_days": 7,
"window_prev_days": 7
},
"prompts": [
{
"prompt_id": 41,
"prompt": "Recommend some entity SEO tools",
"created_at": "2025-06-11 12:16:27",
"current_week": {
"total": 9,
"per_model": [
{
"id": 100,
"name": "Gemini",
"count": 4
},
{
"id": 3,
"name": "chatGPT",
"count": 4
},
{
"id": 1,
"name": "Sonar",
"count": 0
},
{
"id": 5,
"name": "Claude",
"count": 1
}
]
},
"previous_week": {
"total": 8,
"per_model": [
{
"id": 100,
"name": "Gemini",
"count": 3
},
{
"id": 3,
"name": "chatGPT",
"count": 3
},
{
"id": 1,
"name": "Sonar",
"count": 0
},
{
"id": 5,
"name": "Claude",
"count": 2
}
]
},
"delta": 1
}
],
"topic_reports": [
{
"topic": "Topic 1",
"updated": "2025-08-18",
"url": "https://jscloud.net/wk/5f4123a7cbc9f9e4a29fc9117120f38d.json"
},
{
"topic": "Topic 2",
"updated": "2025-08-21",
"url": "https://jscloud.net/wk/ebb4902ff7dd69344b073277653c671b.json"
}
]
}
}
Rankings (All prompts) — Sample Response
{
"code": "200",
"project_id": 20242,
"project_url": "https://inlinks.com",
"prompt_id": null,
"source": "rankings",
"data": {
"prompt": {
"prompt_id": null,
"prompt_name": "All prompts",
"window_days": 30
},
"summary": {
"brand_occurrences_total": 1468,
"exported_at_utc": "2025-10-02T07:45:52+00:00"
},
"rankings": [
{
"rank": 1,
"brand_key": "semrush",
"brand_display_name": "Semrush",
"occurrences": 86,
"share_of_voice_percent": 6,
"is_project_brand": false
},
{
"rank": 2,
"brand_key": "surferseo",
"brand_display_name": "Surfer SEO",
"occurrences": 72,
"share_of_voice_percent": 5,
"is_project_brand": false
},
{
"rank": 3,
"brand_key": "inlinks",
"brand_display_name": "InLinks",
"occurrences": 68,
"share_of_voice_percent": 5,
"is_project_brand": true
}
]
}
}
Sources (All prompts) — Sample Response
{
"code": "200",
"project_id": 20242,
"project_url": "http://inlinks.com",
"prompt_id": null,
"source": "sources",
"data": {
"filters": {
"prompt_id": null,
"window_days": 30
},
"summary": {
"total_sources": 577,
"total_citations": 5037,
"total_urls": 927,
"exported_at_utc": "2025-10-02T07:49:22+00:00"
},
"sources": [
{
"source_key": "searchatlas.com",
"source_display_name": "searchatlas.com",
"citations": 165,
"models": {
"Sonar": 24,
"chatGPT": 11,
"Gemini": 85,
"Claude": 45
},
"urls": [
{
"url": "https://searchatlas.com/blog/automated-internal-linking/",
"citations": 68
},
{
"url": "https://searchatlas.com/blog/schema-markup-tools/",
"citations": 38
},
(...)
]
},
{
"source_key": "backlinko.com",
"source_display_name": "backlinko.com",
"citations": 153,
"models": {
"Sonar": 30,
"chatGPT": 5,
"Claude": 68,
"Gemini": 50
},
"urls": [
{
"url": "https://backlinko.com/best-free-seo-tools",
"citations": 74
},
{
"url": "https://backlinko.com/best-enterprise-seo-tools",
"citations": 16
},
(...)
]
}
]
}
}
AI Knowledge Scores (All topic reports - last 365 days) — Sample Response
{
"code": "200",
"project_id": 8888,
"project_url": "http://example.com",
"prompt_id": null,
"source": "scores",
"data": {
"summary": {
"exported_at_utc": "2025-11-20T13:26:11+00:00",
"window_days": 365,
},
"ai_knowledge_scores": {
"Topic 1": {
"gemini-grounded": {
"2025-09-09": 68,
"2025-10-09": 72,
"2025-11-07": 78
},
"sonar": {
"2025-09-09": 74,
"2025-10-09": 68,
"2025-11-07": 84
},
"chatGPT": {
"2025-09-09": 72,
"2025-10-09": 72,
"2025-11-07": 80
},
"gemini": {
"2025-09-09": 80,
"2025-10-09": 82,
"2025-11-07": 78
},
"claude": {
"2025-09-09": 62,
"2025-10-09": 78,
"2025-11-07": 98
}
},
"Brand overview": {
"sonar": {
"2025-09-09": 88,
"2025-10-09": 86,
"2025-11-07": 95
},
"chatGPT": {
"2025-09-09": 90,
"2025-10-09": 87,
"2025-11-07": 94
},
"gemini": {
"2025-09-09": 81,
"2025-10-09": 89,
"2025-11-07": 86
},
"claude": {
"2025-09-09": 89,
"2025-10-09": 96,
"2025-11-07": 93
},
"gemini-grounded": {
"2025-09-09": 94,
"2025-10-09": 88,
"2025-11-07": 86
}
}
}
}
}
3) Track Brand Visibility - Prompt level
Fetch brand-visibility data for a project, scoped to a specific prompt, and targeted to one of the sources: overview, sources, or rankings.
GET /api/track?key=API_KEY&project=PROJECT_ID&prompt=PROMPT_ID&source=overview|sources|rankings
Query Parameters
Name Type Required Description
key string Yes Your API key. project integer Yes Project ID from List Projects . source enum Yes One of overview, sources, rankings. prompt integer No Prompt ID. If omitted, results are aggregated at project level.
Behavior: Omit prompt → project-level. Include prompt → prompt-level.
Overview — Prompt level — Sample Response
{
"prompt_id":1055,
"prompt":"Tools for brand reputation management LLM",
"created_at":"2025-09-16 09:54:18",
"current_week":{"total":20,"per_model":[
{"id":100,"name":"Gemini","count":7},
{"id":3,"name":"chatGPT","count":7},
{"id":1,"name":"Sonar","count":2},
{"id":5,"name":"Claude","count":4}
]},
"previous_week":{"total":16,"per_model":[
{"id":100,"name":"Gemini","count":6},
{"id":3,"name":"chatGPT","count":6},
{"id":1,"name":"Sonar","count":2},
{"id":5,"name":"Claude","count":2}
]},
"delta":4
}
Rankings — Prompt level — Sample Response
{
"code": "200",
"project_id": 20522,
"prompt_id": 1055,
"source": "Rankings",
"data": {
"prompt": {
"prompt_id": 1055,
"prompt_name": "tools for brand reputation management LLM",
"window_days": 30
},
"summary": {
"brand_occurrences_total": 324,
"exported_at_utc": "2025-10-01T13:42:25+00:00"
},
"rankings": [
{
"rank": 1,
"brand_key": "waikay",
"brand_display_name": "Waikay",
"occurrences": 18,
"share_of_voice_percent": 6,
"is_project_brand": true
},
{
"rank": 2,
"brand_key": "brand24",
"brand_display_name": "Brand24",
"occurrences": 12,
"share_of_voice_percent": 4,
"is_project_brand": false
},
(...)
]
}
}
Sources — Prompt level — Sample Response
{
"code": "200",
"project_id": 20522,
"prompt_id": 1055,
"source": "Sources",
"data": {
"filters": {
"prompt_id": 1055,
"window_days": 30
},
"summary": {
"total_sources": 84,
"total_citations": 301,
"total_urls": 94,
"exported_at_utc": "2025-10-01T13:42:59+00:00"
},
"model_metadata": [],
"sources": [
{
"source_key": "designrush.com",
"source_display_name": "designrush.com",
"citations": 19,
"models": {
"Gemini": 8,
"chatGPT": 4,
"Claude": 7
},
"urls": [
{
"url": "https://www.designrush.com/agency/ai-companies/trends/tools-for-tracking-llm-brand-visibility",
"citations": 11
},
{
"url": "https://www.designrush.com/agency/reputation-management-companies/trends/ai-reputation-management",
"citations": 8
}
]
},
{
"source_key": "semrush.com",
"source_display_name": "semrush.com",
"citations": 19,
"models": {
"Gemini": 8,
"chatGPT": 4,
"Claude": 7
},
"urls": [
{
"url": "https://www.semrush.com/blog/llm-monitoring-tools/",
"citations": 17
},
{
"url": "https://www.semrush.com/blog/llm-optimization/",
"citations": 2
}
]
},
(...)
]
}
}
Prompt Management
The endpoints below let you manage your tracked prompts programmatically — useful for "config-as-code" workflows where you keep your prompt list in a file (e.g. prompts.yaml) and reconcile it with Waikay from a script.
Allowed model IDs
ID Model
1 Sonar API 3 chatGPT API 5 Claude API 100 Gemini API 101 AI Mode - scrapped 102 chatGPT - scrapped 103 Gemini - scrapped 104 Copilot - scrapped
Allowed frequencies
1 = daily, 2 = every 2 days, 7 = weekly
Active states
1 = running, 0 = paused, 2 = deleted (soft delete)
4) List Prompts
Retrieve all prompts defined for a project. Useful as the "read current state" half of a reconciler loop.
GET /api/prompts?key=API_KEY&project=PROJECT_ID
Query Parameters
Name Type Required Description
key string Yes Your API key. project integer Yes Project ID from List Projects . include_inactive integer No 1 to include paused prompts (active=0). Default: 1 (included).include_deleted integer No 1 to include soft-deleted prompts (active=2). Default: 0 (excluded).
Sample Request
Copy code
curl "https://app.waikay.io/api/prompts?key=YOUR_API_KEY&project=20242"
Sample Response
{
"code": "200",
"project_id": 20242,
"project_url": "example.com",
"count": 2,
"prompts": [
{
"prompt_id": 41,
"prompt_string": "Recommend some entity SEO tools",
"models": [1, 3, 5, 100],
"audience": 1,
"frequency": 7,
"active": 1,
"created_at": "2025-06-11 12:16:27"
},
{
"prompt_id": 58,
"prompt_string": "Best tools for brand reputation management",
"models": [3, 5],
"audience": 1,
"frequency": 2,
"active": 0,
"created_at": "2025-08-04 09:31:02"
}
]
}
5) Create Prompt
Create a new tracked prompt. The request body is JSON. The prompt starts in active=1 (running) state. Translation of non-English prompts to English happens automatically in the tracking pipeline; no need to translate beforehand.
POST /api/prompts?key=API_KEY&project=PROJECT_ID
Query Parameters
Name Type Required Description
key string Yes Your API key. project integer Yes Project ID.
Body Parameters (JSON)
Name Type Required Description
prompt_string string Yes The prompt text. Max 500 characters. Immutable after creation. models array<int> Yes Model IDs to track. Allowed values: 1, 3, 5, 100, 101, 102, 103, 104. audience integer No Audience identifier. Default 0. frequency integer Yes One of 1 (daily), 2 (twice weekly), 7 (weekly).
Sample Request
Copy code
curl -X POST "https://app.waikay.io/api/prompts?key=YOUR_API_KEY&project=20242" \
-H "Content-Type: application/json" \
-d '{
"prompt_string": "Best entity SEO tools",
"models": [3, 5, 100],
"audience": 1,
"frequency": 7
}'
Sample Response (201 Created)
{
"code": "201",
"project_id": 20242,
"prompt_id": 1234,
"prompt_string": "Best entity SEO tools",
"models": [3, 5, 100],
"audience": 1,
"frequency": 7,
"active": 1,
"created_at": "2025-11-20 09:14:22"
}
Insufficient Credits Response (402 Payment Required)
{
"ok": false,
"error": "Insufficient credits",
"credits_required": 12.4,
"credits_available": 3.2
}
Cost formula: (regular_models + cheap_models / 5) × multiplier, where multiplier is 30 (daily), 15 (twice weekly), or 4 (weekly). Regular models (IDs 1, 3, 5) cost 1 credit per call; cheap models (IDs 100–104) cost 0.2.
6) Update Prompt
Partially update an existing prompt. Send only the fields you want to change; omitted fields are left untouched. The prompt_string is immutable — to change a prompt's text, delete the prompt and create a new one (this preserves the analytical history attached to the original prompt ID).
PATCH /api/prompts?key=API_KEY&project=PROJECT_ID&prompt=PROMPT_ID
Query Parameters
Name Type Required Description
key string Yes Your API key. project integer Yes Project ID. prompt integer Yes ID of the prompt to update.
Body Parameters (JSON, all optional)
Name Type Description
models array<int> New list of model IDs. Models removed from the list are stopped; models re-added are reactivated; new models are added with fresh tracking rows. audience integer New audience identifier. frequency integer One of 1, 2, 7. active integer One of 0 (pause), 1 (run), 2 (delete). Note: DELETE /api/prompts is the more idiomatic way to delete.
Sending prompt_string in the body returns 400 — the field is immutable.
Sample Request
Copy code
curl -X PATCH "https://app.waikay.io/api/prompts?key=YOUR_API_KEY&project=20242&prompt=1234" \
-H "Content-Type: application/json" \
-d '{ "models": [3, 5, 100, 101], "frequency": 2 }'
Sample Response (200 OK)
{
"code": "200",
"project_id": 20242,
"prompt_id": 1234,
"prompt_string": "Best entity SEO tools",
"models": [3, 5, 100, 101],
"audience": 1,
"frequency": 2,
"active": 1,
"created_at": "2025-11-20 09:14:22"
}
7) Delete Prompt
Soft-delete a prompt. The prompt's active state is set to 2; tracking history is preserved in the database, and the worker stops executing the prompt. Deleting an already-deleted prompt is idempotent (returns 200 with no state change).
DELETE /api/prompts?key=API_KEY&project=PROJECT_ID&prompt=PROMPT_ID
Query Parameters
Name Type Required Description
key string Yes Your API key. project integer Yes Project ID. prompt integer Yes ID of the prompt to delete.
Sample Request
Copy code
curl -X DELETE "https://app.waikay.io/api/prompts?key=YOUR_API_KEY&project=20242&prompt=1234"
Sample Response (200 OK)
{
"code": "200",
"project_id": 20242,
"prompt_id": 1234,
"deleted": true,
"was_already_deleted": false
}
Error Responses
All errors are returned as JSON with an ok: false flag and a human-readable error message. The HTTP status code carries the primary signal.
Status Meaning
400 Bad request — missing or malformed parameters (e.g. invalid JSON body, unknown source, invalid frequency). 401 Unauthorized — missing, invalid, or inactive API key; or the project doesn't belong to the authenticated customer. 402 Payment required — insufficient credits (only on POST /api/prompts). 404 Not found — project or prompt doesn't exist. 405 Method not allowed — endpoint called with the wrong HTTP method. 500 Internal server error — database or upstream failure. Retry after a short delay. 502 Bad gateway — upstream tracking service unreachable (only on GET /api/track).
OpenAPI (YAML)
Copy code openapi: 3.0.3
info: { title: Waikay Brand Visibility API, version: 1.1.0 }
servers: [ { url: https://app.waikay.io } ]
paths:
/api/projects:
get:
parameters:
- { name: key, in: query, required: true, schema: { type: string } }
/api/track:
get:
parameters:
- { name: key, in: query, required: true, schema: { type: string } }
- { name: project, in: query, required: true, schema: { type: integer } }
- { name: prompt, in: query, required: false, schema: { type: integer } }
- { name: source, in: query, required: true, schema: { type: string, enum: [overview, sources, rankings, scores] } }
/api/prompts:
get:
parameters:
- { name: key, in: query, required: true, schema: { type: string } }
- { name: project, in: query, required: true, schema: { type: integer } }
- { name: include_inactive, in: query, required: false, schema: { type: integer, enum: [0, 1] } }
- { name: include_deleted, in: query, required: false, schema: { type: integer, enum: [0, 1] } }
post:
parameters:
- { name: key, in: query, required: true, schema: { type: string } }
- { name: project, in: query, required: true, schema: { type: integer } }
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [prompt_string, models, frequency]
properties:
prompt_string: { type: string, maxLength: 500 }
models: { type: array, items: { type: integer, enum: [1, 3, 5, 100, 101, 102, 103, 104] } }
audience: { type: integer }
frequency: { type: integer, enum: [1, 2, 7] }
patch:
parameters:
- { name: key, in: query, required: true, schema: { type: string } }
- { name: project, in: query, required: true, schema: { type: integer } }
- { name: prompt, in: query, required: true, schema: { type: integer } }
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
models: { type: array, items: { type: integer, enum: [1, 3, 5, 100, 101, 102, 103, 104] } }
audience: { type: integer }
frequency: { type: integer, enum: [1, 2, 7] }
active: { type: integer, enum: [0, 1, 2] }
delete:
parameters:
- { name: key, in: query, required: true, schema: { type: string } }
- { name: project, in: query, required: true, schema: { type: integer } }
- { name: prompt, in: query, required: true, schema: { type: integer } }
© Waikay — Brand Visibility API. Example data as provided.