Documentation Index
Fetch the complete documentation index at: https://docs.get-spotlight.com/llms.txt
Use this file to discover all available pages before exploring further.
Spotlight MCP exposes 20 tools. Each tool calls the same backend as the REST API. Parameters use camelCase in MCP; REST paths use the standard URL structure documented in the API reference.
Context and discovery
| Tool | Description | REST equivalent |
|---|
get_organization_context | Organization plan and brand count. Call once per session. | GET /v1/organization/context |
get_brand_context | Brand targeting, prompt quota, schedule, and estimated next fetch. Requires brandId. | GET /v1/brands/{brandId}/context |
get_spotlight_usage_guide | Returns Markdown guidance for agents (prompt style, quotas, scheduling). | Built-in guide |
list_brands | All brands in the organization. | GET /v1/brands |
Brands, runs, and results
| Tool | Description | REST equivalent |
|---|
list_brand_runs | Historical analysis runs for a brand. Supports page, limit. | GET /v1/brands/{brandId}/runs |
get_run_results | Per-prompt results for a run. Optional includeAnswer, page, limit. | GET /v1/runs/{runId} |
get_brand_last_results | Latest run results for a brand. | GET /v1/brands/{brandId}/last/results |
get_run_stats | Aggregate metrics, topic breakdown, and top mentioned brands. | GET /v1/runs/{runId}/stats |
get_run_sources | Cited URLs grouped by domain for a run. | GET /v1/runs/{runId}/sources |
get_run_content_suggestions | AI content ideas for a run. Supports pagination. | GET /v1/runs/{runId}/content-suggestions |
Perception
| Tool | Description | REST equivalent |
|---|
get_brand_perception_prompts_responses | Perception prompts and scored responses. Optional runId. | GET /v1/brands/{brandId}/perception-prompts-responses |
get_run_perception_prompts_responses | Perception data for a specific run. | GET /v1/runs/{runId}/perception-prompts-responses |
add_perception_prompts | Add branded perception prompts with optional scoring logic. | POST /v1/brands/{brandId}/perception-prompts |
Topics and prompts (write)
| Tool | Description | REST equivalent |
|---|
batch_create_topics_and_prompts | Create multiple topics and prompts in one call. | POST /v1/brands/{brandId}/topics-prompts/batch |
create_topics | Create one or more topics. | POST /v1/brands/{brandId}/topics |
create_prompts_in_topic | Add prompts under an existing topic. Returns remaining slots. | POST /v1/topics/{topicId}/prompts |
delete_prompt | Delete a single prompt. Prefer delete_prompts for multiple. | POST /v1/prompts/batch-delete |
delete_prompts | Delete multiple prompts in one request. | POST /v1/prompts/batch-delete |
delete_topic | Delete a topic and all prompts under it. | DELETE /v1/topics/{topicId} |
get_brand_context
Required: brandId
Returns:
- Language and target market
- Prompt quota (
remainingSlots, limits)
- Topic and prompt counts
- Report schedule and
nextEstimatedScheduledFetchAt
Call this before creating or deleting prompts so the agent respects plan limits.
get_run_results / get_brand_last_results
Required: runId or brandId
Optional: includeAnswer (boolean, default false), page, limit (max 500)
Set includeAnswer: true only when you need raw LLM response text — responses can be large.
add_perception_prompts
Required: brandId, prompts (array)
Each prompt object:
| Field | Required | Description |
|---|
text | Yes | Perception prompt text (branded) |
propertyId | No | Perception property ID (defaults to Custom) |
scoringLogic | No | Object or string defining how to score |
goodScore / badScore | No | Shorthand score labels |
batch_create_topics_and_prompts
Required: brandId, topics (array)
Each topic may include an existing id or a new name, plus a prompts array. Every prompt must belong to a topic. Prompt limits are enforced.
Write tools return nextScheduledRunAt and a scheduling note — new prompts run on the next scheduled report, not immediately.
MCP clients can call tools/list (JSON-RPC) to retrieve the live tool catalog with JSON Schema input definitions. A GET request to the MCP endpoint returns server metadata:
curl -s "https://app.get-spotlight.com/api/mcp"
{
"name": "spotlight-org-api-mcp",
"protocol": "mcp",
"transport": "http",
"endpoint": "/functions/v1/org-api-mcp"
}
