API and MCP
REST API reference
Every endpoint of /api/v1 with its parameters, and curl examples for the main reads.
Base URL https://dash.botlum.com/api/v1. Every request needs Authorization: Bearer with an API key or a signed-in person's token. Responses
are JSON, except the CSV exports. The machine-readable OpenAPI 3.1 document is at https://dash.botlum.com/api/v1/openapi.json, and it
can be imported into Postman, Insomnia or a code generator.
Most reads take the dashboard's filters as query parameters: from and to (yyyy-MM-dd, up to 92 days),
and comma-separated engines, countries, languages, topics and tags, plus
branded.
List workspaces
GET /api/v1/workspaces
With an API key: the key's workspace. Signed in: every workspace you can open.
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces"List projects
GET /api/v1/workspaces/{workspaceSlug}/projects
Each project is a brand with its domains, other names and competitors. Archived projects are left out unless asked for.
| Parameter | In | Required | Meaning |
|---|---|---|---|
includeArchived | query | no |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects"Get a project
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}
| Parameter | In | Required | Meaning |
|---|---|---|---|
projectId | path | yes |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID"List the project's prompts
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/prompts
Every prompt with its text, country, language, status, topic and tags.
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/prompts"List the project's topics
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/topics
Topics group prompts; their order is the owners'.
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/topics"Visibility overview
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/visibility/overview
Visibility of the brand and its competitors over the range, with counts, the change against the previous range of the same length (null when the two are not comparable, with reasons), share of voice, sentiment and a per-engine breakdown.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/visibility/overview"Visibility by day
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/visibility/series
One point per day and engine, and per day across all engines, for one brand.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
brand | query | no | `project` (default) or `competitor:{id}`. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/visibility/series"Visibility by prompt, country or topic
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/visibility/matrix
Rows by prompt, country or topic, one cell per engine, with a daily line for each row.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
brand | query | no | `project` (default) or `competitor:{id}`. |
by | query | no | `prompt` (default), `country` or `topic`. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/visibility/matrix"Brands side by side
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/visibility/competitors
The brand and each competitor over the range, overall and per engine.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/visibility/competitors"Brands the answers name that the project does not track
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/visibility/discovered-brands
Most frequent first, with how many answers named each and on which engines.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/visibility/discovered-brands"One answer
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/prompts/{slotId}/answers/{engine}/{measuredFor}
The answer one engine gave to one prompt on one day (yyyy-MM-dd): its text, the sources it cited, the searches the engine ran, which brands it named and how, and where they stood on the results page.
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/prompts/PROMPT_ID/answers/chatgpt_search/2026-10-21"Searches the engines ran for a prompt
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/prompts/{slotId}/searches
The web searches engines reported running while answering this prompt.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/prompts/PROMPT_ID/searches"Cited domains
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/sources/domains
Domains the answers cite, how often, and for which brands.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/sources/domains"Cited pages
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/sources/pages
Pages the answers cite, how often, and for which brands.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/sources/pages"Source gap
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/sources/gap
Domains cited in answers that name competitors but not the brand: where to get mentioned.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/sources/gap"Answers citing a domain
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/sources/answers
The answers behind one cited domain or page.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
domain | query | no | The cited domain. |
page | query | no | A cited page, instead of a domain. |
gap | query | no | `true` for answers that name competitors but not the brand. |
limit | query | no | How many answers, at most. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/sources/answers"CSV export
GET /api/v1/workspaces/{workspaceSlug}/projects/{projectId}/export/{kind}.csv
`visibility`, `sources` or `brands` over the range, as the dashboard's CSV download.
| Parameter | In | Required | Meaning |
|---|---|---|---|
from | query | no | Required. First day, yyyy-MM-dd. |
to | query | no | Required. Last day, yyyy-MM-dd. A range covers at most 92 days. |
engines | query | no | Comma-separated engine keys, e.g. `chatgpt,gemini`. |
countries | query | no | Comma-separated ISO 3166-1 alpha-2 country codes. |
languages | query | no | Comma-separated language codes. |
topics | query | no | Comma-separated topic ids; `none` means prompts without a topic. |
tags | query | no | Comma-separated prompt tags; a prompt with any of them counts. |
branded | query | no | `true` for prompts that name the brand, `false` for the others. |
curl -H "Authorization: Bearer $BOTLUM_KEY" "https://dash.botlum.com/api/v1/workspaces/your-workspace/projects/PROJECT_ID/export/visibility.csv"