# Introduction Source: https://docs.rocketblue.ai/api-reference Pull rocketblue data into your own dashboards, scripts, and automations. ## What is the rocketblue API? The rocketblue API gives you programmatic access to the same brand intelligence data that powers the rocketblue app. Use it to integrate AI-visibility metrics, analysis runs, content suggestions, and perception scores into your own tooling. > [card] [Quickstart](/quickstart) > > Make your first API call in under 2 minutes. > [card] [Authentication](/authentication) > > Learn how to authenticate with API keys. > [card] [API Reference](/api-reference/discovery) > > Full reference for all endpoints. > [card] [MCP](/mcp-overview) > > Connect AI assistants via the Model Context Protocol. > [card] [Pagination](/pagination) > > Understand paging and limits. ## Base URL Every request starts with your organization's API base URL, found in **Settings → API** inside the app: ```text theme={null} https://app.rocketblue.ai/api ``` ## What you can do | Category | What you get | | - | - | | **Organization & brand context** | Plan, quotas, schedule, and targeting for your API key | | **Brands** | List all brands tracked in your organization | | **Runs** | Browse the history of analysis runs with aggregate metrics | | **Results** | Per-prompt presence, sentiment, rank, and (optionally) raw LLM responses | | **Created content** | Fetch saved content drafts created in the app | | **Content suggestions** | AI-generated content ideas derived from each run | | **Sources** | Domains and URLs that LLMs cited when analyzing your brand | | **Web search queries** | Queries used by LLM models during analysis | | **Perception** | Scored perception properties (trust, clarity, etc.) with LLM explanations | | **Topics & prompts** | Add, organize, and delete the prompts that drive your analysis | # Get brand context Source: https://docs.rocketblue.ai/api-reference/brands/context Return targeting, prompt quota, schedule, and estimated next fetch for a brand. Call this before creating prompts or interpreting limits for a brand. ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Request ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/context" ``` ### Response **brand** `object` Brand identity and targeting fields. **Brand** **organizationPlan** `string | null` Organization plan. **enabledFeatures** `object` Merged organization + brand feature flags. **promptQuota** `object | null` Remaining prompt slots and limits for the brand (and optional org-wide limit). **topicCount** `integer | null` Number of topics on the brand. **promptCount** `integer | null` Number of regular prompts on the brand. **reportSchedule** `object | null` Frequency, last run, and enabled LLMs. **lastAnalysisActivityAt** `string | null` ISO timestamp of the latest analysis activity. **nextEstimatedScheduledFetchAt** `string | null` Estimated next scheduled fetch time. Actual cron timing may differ slightly. ```json theme={null} { "brand": { "id": "brand-uuid-123", "name": "my-brand", "displayName": "My Brand", "targetMarket": "US SMB", "language": "en", "organizationId": "org-uuid-123" }, "organizationPlan": "growth", "promptQuota": { "remainingSlots": 42, "promptLimit": 100, "brandTotalPrompts": 58 }, "topicCount": 8, "promptCount": 50, "nextEstimatedScheduledFetchAt": "2026-08-04T00:00:00.000Z" } ``` # List brands Source: https://docs.rocketblue.ai/api-reference/brands/list GET /v1/brands Return all brands that belong to your organization. Brands are the top-level entities you track in rocketblue (e.g. your company or product lines). Call this endpoint first to discover available `brandId` values for use in other endpoints. ### Request ```bash cURL theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands" ``` ```python Python theme={null} import requests r = requests.get( "https://app.rocketblue.ai/api/v1/brands", headers={"x-api-key": "YOUR_API_KEY"}, ) brands = r.json()["data"] ``` ```javascript JavaScript theme={null} const r = await fetch("https://app.rocketblue.ai/api/v1/brands", { headers: { "x-api-key": "YOUR_API_KEY" }, }); const { data } = await r.json(); ``` ### Response **data** `Brand[]` Array of brand objects. **Brand object** **id** `string` Unique brand identifier — use this as `{brandId}` in other endpoints. **name** `string` Internal slug-style name. **displayName** `string` Human-readable label shown in the app. **targetMarket** `string | null` The audience this brand targets, e.g. `"US SMB"`. **language** `string` Primary language code, e.g. `"en"`. **count** `integer` Total number of brands returned. ```json theme={null} { "data": [ { "id": "brand-uuid-123", "name": "my-brand", "displayName": "My Brand", "targetMarket": "US SMB", "language": "en" } ], "count": 1 } ``` # Get latest content suggestions Source: https://docs.rocketblue.ai/api-reference/content-suggestions/get-latest-suggestions GET /v1/brands/{brandId}/last/content-suggestions Return content suggestions from the most recent run of a brand. Shortcut to the most recent run's content suggestions without needing to first look up the `runId`. Identical response shape to [Get content suggestions](/api-reference/content-suggestions/get-run-suggestions). ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Query parameters ### Request ```bash theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/last/content-suggestions" ``` ### Response Same shape as [Get content suggestions](/api-reference/content-suggestions/get-run-suggestions). > [!WARNING] > > Returns `404` if the brand has no analysis runs yet. # Get content suggestions Source: https://docs.rocketblue.ai/api-reference/content-suggestions/get-run-suggestions GET /v1/runs/{runId}/content-suggestions Return AI-generated content ideas for a specific run. Content suggestions are higher-level content ideas (article titles, descriptions, outlines) generated from a run. Use them to automatically populate content backlogs or feed ideas into editorial tools like Notion, Jira, or Trello. ### Path parameters **runId** `string` *required* Run UUID. Obtain from [List runs](/api-reference/runs/list). ### Query parameters **limit** `integer` (default: 20) Items per page. Maximum 500. **page** `integer` (default: 1) Page number (1-based). ### Request ```bash cURL theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/runs/RUN_ID/content-suggestions?limit=20&page=1" ``` ```python Python theme={null} import requests r = requests.get( "https://app.rocketblue.ai/api/v1/runs/RUN_ID/content-suggestions", headers={"x-spotlight-api-key": "YOUR_API_KEY"}, params={"limit": 20, "page": 1}, ) print(r.json()) ``` ### Response **run** `object` **Run** **data** `Suggestion[]` Array of content suggestions. **Suggestion object** **prompt** `object` **Prompt** **topic** `object` **Topic** **contentSuggestion** `object` **Content suggestion** ```json theme={null} { "run": { "id": "run-uuid-123", "brandId": "brand-uuid-123", "startedAt": "2025-02-01T10:00:00Z" }, "data": [ { "id": "suggestion-uuid-1", "runId": "run-uuid-123", "prompt": { "text": "What do customers say about our onboarding?", "estimatedVolume": 120 }, "topic": { "name": "Onboarding experience" }, "llms": ["chatgpt"], "contentSuggestion": { "title": "Guide: Make your first week with us effortless", "description": "A step-by-step onboarding guide that addresses the most common friction points." } } ], "paging": { "page": 1, "limit": 20, "total": 5, "nextPage": null } } ``` # Get created content Source: https://docs.rocketblue.ai/api-reference/created-content/get Get one created content draft, including the full markdown body. Returns the full draft plus schema suggestions, JSON-LD, and research sources when present. ### Path parameters **brandId** `string` *required* Brand UUID. **contentId** `string` *required* Created content UUID. Obtain from [List created content](/api-reference/created-content/list). ### Request ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/contents/CONTENT_ID" ``` ### Response **brandId** `string` Brand UUID. **data** `object` Full created-content payload. **Fields** ```json theme={null} { "brandId": "brand-uuid-123", "data": { "id": "content-uuid-123", "brandId": "brand-uuid-123", "title": "How to choose an AI visibility platform", "content": "# How to choose an AI visibility platform\n\n...", "excerpt": "A practical guide...", "format": "article", "createdAt": "2026-07-20T12:00:00.000Z", "suggestedSchemaTypes": [], "jsonLd": [], "researchSources": [], "prompt": { "id": "prompt-uuid-123", "text": "What should buyers look for in AI visibility tools?" } } } ``` # List created content Source: https://docs.rocketblue.ai/api-reference/created-content/list List created content drafts for a brand. Returns paginated draft metadata (title, excerpt, prompt, featured image). Use [Get created content](/api-reference/created-content/get) to fetch the full markdown body. ### Path parameters **brandId** `string` *required* Brand UUID. ### Query parameters **limit** `integer` (default: 100) Items per page. Maximum 500. **page** `integer` (default: 1) Page number (1-based). ### Request ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/contents?limit=50&page=1" ``` ### Response **brandId** `string` Brand UUID. **data** `CreatedContent[]` Draft metadata rows, newest first. **CreatedContent object** **prompt** `object` Linked prompt id/text when available. **paging** `object` Standard paging object. See [Pagination](/pagination). ```json theme={null} { "brandId": "brand-uuid-123", "data": [ { "id": "content-uuid-123", "brandId": "brand-uuid-123", "title": "How to choose an AI visibility platform", "excerpt": "A practical guide...", "format": "article", "createdAt": "2026-07-20T12:00:00.000Z", "prompt": { "id": "prompt-uuid-123", "text": "What should buyers look for in AI visibility tools?" } } ], "paging": { "page": 1, "limit": 50, "total": 12, "nextPage": null } } ``` # Discovery Source: https://docs.rocketblue.ai/api-reference/discovery Verify connectivity and enumerate available endpoints. Returns the API version, your organization ID, and the full list of available endpoint paths. Call this first to confirm your key and base URL are correct. ### Request ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/" ``` ### Response **message** `string` A friendly label — always `"rocketblue Data API"`. **version** `string` Current API version string, e.g. `"v1"`. **organizationId** `string` The organization UUID linked to the API key you sent. **endpoints** `array` List of all available routes. Each item has: * `method` — HTTP verb (`GET`, `POST`, `PATCH`, `DELETE`) * `path` — URL path template ```json theme={null} { "message": "rocketblue Data API", "version": "v1", "organizationId": "00000000-0000-0000-0000-000000000000", "endpoints": [ { "method": "GET", "path": "/v1/organization/context" }, { "method": "GET", "path": "/v1/brands/{brandId}/context" }, { "method": "GET", "path": "/v1/brands" }, { "method": "GET", "path": "/v1/brands/{brandId}/contents" }, { "method": "GET", "path": "/v1/brands/{brandId}/contents/{contentId}" }, { "method": "GET", "path": "/v1/brands/{brandId}/runs" }, { "method": "GET", "path": "/v1/runs/{runId}/stats" }, { "method": "GET", "path": "/v1/brands/{brandId}/last/results" }, { "method": "GET", "path": "/v1/brands/{brandId}/last/content-suggestions" }, { "method": "GET", "path": "/v1/brands/{brandId}/last/sources" }, { "method": "GET", "path": "/v1/brands/{brandId}/last/perception-sources" }, { "method": "GET", "path": "/v1/brands/{brandId}/last/perception" }, { "method": "GET", "path": "/v1/runs/{runId}" }, { "method": "GET", "path": "/v1/runs/{runId}/content-suggestions" }, { "method": "GET", "path": "/v1/runs/{runId}/sources" }, { "method": "GET", "path": "/v1/runs/{runId}/web-search-queries" }, { "method": "GET", "path": "/v1/brands/{brandId}/web-search-queries" }, { "method": "GET", "path": "/v1/brands/{brandId}/last/web-search-queries" }, { "method": "GET", "path": "/v1/runs/{runId}/perception-sources" }, { "method": "GET", "path": "/v1/runs/{runId}/perception" }, { "method": "GET", "path": "/v1/brands/{brandId}/perception" }, { "method": "GET", "path": "/v1/brands/{brandId}/perception-prompts-responses" }, { "method": "GET", "path": "/v1/runs/{runId}/perception-prompts-responses" }, { "method": "POST", "path": "/v1/brands/{brandId}/topics-prompts/batch" }, { "method": "POST", "path": "/v1/brands/{brandId}/topics" }, { "method": "POST", "path": "/v1/topics/{topicId}/prompts" }, { "method": "POST", "path": "/v1/brands/{brandId}/perception-prompts" }, { "method": "POST", "path": "/v1/perception-prompts/batch-update" }, { "method": "POST", "path": "/v1/prompts/batch-delete" }, { "method": "POST", "path": "/v1/prompts/batch-update" }, { "method": "POST", "path": "/v1/prompts/move-to-topic" }, { "method": "POST", "path": "/v1/topics/batch-update" }, { "method": "PATCH", "path": "/v1/topics/{topicId}" }, { "method": "DELETE", "path": "/v1/prompts/{promptId}" }, { "method": "DELETE", "path": "/v1/topics/{topicId}" } ] } ``` # Get organization context Source: https://docs.rocketblue.ai/api-reference/organization/context Return organization-level plan and brand count for the authenticated API key. Use this once per session to understand the organization scope tied to your API key. ### Request ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/organization/context" ``` ### Response **organizationId** `string` Organization UUID linked to the API key. **name** `string` Organization name. **plan** `string | null` Current plan identifier. **agency** `boolean | null` Whether this organization is an agency account. **enabledFeatures** `object` Feature flags and limits for the organization. **brandCount** `integer` Number of brands in the organization. ```json theme={null} { "organizationId": "org-uuid-123", "name": "Acme Inc", "plan": "growth", "agency": false, "enabledFeatures": {}, "brandCount": 3 } ``` # Get brand perception Source: https://docs.rocketblue.ai/api-reference/perception/get-brand-perception GET /v1/brands/{brandId}/perception Return perception prompts and scored responses for a brand. Perception prompts are questions like *"How trustworthy does this brand appear?"* that are sent to multiple LLMs. Each response includes a numeric score and reasoning. Use this endpoint to: * Build NPS-style perception dashboards per property * Compare how different LLMs score and describe the same trait * Feed perception metrics into BI tools or internal reports ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Query parameters **runId** `string` Target a specific run. If omitted, the most recent run is used. ### Request ```bash cURL — latest run theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/perception" ``` ```bash cURL — specific run theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/perception?runId=RUN_ID" ``` ```python Python theme={null} import requests r = requests.get( "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/perception", headers={"x-spotlight-api-key": "YOUR_API_KEY"}, params={"runId": "RUN_ID"}, # optional ) print(r.json()) ``` ### Response **run** `object | null` The run these responses are tied to, or `null` if no run was found. **Run** **data** `PerceptionPrompt[]` Array of perception prompts with responses. **PerceptionPrompt object** **responses** `PerceptionResponse[]` One response per LLM (latest per LLM if multiple runs). **PerceptionResponse object** ```json theme={null} { "brandId": "brand-uuid-123", "run": { "id": "run-uuid-123", "startedAt": "2025-02-01T10:00:00Z" }, "data": [ { "id": "perception-prompt-uuid-1", "propertyId": "Trust", "promptText": "On a scale from 0 to 10, how trustworthy does this brand appear?", "scoringLogic": "0-6: detractor, 7-8: passive, 9-10: promoter", "createdAt": "2025-01-15T09:00:00Z", "responses": [ { "id": "response-uuid-1", "llm": "chatgpt", "response": "Customers generally see the brand as trustworthy, but some mention confusing pricing.", "score": 8.5, "scoreReason": "Mostly positive trust signals with a few concerns.", "isUserChanged": false, "createdAt": "2025-02-01T10:05:00Z" } ] } ] } ``` # Get perception prompts & responses (brand) Source: https://docs.rocketblue.ai/api-reference/perception/get-brand-perception-prompts-responses GET /v1/brands/{brandId}/perception-prompts-responses Return all perception prompts and their scored responses for a brand, optionally scoped to a run. Returns perception prompts and all associated LLM responses for a brand. Defaults to the most recent run if `runId` is not provided. ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Query parameters **runId** `string` Target a specific run. If omitted, the most recent run is used. ### Request ```bash theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/perception-prompts-responses?runId=RUN_ID" ``` ### Response Same shape as [Get brand perception](/api-reference/perception/get-brand-perception). # Get latest perception Source: https://docs.rocketblue.ai/api-reference/perception/get-latest-perception GET /v1/brands/{brandId}/last/perception Return perception data from the most recent run of a brand. Shortcut to the latest run's perception data without needing to look up the `runId`. Identical response shape to [Get brand perception](/api-reference/perception/get-brand-perception). ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Request ```bash theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/last/perception" ``` ### Response Same shape as [Get brand perception](/api-reference/perception/get-brand-perception). > [!WARNING] > > Returns `404` if the brand has no analysis runs yet. # Get latest perception sources Source: https://docs.rocketblue.ai/api-reference/perception/get-latest-perception-sources GET /v1/brands/{brandId}/last/perception-sources Return perception sources from the most recent run of a brand. Shortcut to the latest run's perception sources. Identical response shape to [Get perception sources](/api-reference/perception/get-run-perception-sources). ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Request ```bash theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/last/perception-sources" ``` ### Response Same shape as [Get perception sources](/api-reference/perception/get-run-perception-sources). > [!WARNING] > > Returns `404` if the brand has no analysis runs yet. # Get run perception Source: https://docs.rocketblue.ai/api-reference/perception/get-run-perception GET /v1/runs/{runId}/perception Return perception data for a specific run. Returns the same perception data as [Get brand perception](/api-reference/perception/get-brand-perception), but addressed by `runId` rather than `brandId + runId`. Useful when you already have the run ID. ### Path parameters **runId** `string` *required* Run UUID. Obtain from [List runs](/api-reference/runs/list). ### Request ```bash theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/runs/RUN_ID/perception" ``` ### Response Same shape as [Get brand perception](/api-reference/perception/get-brand-perception). # Get perception prompts & responses (run) Source: https://docs.rocketblue.ai/api-reference/perception/get-run-perception-prompts-responses GET /v1/runs/{runId}/perception-prompts-responses Return all perception prompts and their scored LLM responses for a specific run. Returns each perception prompt alongside every LLM's scored response for the given run. Useful when you need a flat view of prompt + response pairs tied to a specific run ID. ### Path parameters **runId** `string` *required* Run UUID. Obtain from [List runs](/api-reference/runs/list). ### Request ```bash theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/runs/RUN_ID/perception-prompts-responses" ``` ### Response Same shape as [Get brand perception](/api-reference/perception/get-brand-perception). # Get perception sources Source: https://docs.rocketblue.ai/api-reference/perception/get-run-perception-sources GET /v1/runs/{runId}/perception-sources Return URLs cited in perception responses for a specific run, grouped by domain. Perception sources are the external URLs that LLMs referenced when generating perception scores. They are grouped by domain and sorted by response count — like [Get run sources](/api-reference/sources/get-run-sources), but specific to the perception layer. In addition to topics and LLMs, each domain group lists the **perception properties** (e.g. `"Trust"`, `"Ease of use"`) that those sources contributed to. ### Path parameters **runId** `string` *required* Run UUID. Obtain from [List runs](/api-reference/runs/list). ### Request ```bash theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/runs/RUN_ID/perception-sources" ``` ### Response **run** `object` **Run** **data** `DomainGroup[]` Domains sorted by `responseCount` descending. **DomainGroup object** **links** `Link[]` **Link** ```json theme={null} { "run": { "id": "run-uuid-123", "brandId": "brand-uuid-123", "startedAt": "2025-02-01T10:00:00Z", "completedAt": "2025-02-01T11:00:00Z" }, "data": [ { "domain": "reviews.example.com", "urlCount": 2, "responseCount": 6, "properties": ["Trust", "Ease of use"], "llms": ["chatgpt"], "links": [ { "uri": "https://reviews.example.com/post-1", "type": "review", "responseCount": 4 } ] } ] } ``` # Get latest results Source: https://docs.rocketblue.ai/api-reference/results/get-latest-results GET /v1/brands/{brandId}/last/results Return per-prompt results for the most recent run of a brand. Shortcut to the most recent run's results without needing to first look up the `runId`. Identical response shape to [Get run results](/api-reference/results/get-run-results). ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Query parameters **include\_answer** `boolean` (default: false) Include full LLM response text in each result. **limit** `integer` (default: 50) Items per page. Maximum 500. **page** `integer` (default: 1) Page number (1-based). ### Request ```bash theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/last/results" ``` ### Response Same shape as [Get run results](/api-reference/results/get-run-results). > [!WARNING] > > Returns `404` if the brand has no analysis runs yet. # Get run results Source: https://docs.rocketblue.ai/api-reference/results/get-run-results GET /v1/runs/{runId} Return per-prompt analysis results for a specific run. Returns one record per prompt/LLM combination: presence, sentiment, rank, mentioned brands, and optionally the full LLM response text. ### Path parameters **runId** `string` *required* Run UUID. Obtain from [List runs](/api-reference/runs/list). ### Query parameters **include\_answer** `boolean` (default: false) Set to `true` to include the raw LLM response text in each result. Significantly increases response size. **limit** `integer` (default: 50) Items per page. Maximum 500. **page** `integer` (default: 1) Page number (1-based). ### Request ```bash cURL theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/runs/RUN_ID?include_answer=false&limit=50&page=1" ``` ```python Python theme={null} import requests r = requests.get( "https://app.rocketblue.ai/api/v1/runs/RUN_ID", headers={"x-spotlight-api-key": "YOUR_API_KEY"}, params={"include_answer": "false", "limit": 50, "page": 1}, ) print(r.json()) ``` ```javascript JavaScript theme={null} const url = new URL("https://app.rocketblue.ai/api/v1/runs/RUN_ID"); url.searchParams.set("include_answer", "false"); url.searchParams.set("limit", "50"); const r = await fetch(url, { headers: { "x-spotlight-api-key": "YOUR_API_KEY" }, }); const json = await r.json(); ``` ### Response **run** `object` Basic run metadata. **Run** **data** `Result[]` Per-prompt analysis results. **Result object** **prompt** `object` **Prompt** **topic** `object` **Topic** ```json theme={null} { "run": { "id": "run-uuid-123", "brandId": "brand-uuid-123", "startedAt": "2025-02-01T10:00:00Z" }, "data": [ { "id": "result-uuid-1", "runId": "run-uuid-123", "prompt": { "text": "What do customers say about pricing?", "journeyStage": "consideration" }, "topic": { "name": "Pricing" }, "llm": "chatgpt", "isPresent": true, "rank": 1, "sentiment": "positive", "mentionedBrands": ["competitor-x"] } ], "paging": { "page": 1, "limit": 50, "total": 200, "nextPage": 2 }, "includeAnswer": false } ``` # List runs Source: https://docs.rocketblue.ai/api-reference/runs/list GET /v1/brands/{brandId}/runs List analysis runs for a brand with aggregate metrics. An **analysis run** is a complete processing pass for a brand: collecting LLM responses, scoring presence and sentiment, and computing summary metrics. Use this endpoint to build a run history picker, or to check the latest aggregate stats before diving into per-prompt results. ### Path parameters **brandId** `string` *required* The brand UUID. Obtain it from [List brands](/api-reference/brands/list). ### Query parameters **limit** `integer` (default: 10) Items per page. Maximum 500. **page** `integer` (default: 1) Page number (1-based). ### Request ```bash cURL theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/runs?limit=10&page=1" ``` ```python Python theme={null} import requests r = requests.get( "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/runs", headers={"x-spotlight-api-key": "YOUR_API_KEY"}, params={"limit": 10, "page": 1}, ) print(r.json()) ``` ```javascript JavaScript theme={null} const r = await fetch( "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/runs?limit=10&page=1", { headers: { "x-spotlight-api-key": "YOUR_API_KEY" } } ); const json = await r.json(); ``` ### Response **data** `Run[]` Array of run objects. **Run object** **id** `string` Run UUID — use as `{runId}` in other endpoints. **startedAt** `string (ISO 8601)` When the run began. **metrics** `object` Aggregate statistics for the run. **paging** `Paging` See [Pagination](/pagination). ```json theme={null} { "data": [ { "id": "run-uuid-123", "startedAt": "2025-02-01T10:00:00Z", "metrics": { "present": 120, "positive": 80, "negative": 20, "neutral": 20, "responsesWithBrands": 100, "totalResponses": 150, "completedResponses": 150, "averageRank": 1.8, "topics": null, "calculatedAt": "2025-02-01T10:30:00Z" } } ], "paging": { "page": 1, "limit": 10, "total": 3, "nextPage": null } } ``` > [!NOTE] > > If a completed run has not had its metrics calculated yet, the API triggers an automatic refresh and returns updated metrics. You always receive accurate numbers. # Get run stats Source: https://docs.rocketblue.ai/api-reference/runs/stats GET /v1/runs/{runId}/stats Return aggregate statistics for a specific run. Returns the same metrics object available in the runs list, but for a single run by ID. Useful when you already know the `runId` and want metrics without fetching the full list. ### Path parameters **runId** `string` *required* The run UUID. Obtain it from [List runs](/api-reference/runs/list). ### Request ```bash theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/runs/RUN_ID/stats" ``` ### Response **metrics** `object` See the metrics schema in [List runs](/api-reference/runs/list). ```json theme={null} { "id": "run-uuid-123", "brandId": "brand-uuid-123", "startedAt": "2025-02-01T10:00:00Z", "metrics": { "present": 120, "positive": 80, "negative": 20, "neutral": 20, "responsesWithBrands": 100, "totalResponses": 150, "completedResponses": 150, "averageRank": 1.8, "mentionedBrandsRun": { "competitor-x": 45, "competitor-y": 30 }, "topics": { "Pricing": { "present": 40, "positive": 30 }, "Support": { "present": 30, "negative": 5 } }, "calculatedAt": "2025-02-01T10:30:00Z" } } ``` # Get latest sources Source: https://docs.rocketblue.ai/api-reference/sources/get-latest-sources GET /v1/brands/{brandId}/last/sources Return sources from the most recent run of a brand. Shortcut to the most recent run's sources without needing to first look up the `runId`. Identical response shape to [Get run sources](/api-reference/sources/get-run-sources). ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Request ```bash theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/last/sources" ``` ### Response Same shape as [Get run sources](/api-reference/sources/get-run-sources). > [!WARNING] > > Returns `404` if the brand has no analysis runs yet. # Get run sources Source: https://docs.rocketblue.ai/api-reference/sources/get-run-sources GET /v1/runs/{runId}/sources Return the URLs that LLMs cited during a specific run, grouped by domain. Sources answer the question: **"Where did this information come from?"** They are the external URLs that LLMs referenced when analyzing your brand. Results are grouped by domain and sorted by number of responses. Use this data to: * Identify which websites most influence your brand's AI visibility * Find high-impact pages to update or promote * Build source attribution dashboards ### Path parameters **runId** `string` *required* Run UUID. Obtain from [List runs](/api-reference/runs/list). ### Request ```bash cURL theme={null} curl -s \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/runs/RUN_ID/sources" ``` ```python Python theme={null} import requests r = requests.get( "https://app.rocketblue.ai/api/v1/runs/RUN_ID/sources", headers={"x-spotlight-api-key": "YOUR_API_KEY"}, ) print(r.json()) ``` ### Response **run** `object` **Run** **data** `DomainGroup[]` Domains sorted by `responseCount` descending. **DomainGroup object** **links** `Link[]` Individual URLs under this domain. **Link object** ```json theme={null} { "run": { "id": "run-uuid-123", "brandId": "brand-uuid-123", "startedAt": "2025-02-01T10:00:00Z" }, "data": [ { "domain": "example.com", "urlCount": 3, "responseCount": 12, "topics": ["Pricing", "Support"], "llms": ["chatgpt", "gemini"], "links": [ { "uri": "https://example.com/blog/post-1", "type": "article", "responseCount": 7 }, { "uri": "https://example.com/reviews", "type": "review", "responseCount": 5 } ] } ] } ``` # Batch create topics & prompts Source: https://docs.rocketblue.ai/api-reference/topics-prompts/batch-create POST /v1/brands/{brandId}/topics-prompts/batch Create multiple topics and prompts in a single request. The recommended way to add prompts. One call can create new topics, add prompts to those new topics, and also add prompts to existing topics — all at once. ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Request body **topics** `TopicInput[]` *required* Array of topics. Each topic can be new (provide `name`) or existing (provide `id`). **TopicInput — new topic** **TopicInput — existing topic** **PromptInput** ### Request ```bash cURL theme={null} curl -s -X POST \ -H "x-spotlight-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "topics": [ { "name": "Pricing", "prompts": [ { "text": "How does the pricing compare to alternatives?", "customerJourney": "consideration" }, { "text": "Is there a free tier available?" } ] }, { "id": "existing-topic-uuid", "prompts": [ { "text": "What do customers say about support response times?" } ] } ] }' \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/topics-prompts/batch" ``` ```python Python theme={null} import requests payload = { "topics": [ { "name": "Pricing", "prompts": [ {"text": "How does the pricing compare to alternatives?", "customerJourney": "consideration"}, ], }, { "id": "existing-topic-uuid", "prompts": [{"text": "What do customers say about support?"}], }, ] } r = requests.post( "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/topics-prompts/batch", headers={"x-spotlight-api-key": "YOUR_API_KEY"}, json=payload, ) print(r.json()) ``` ### Response ```json theme={null} { "topics": [ { "id": "new-topic-uuid", "name": "Pricing", "prompts": [] } ], "remainingSlots": 87, "promptLimit": 100, "orgWideLimit": 500, "orgTotalPrompts": 413 } ``` ### Errors `409` — prompt limit exceeded: ```json theme={null} { "message": "Prompt limit exceeded", "code": "prompt_limit_exceeded", "remainingSlots": 0, "promptLimit": 100, "orgWideLimit": 500, "orgTotalPrompts": 500 } ``` # Batch delete prompts Source: https://docs.rocketblue.ai/api-reference/topics-prompts/batch-delete-prompts Delete multiple prompts in one request. Prefer this over repeated [Delete prompt](/api-reference/topics-prompts/delete-prompt) calls when removing more than one prompt. ### Request body **promptIds** `string[]` *required* Non-empty array of prompt UUIDs to delete. ### Request ```bash theme={null} curl -s -X POST \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"promptIds":["PROMPT_ID_1","PROMPT_ID_2"]}' \ "https://app.rocketblue.ai/api/v1/prompts/batch-delete" ``` ### Response **deletedPromptIds** `string[]` Prompt IDs that were deleted. **deletedCount** `integer` Number of prompts deleted. **brandIds** `string[]` Brands affected by the deletion. **brandId** `string | null` Present when all deleted prompts belonged to a single brand. **remainingSlots** `integer | null` Remaining slots for the single brand case. **remainingSlotsByBrand** `object` Remaining slots keyed by brand ID. ```json theme={null} { "deletedPromptIds": ["prompt-uuid-1", "prompt-uuid-2"], "deletedCount": 2, "brandIds": ["brand-uuid-123"], "brandId": "brand-uuid-123", "remainingSlots": 90, "remainingSlotsByBrand": { "brand-uuid-123": 90 } } ``` # Batch update prompts Source: https://docs.rocketblue.ai/api-reference/topics-prompts/batch-update-prompts Update journey stage and/or text on multiple prompts in one request. Use this to set **customer journey stage** or **prompt text** on many prompts at once. Prefer a single call with `promptIds` when applying the same values to all prompts; use `prompts[]` when each prompt needs different values. ### Request body Provide **either** `prompts[]` **or** `promptIds` (at least one must be present). **prompts** `PromptUpdate[]` Per-prompt patches. Each item must include `id` and at least one of `text` or `customerJourney`. **PromptUpdate** **id** `string` *required* Prompt UUID. **text** `string` New prompt text. **customerJourney** `string` `"awareness"`, `"consideration"`, `"decision"`, or `"post-purchase"`. Also accepted as `customer_journey`. Pass `null` or empty string to clear the stage. **promptIds** `string[]` Apply the same `text` and/or `customerJourney` to every listed prompt. **text** `string` Shared prompt text when using `promptIds`. **customerJourney** `string` Shared journey stage when using `promptIds`. ### Request Uniform journey stage on many prompts: ```bash theme={null} curl -s -X POST \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "promptIds": ["PROMPT_ID_1", "PROMPT_ID_2"], "customerJourney": "consideration" }' \ "https://app.rocketblue.ai/api/v1/prompts/batch-update" ``` Per-prompt updates: ```bash theme={null} curl -s -X POST \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompts": [ { "id": "PROMPT_ID_1", "customerJourney": "awareness" }, { "id": "PROMPT_ID_2", "customerJourney": "decision" } ] }' \ "https://app.rocketblue.ai/api/v1/prompts/batch-update" ``` ### Response **updatedCount** `integer` Number of prompts updated. **updatedPrompts** `object[]` Updated prompt objects with `id`, `text`, `topicId`, and `customerJourney`. **brandIds** `string[]` Brands affected by the update. **brandId** `string | null` Present when all updated prompts belonged to a single brand. ```json theme={null} { "updatedCount": 2, "updatedPrompts": [ { "id": "prompt-uuid-1", "text": "How do teams compare pricing?", "topicId": "topic-uuid-1", "customerJourney": "consideration" }, { "id": "prompt-uuid-2", "text": "What should I look for in a vendor?", "topicId": "topic-uuid-1", "customerJourney": "consideration" } ], "brandIds": ["brand-uuid-123"], "brandId": "brand-uuid-123" } ``` # Batch update topics Source: https://docs.rocketblue.ai/api-reference/topics-prompts/batch-update-topics Rename multiple topics in one request. Rename one or more topics in a single call. Prefer this over repeated [Rename topic](/api-reference/topics-prompts/rename-topic) calls when updating more than one topic. ### Request body **topics** `TopicUpdate[]` *required* Non-empty array of topic renames. **TopicUpdate** **id** `string` *required* Topic UUID. **name** `string` *required* New topic name (non-empty after trim). ### Request ```bash theme={null} curl -s -X POST \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "topics": [ { "id": "TOPIC_ID_1", "name": "Pricing & packaging" }, { "id": "TOPIC_ID_2", "name": "Security & compliance" } ] }' \ "https://app.rocketblue.ai/api/v1/topics/batch-update" ``` ### Response **updatedCount** `integer` Number of topics updated. **updatedTopics** `object[]` Updated topic objects with `id`, `name`, and `brandId`. **brandIds** `string[]` Brands affected by the update. **brandId** `string | null` Present when all updated topics belonged to a single brand. ```json theme={null} { "updatedCount": 2, "updatedTopics": [ { "id": "topic-uuid-1", "name": "Pricing & packaging", "brandId": "brand-uuid-123" }, { "id": "topic-uuid-2", "name": "Security & compliance", "brandId": "brand-uuid-123" } ], "brandIds": ["brand-uuid-123"], "brandId": "brand-uuid-123" } ``` # Create perception prompts Source: https://docs.rocketblue.ai/api-reference/topics-prompts/create-perception-prompts POST /v1/brands/{brandId}/perception-prompts Add perception prompts to a brand. Perception prompts are questions (e.g. *"How trustworthy does this brand appear on a scale from 0–10?"*) that are sent to LLMs to score brand attributes. This endpoint requires the **Custom Perception Prompts** feature to be enabled for your organization. Perception prompts share the same quota as regular prompts. ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Request body **prompts** `PerceptionPromptInput[]` *required* **PerceptionPromptInput** ### Request ```bash theme={null} curl -s -X POST \ -H "x-spotlight-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompts": [ { "text": "On a scale from 0 to 10, how trustworthy does this brand appear?", "propertyId": "Trust", "scoringLogic": "0-6: detractor, 7-8: passive, 9-10: promoter" }, { "text": "How clear and easy to understand is this brand'"'"'s messaging?", "propertyId": "Clarity", "goodScore": "Messaging is clear and compelling", "badScore": "Messaging is confusing or inconsistent" } ] }' \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/perception-prompts" ``` ### Response ```json theme={null} { "prompts": [ { "id": "perception-prompt-uuid-1", "brandId": "brand-uuid-123", "propertyId": "Trust", "promptText": "On a scale from 0 to 10, how trustworthy does this brand appear?", "scoringLogic": "0-6: detractor, 7-8: passive, 9-10: promoter" } ], "remainingSlots": 85 } ``` ### Errors | Status | Code | Description | | - | - | - | | `403` | `custom_perception_prompts_disabled` | Custom perception prompts are not enabled for this organization or brand. | | `409` | `prompt_limit_exceeded` | Prompt quota reached. See [Errors](/errors). | # Create prompts Source: https://docs.rocketblue.ai/api-reference/topics-prompts/create-prompts POST /v1/topics/{topicId}/prompts Add prompts to an existing topic. Adds one or more prompts to an existing topic. Enforces the same prompt quota as [Batch create](/api-reference/topics-prompts/batch-create). ### Path parameters **topicId** `string` *required* Topic UUID. Obtain from [Create topics](/api-reference/topics-prompts/create-topics) or the rocketblue app. ### Request body **prompts** `PromptInput[]` *required* **PromptInput** ### Request ```bash theme={null} curl -s -X POST \ -H "x-spotlight-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompts": [ { "text": "How competitive is the pricing?", "customerJourney": "consideration" } ] }' \ "https://app.rocketblue.ai/api/v1/topics/TOPIC_ID/prompts" ``` ### Response ```json theme={null} { "prompts": [ { "id": "prompt-uuid-1", "text": "How competitive is the pricing?", "customerJourney": "consideration" } ], "remainingSlots": 86 } ``` # Create topics Source: https://docs.rocketblue.ai/api-reference/topics-prompts/create-topics POST /v1/brands/{brandId}/topics Create one or more topics for a brand. Creates topics without adding prompts. Use this to first scaffold the topic structure, then add prompts via [Create prompts](/api-reference/topics-prompts/create-prompts) or [Batch create](/api-reference/topics-prompts/batch-create). ### Path parameters **brandId** `string` *required* Brand UUID. Obtain from [List brands](/api-reference/brands/list). ### Request body **topics** `object[]` *required* **Topic** ### Request ```bash theme={null} curl -s -X POST \ -H "x-spotlight-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "topics": [{ "name": "Pricing" }, { "name": "Support" }] }' \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/topics" ``` ### Response ```json theme={null} { "topics": [ { "id": "topic-uuid-1", "name": "Pricing" }, { "id": "topic-uuid-2", "name": "Support" } ] } ``` # Delete prompt Source: https://docs.rocketblue.ai/api-reference/topics-prompts/delete-prompt DELETE /v1/prompts/{promptId} Delete a single prompt. Permanently deletes one prompt. Returns updated remaining slot counts. ### Path parameters **promptId** `string` *required* Prompt UUID. ### Request ```bash theme={null} curl -s -X DELETE \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/prompts/PROMPT_ID" ``` ### Response ```json theme={null} { "deleted": true, "remainingSlots": 87 } ``` # Delete topic Source: https://docs.rocketblue.ai/api-reference/topics-prompts/delete-topic DELETE /v1/topics/{topicId} Delete a topic and all prompts inside it. Permanently deletes a topic and **all prompts** it contains. Use with care — there is no undo. ### Path parameters **topicId** `string` *required* Topic UUID. ### Request ```bash theme={null} curl -s -X DELETE \ -H "x-spotlight-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/topics/TOPIC_ID" ``` ### Response ```json theme={null} { "deleted": true, "remainingSlots": 100 } ``` > [!WARNING] > > This operation deletes all prompts under the topic. Historical analysis results that referenced those prompts are not deleted, but the prompts themselves will no longer be returned in future API calls. # Move prompts to topic Source: https://docs.rocketblue.ai/api-reference/topics-prompts/move-prompts-to-topic Move multiple prompts to a different topic in one request. Moves prompts to another topic and updates related historical data (analysis results, response links, content suggestions, and generated content ideas) so reporting stays consistent. All prompts must belong to the **same brand**. The destination topic must belong to that brand. ### Request body **promptIds** `string[]` *required* Non-empty array of prompt UUIDs to move. **topicId** `string` *required* Destination topic UUID. ### Request ```bash theme={null} curl -s -X POST \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "promptIds": ["PROMPT_ID_1", "PROMPT_ID_2"], "topicId": "TOPIC_ID" }' \ "https://app.rocketblue.ai/api/v1/prompts/move-to-topic" ``` ### Response **topicId** `string` Destination topic ID. **brandId** `string` Brand the prompts belong to. **movedPromptIds** `string[]` Prompt IDs included in the request. **movedCount** `integer` Number of prompts in the request. **updatedPrompts** `integer` Prompt rows whose `topic_id` changed. **updatedAnalysisResults** `integer` Historical analysis result rows updated. **updatedResponseLinks** `integer` Response link rows updated. **updatedContentSuggestions** `integer` Content suggestion rows updated. **updatedGeneratedContentIdeas** `integer` Generated content idea rows updated. ```json theme={null} { "topicId": "topic-uuid-2", "brandId": "brand-uuid-123", "movedPromptIds": ["prompt-uuid-1", "prompt-uuid-2"], "movedCount": 2, "updatedPrompts": 2, "updatedAnalysisResults": 48, "updatedResponseLinks": 120, "updatedContentSuggestions": 0, "updatedGeneratedContentIdeas": 0 } ``` # Rename topic Source: https://docs.rocketblue.ai/api-reference/topics-prompts/rename-topic Rename a single topic. Updates the display name of an existing topic. For renaming many topics at once, use [Batch update topics](/api-reference/topics-prompts/batch-update-topics). ### Path parameters **topicId** `string` *required* Topic UUID. ### Request body **name** `string` *required* New topic name (non-empty after trim). ### Request ```bash theme={null} curl -s -X PATCH \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Pricing & packaging"}' \ "https://app.rocketblue.ai/api/v1/topics/TOPIC_ID" ``` ### Response **updatedCount** `integer` Number of topics updated (always `1` on success). **updatedTopics** `object[]` Updated topic objects with `id`, `name`, and `brandId`. **brandId** `string` Brand the topic belongs to. ```json theme={null} { "updatedCount": 1, "updatedTopics": [ { "id": "topic-uuid-1", "name": "Pricing & packaging", "brandId": "brand-uuid-123" } ], "brandIds": ["brand-uuid-123"], "brandId": "brand-uuid-123" } ``` # Update perception prompts Source: https://docs.rocketblue.ai/api-reference/topics-prompts/update-perception-prompts POST /v1/perception-prompts/batch-update Update the property and/or scoring logic on one or more existing perception prompts. Use this to set the **property** a perception prompt measures (for example `"Trust"` or `"Clarity"`) and the **scoring logic** used the next time responses are scored. Send only the fields you want to change. Omitted fields stay as they are. Pass `scoringLogic: null` to clear scoring logic. A scoring update replaces the whole `scoringLogic` value. `goodScore` and `badScore` are stored as `{ "good": "...", "bad": "..." }`, which is what response scoring reads. Existing scores are left as they are until responses are scored again. Prefer a single call with `promptIds` when applying the same change to every prompt. Use `prompts[]` when each prompt needs a different property or scoring logic. ### Request body Provide **either** `prompts[]` **or** `promptIds` plus at least one shared field (`propertyId` and/or scoring logic). **prompts** `PerceptionPromptUpdate[]` Per-prompt updates. Each item must include `id` and at least one of `propertyId` or a scoring field. **PerceptionPromptUpdate** **id** `string` *required* Perception prompt UUID. **propertyId** `string` The perception property this prompt measures, e.g. `"Trust"`, `"Clarity"`. Also accepted as `property_id`. **scoringLogic** `string | object | null` How to interpret the score. An object `{ "good": "...", "bad": "..." }`, a string, or `null` to clear. Also accepted as `scoring_logic`. Replaces the current scoring logic. **goodScore** `string` What a high score means. Combined with `badScore` into `{ good, bad }`. **badScore** `string` What a low score means. **promptIds** `string[]` Apply the same `propertyId` and/or scoring fields to every listed perception prompt. **propertyId** `string` Shared property when using `promptIds`. Also accepted as `property_id`. **scoringLogic** `string | object | null` Shared scoring logic when using `promptIds`. `null` clears it. Also accepted as `scoring_logic`. **goodScore** `string` Shared high-score meaning when using `promptIds`. **badScore** `string` Shared low-score meaning when using `promptIds`. ### Request Same property on many prompts: ```bash theme={null} curl -s -X POST \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "promptIds": ["PERCEPTION_PROMPT_ID_1", "PERCEPTION_PROMPT_ID_2"], "propertyId": "Trust" }' \ "https://app.rocketblue.ai/api/v1/perception-prompts/batch-update" ``` Same scoring logic on many prompts: ```bash theme={null} curl -s -X POST \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "promptIds": ["PERCEPTION_PROMPT_ID_1", "PERCEPTION_PROMPT_ID_2"], "goodScore": "Clear recommendation and specific evidence", "badScore": "Vague, contradictory, or unsupported claims" }' \ "https://app.rocketblue.ai/api/v1/perception-prompts/batch-update" ``` Per-prompt property and scoring logic: ```bash theme={null} curl -s -X POST \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompts": [ { "id": "PERCEPTION_PROMPT_ID_1", "propertyId": "Trust", "scoringLogic": { "good": "Specific evidence that the brand is reliable", "bad": "Doubt, complaints, or missing proof" } }, { "id": "PERCEPTION_PROMPT_ID_2", "scoringLogic": null } ] }' \ "https://app.rocketblue.ai/api/v1/perception-prompts/batch-update" ``` ### Response **updatedCount** `integer` Number of perception prompts updated. **updatedPrompts** `object[]` Updated perception prompts with `id`, `propertyId`, `promptText`, `scoringLogic`, and `brandId`. **brandIds** `string[]` Brands affected by the update. **brandId** `string | null` Present when all updated prompts belonged to a single brand. ```json theme={null} { "updatedCount": 2, "updatedPrompts": [ { "id": "perception-prompt-uuid-1", "propertyId": "Trust", "promptText": "How trustworthy is Acme?", "scoringLogic": { "good": "Specific evidence that the brand is reliable", "bad": "Doubt, complaints, or missing proof" }, "brandId": "brand-uuid-123" }, { "id": "perception-prompt-uuid-2", "propertyId": "Clarity", "promptText": "Would you recommend Acme?", "scoringLogic": null, "brandId": "brand-uuid-123" } ], "brandIds": ["brand-uuid-123"], "brandId": "brand-uuid-123" } ``` # Get brand web search queries Source: https://docs.rocketblue.ai/api-reference/web-search-queries/get-brand Return web search queries for a brand, using a specific run or the latest run. Same response shape as [Get run web search queries](/api-reference/web-search-queries/get-run). When `runId` is omitted, the latest analysis run for the brand is used. ### Path parameters **brandId** `string` *required* Brand UUID. ### Query parameters **runId** `string` Optional run UUID. Alias: `run_id`. Defaults to the latest run. **prompt\_id** `string` Optional prompt UUID filter. Alias: `promptId`. **llm** `string` Optional LLM name filter. Alias: `llm_names`. ### Request ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/web-search-queries" ``` # Get latest web search queries Source: https://docs.rocketblue.ai/api-reference/web-search-queries/get-latest Convenience endpoint for web search queries from the brand's latest analysis run. Equivalent to calling [Get brand web search queries](/api-reference/web-search-queries/get-brand) without a `runId`. ### Path parameters **brandId** `string` *required* Brand UUID. ### Query parameters **prompt\_id** `string` Optional prompt UUID filter. Alias: `promptId`. **llm** `string` Optional LLM name filter. Alias: `llm_names`. ### Request ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/last/web-search-queries" ``` # Get run web search queries Source: https://docs.rocketblue.ai/api-reference/web-search-queries/get-run Return web search queries used by LLM models for a specific analysis run. Returns prompts (id and text) with per-response web search queries. Optionally filter by prompt and/or LLM names. ### Path parameters **runId** `string` *required* Run UUID. ### Query parameters **prompt\_id** `string` Optional prompt UUID filter. Alias: `promptId`. **llm** `string` Optional LLM name filter. Repeat the param or pass a comma-separated list. Alias: `llm_names`. ### Request ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/runs/RUN_ID/web-search-queries?llm=chatgpt,perplexity" ``` ### Response **run** `object` Run id, brandId, and startedAt. **filters** `object` Applied `promptId` and `llmNames` filters. **summary** `object` Counts of prompts, responses, and queries in the result. **prompts** `array` Each prompt includes `id`, `text`, and `responses[]` with `analysisResultId`, `llm`, and `webSearchQueries`. ```json theme={null} { "run": { "id": "run-uuid-123", "brandId": "brand-uuid-123", "startedAt": "2026-07-20T00:00:00.000Z" }, "filters": { "promptId": null, "llmNames": ["chatgpt", "perplexity"] }, "summary": { "promptCount": 2, "responseCount": 4, "queryCount": 9 }, "prompts": [ { "id": "prompt-uuid-123", "text": "Best AI visibility platforms", "responses": [ { "analysisResultId": "result-uuid-123", "llm": "chatgpt", "webSearchQueries": ["best ai visibility tools 2026"] } ] } ] } ``` # Authentication Source: https://docs.rocketblue.ai/authentication How to authenticate with the rocketblue API. ## API keys Every request must include your API key. Each key is scoped to a single **organization** — all data returned is automatically filtered to that organization. You can send the key in any of these headers (all are equivalent): | Header | Example | | - | - | | `x-api-key` | `x-api-key: sk_live_...` | | `x-spotlight-api-key` | `x-spotlight-api-key: sk_live_...` (legacy alias) | | `spotlight-api-key` | `spotlight-api-key: sk_live_...` (legacy alias) | | `Authorization` (Bearer) | `Authorization: Bearer sk_live_...` | > [!TIP] > > We recommend using `x-api-key` as the canonical header name. The `x-spotlight-api-key` and `spotlight-api-key` headers remain supported for compatibility. ## Getting a key 1. Go to **Settings → API** in the rocketblue app. 2. Copy the key shown on the page. 3. Keep it secret — treat it like a password. API access is available on all plans for members who are not viewers or guests. ## MCP authentication Claude custom connectors and ChatGPT custom MCP apps use **OAuth** instead of an API key. Copy the Server URL from **Settings → MCP**. In Claude, paste that URL into a custom connector, let Claude detect the settings, then approve access. See [Connect an MCP client](/rocketblue-mcp/connect). Cursor and other header-based MCP clients use the same API key headers as REST. ## Authentication errors | Status | Message | Fix | | - | - | - | | `401` | `Missing API key` | Add one of the headers above to your request. | | `401` | `Invalid API key` | The key was not found or has been revoked. Check the Settings page for your current key. | ## Rate limiting API keys have a quota on the number of requests per minute, configurable per organization (default: 120 req/min). When the limit is exceeded the API returns `429 Too Many Requests`. ## Example ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands" ``` # Errors Source: https://docs.rocketblue.ai/errors HTTP status codes and error response shapes. ## Error response format All errors return JSON with at minimum a `message` field: ```json theme={null} { "message": "Brand not found", "code": "not_found" } ``` Some errors include additional context fields (see per-endpoint docs). ## Status codes | Code | Meaning | Common causes | | - | - | - | | `200` | OK | Request succeeded. | | `201` | Created | Resource was created (write endpoints). | | `400` | Bad Request | Missing or invalid request body / parameters. | | `401` | Unauthorized | Missing or invalid API key. | | `403` | Forbidden | Feature disabled for your plan or organization. | | `404` | Not Found | Brand, run, topic, or prompt doesn't exist — or doesn't belong to your organization. | | `405` | Method Not Allowed | HTTP method is not supported on this path. | | `409` | Conflict | Prompt limit exceeded. Response includes `code: "prompt_limit_exceeded"` and remaining slot counts. | | `429` | Too Many Requests | Rate limit exceeded. Back off and retry. | | `500` | Internal Server Error | Unexpected server-side failure. Server logs are tagged `[org-api]`. | ## 404 — unknown path When the path doesn't match any route, the API returns a helpful `404` with the normalized path and the full list of available endpoints: ```json theme={null} { "message": "Endpoint not found", "path": "/v1/brandz", "availableEndpoints": [ { "method": "GET", "path": "/v1/brands" }, { "method": "GET", "path": "/v1/brands/{brandId}/runs" } ] } ``` ## 409 — prompt limit exceeded ```json theme={null} { "message": "Prompt limit exceeded", "code": "prompt_limit_exceeded", "remainingSlots": 0, "promptLimit": 100, "orgWideLimit": 500, "orgTotalPrompts": 500 } ``` ## 403 — feature disabled ```json theme={null} { "message": "Custom perception prompts are not enabled for this organization", "code": "custom_perception_prompts_disabled" } ``` # MCP overview Source: https://docs.rocketblue.ai/mcp-overview Connect AI assistants to your rocketblue organization via MCP (OAuth or API key). ## What is rocketblue MCP? rocketblue exposes an [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server so AI assistants — such as Claude, ChatGPT, Cursor, or other MCP-compatible clients — can read and manage your organization's rocketblue data using natural language. MCP uses the same organization data and permissions as the app and the REST API. Rate limits are shared. Claude and ChatGPT typically connect with **OAuth**; Cursor and many other clients use your **API key**. > [card] [Connect a client](/rocketblue-mcp/connect) > > Set up Claude, ChatGPT, Cursor, or another MCP client. > [card] [MCP security](/rocketblue-mcp/security) > > Technical and security details for IT review. > [card] [Use cases](/rocketblue-mcp/use-cases) > > Practical AI visibility automation workflows. > [card] [Tools reference](/rocketblue-mcp/tools) > > Full list of MCP tools and what each one does. > [card] [Best practices](/rocketblue-mcp/best-practices) > > How agents should work with prompts, quotas, credits, and scheduling. ## Prerequisites 1. **API & MCP access** — Available on all plans for members who are not viewers or guests. Open **Settings → MCP** to get started (credentials are created automatically). 2. **Credentials** — From **Settings → MCP**, copy your team **Server URL**. Claude registers OAuth automatically from that URL. For Cursor and header-based clients, also copy your API key from **Settings → API**. 3. **Server URL** — Unique per team so you can add one connector per organization. Example: ```text theme={null} https://app.rocketblue.ai/api/mcp?484aa7033e56 ``` ## What you can do with MCP | Area | Examples | | - | - | | **Context** | Plan, credits, brands, and brand context with topics, settings, and more in one call | | **Analysis data** | Run history, per-prompt results, run stats, sources, web search queries, perception scores | | **Prompts** | Create, edit, tag, move, and delete topics and prompts; generate prompts with AI; estimate search volume | | **Brand settings** | Profile, location, competitors, brand-name consolidation, content settings | | **Outreach** | Most cited websites, statuses and notes, hidden URLs and domains, domain classification, contact lookup | | **Content** | Content ideas, AI drafts, revisions, featured images, excerpts and schema, publishing to WordPress or Shopify | | **Tracking and audits** | Track URLs and domains, page AI-readiness grades, site audits, timeline events, visibility reports | See [MCP use cases](/rocketblue-mcp/use-cases) for end-to-end automation recipes (weekly digests, competitor watches, content pipelines, and more). ## How MCP relates to the REST API Many MCP tools use the same endpoints as the REST API under `https://app.rocketblue.ai/api`. For example, `get_run_stats` calls `GET /v1/runs/{runId}/stats`. MCP also includes actions that are not in the REST API yet, such as content drafting and outreach updates. Agents should call **`get_organization_context`** once per session and **`get_brand_context`** before working with a specific brand. See [Best practices](/rocketblue-mcp/best-practices) for the recommended workflow. ## Transport and protocol * **Transport:** Streamable HTTP * **Protocol versions:** 2025-06-18, 2025-03-26, 2024-11-05 * **Authentication:** OAuth 2.0 (Claude and ChatGPT) or `x-spotlight-api-key` / equivalent headers (Cursor and other clients) * **Scope:** One team = one Server URL and credential set; all tools are scoped to that organization ## Next steps 1. [Connect your MCP client](/rocketblue-mcp/connect) 2. [Share MCP security with IT](/rocketblue-mcp/security) 3. [Browse use cases](/rocketblue-mcp/use-cases) 4. [Review available tools](/rocketblue-mcp/tools) 5. [Follow agent best practices](/rocketblue-mcp/best-practices) # Step 2: Configure your competitors Source: https://docs.rocketblue.ai/onboarding/competitors Clean up who you're measured against in the rocketblue dashboard rocketblue automatically discovers every brand mentioned in AI responses to your tracked prompts. That list is often longer than expected — it can include media outlets, trade associations, directories, and other brands that aren't really your competitors. This step is about getting that list accurate so your comparisons are meaningful. ## 1. Remove non-competitors from the dashboard Go to **Visibility Analysis** → **Competitor Comparison**. You'll see every brand that has appeared in your prompt responses. Review the list and hide any that aren't direct competitors. Removing a brand doesn't delete the underlying data — it just hides it from your dashboard so the comparisons stay clean. > [!TIP] > > When in doubt, keep it. You can always hide a brand later if it clutters your view. It's harder to recover data you've dismissed. ## 2. Consolidate brand aliases AI models don't always spell brand names consistently. "MEXEM", "mexem.com", and "Mexem" might all appear as separate entries — but they're the same brand, and should count as one. To fix this: 1. Go to **Settings** → **Brand settings**. 2. Click **Consolidate brands**. The system automatically groups alternate spellings and variations under a single canonical name. 3. Verify that your own brand's aliases are correctly grouped. This directly affects your Brand Presence score. > [!NOTE] > > Run consolidation once after initial setup, then again every few months. New aliases appear as more responses are collected. > [!WARNING] > > Consolidation causes your metrics to shift slightly — this is expected and is a sign the numbers are now more accurate, not that something broke. *** > [!TIP] > > **Done when:** Non-competitors are hidden from your competitor view and brand aliases are consolidated so your Brand Presence score is counting correctly. > [card] [Next: Connect your content](/onboarding/content) > > Import your existing content so rocketblue can track what's being cited. > [card] [Back: Set up prompts](/onboarding/prompts) > > Return to Step 1. # Step 3: Connect your content Source: https://docs.rocketblue.ai/onboarding/content Import your existing content so rocketblue can track what's being cited by AI models rocketblue tracks which of your web pages are being cited when AI models answer your tracked prompts. This step connects your existing content so rocketblue can measure what's working — and flag what isn't. ## 1. Import your content from your sitemap Go to **Impact** → **Citation Tracker** and click **Import from sitemap**. The **Tutorial** button on that page plays this walkthrough: [Citation Tracker tutorial](https://www.youtube.com/embed/VdXBTvMCj8g) 1. Enter your sitemap URL (usually `yourdomain.com/sitemap.xml`). 2. Filter the results to just your blog or articles — you don't need to import every page on your site, just the content that's relevant to your tracked prompts. 3. Select the pages you want to track and import them. rocketblue will now monitor these pages and surface them in Citation Tracker whenever they're cited in an AI response. > [!TIP] > > If you have content on multiple domains or subdomains (a separate blog, a press page, LinkedIn articles), you can add additional domains from Citation Tracker. All cited content across your properties will be tracked in one place. ## 2. Connect Google Search Console AI models search Google to find content to cite. If your pages aren't indexed by Google, they can't be cited — no matter how good they are. Connect Google Search Console under **Settings** → **Integrations**. Once connected, rocketblue will: * Check whether each of your tracked pages is indexed. * Flag any pages that aren't indexed so you can fix them. * Submit unindexed pages to Google for indexing on your behalf. > [!WARNING] > > This is a common reason new content doesn't get cited. Always verify indexing after publishing, especially on new domains or subdomains. ## 3. Connect Google Analytics (optional) Under **Settings** → **Integrations**, you can also connect Google Analytics 4. This lets you see traffic arriving at your site directly from AI models — which landing pages they arrive on, and what they do after. Most users who discover your brand through AI will search for you on Google first, then arrive via organic, so direct AI traffic is typically a small slice. But it's a useful data point as the channel matures. *** > [!TIP] > > **Done when:** Your blog content is imported into Citation Tracker, Google Search Console is connected, and rocketblue has verified (or submitted for) indexing on your key pages. > [card] [Next: Create your first article](/onboarding/generate) > > Generate a GEO-optimised article and publish it. > [card] [Back: Configure competitors](/onboarding/competitors) > > Return to Step 2. # Step 4: Create your first article Source: https://docs.rocketblue.ai/onboarding/generate Generate a GEO-optimised article and publish it to start getting cited This is where rocketblue moves from monitoring to action. Open **Improve Visibility** in the sidebar. The page is titled **This Week's Actions Items**, and the **Tutorial** button plays this walkthrough: [Action items tutorial](https://www.youtube.com/embed/pHi_r_HH0Xg) The content generator creates articles that are specifically optimised for AI citation — not just for Google rankings. Most content generated this way gets cited by AI models within a few days of being published. ## 1. Enter your brand info and tone of voice Before generating your first article, go to **Settings** → **Brand** and fill in: * A description of your business and what makes it different * Your tone of voice (e.g. professional, conversational, authoritative) * Competitor information (used when generating listicles that compare options) You only need to do this once. Every piece of content the generator produces will use this context. ## 2. Generate content via Content Gap Analysis Go to **Opportunities** → **Content Gap Analysis**. 1. Select a prompt you want to appear in. 2. Click **Content suggestions**. rocketblue analyses the sources currently cited by AI models for that prompt and reverse-engineers what properties make them work — word count, structure, heading style, citations, and more. 3. You'll get two types of suggestions: * **Aligned content** — articles similar to what's already being cited. High probability of citation because the format is proven. * **Fresh angle content** — ideas that offer something no existing article covers. AI models also like to cite content that adds something new to the conversation. 4. Select an idea and click **Create content**. > [!TIP] > > **Listicles outperform long-form articles for citation rate.** If you're not sure what format to start with, pick a listicle from the suggestions. They're structured, scannable, and tend to get cited across a wider range of prompts. ## 3. Review the generated article rocketblue will produce a full article with: * A title and meta description optimised for the prompt * H2 headers phrased as questions (which AI models prefer) * Self-contained sentences that can be quoted directly * An FAQ section and relevant citations * Target keywords — the terms AI models use when searching for sources (different from what humans type into Google) Review and edit the article as needed. You can adjust the tone, add proprietary data or examples, and refine for your brand voice. ## 4. Publish and track Publish the article to your blog or LinkedIn — both work for AI citation purposes. For WordPress users, install the rocketblue plugin to push content directly from the generator without leaving the dashboard. After publishing: 1. Make sure the page gets indexed by Google (rocketblue will flag this via your Search Console connection from Step 3). 2. Add the URL to **Citation Tracker** (**Impact** in the sidebar) if it isn't automatically picked up. 3. Check back in a few days — you should see the article appear in Citation Tracker with model and prompt attribution. > [!NOTE] > > **Expected timeline:** 80–90% of rocketblue-generated content gets cited by at least one major AI model within the first week of publication. If a piece isn't being cited after two weeks, check that it's indexed and consider whether the prompt it targets is competitive. *** > [!TIP] > > **Done when:** You've set your brand info, generated an article from Content Gap Analysis, published it, and verified it's indexed in Google Search Console. ## What comes next You're set up. From here, the workflow is: 1. **Each week** — check **Weekly Performance**. Watch Brand Presence and Citation Share trend upward. 2. **Monthly** — run Content Gap Analysis for your highest-priority prompts and publish one to two new articles. 3. **Occasionally** — check for new prompt suggestions from rocketblue (you'll get an email when new relevant prompts are detected). Approve the ones you want to track. > [card] [Back to overview](/onboarding) > > Review the full getting started checklist. > [card] [Back: Connect content](/onboarding/content) > > Return to Step 3. # Getting started with rocketblue Source: https://docs.rocketblue.ai/onboarding/index Get your rocketblue workspace set up in four steps. Welcome to rocketblue. This guide walks you through the four things you need to do to get up and running — in order. The whole setup takes about an hour the first time. > [!NOTE] > > **Most time-sensitive:** rocketblue runs your prompts against AI models on a weekly schedule. Complete Step 1 before your first data run so you're tracking the right things from day one. ## The four steps **1. Set up your prompts** Review and configure the prompts rocketblue tracks on your behalf. This is the most critical step — prompts you approve are run every week across all major AI models. [Go to Step 1 →](/onboarding/prompts) **2. Configure your competitors** Clean up who you're measured against. The system finds all brands appearing in AI responses — not all of them will be real competitors. [Go to Step 2 →](/onboarding/competitors) **3. Connect your content** Import your existing content so rocketblue can track which of your pages are being cited by AI models, and flag any that aren't indexed by Google. [Go to Step 3 →](/onboarding/content) **4. Create your first article** Use rocketblue's content generator to write a GEO-optimised article targeting one of your tracked prompts. Most generated content gets cited within days of publishing. [Go to Step 4 →](/onboarding/generate) ## What to watch after setup Once your prompts are locked in, check **Weekly Performance** each week (the page is titled **Weekly Overview**) and track two metrics: * **Brand Presence** — the share of AI responses that mention your brand, across your tracked prompts and models. You want this going up. * **Citation Share** — the percentage of cited sources that belong to you. You want this going up too. > [!WARNING] > > Avoid changing your prompts frequently after setup. Each change retroactively shifts your metrics, making it hard to measure progress. If you add new topics over time, monitor them at the topic level rather than the global level so your historical data stays clean. # Step 1: Set up your prompts Source: https://docs.rocketblue.ai/onboarding/prompts Review, clean, and configure the prompts rocketblue tracks every week > [!WARNING] > > **Do this first.** rocketblue runs all your approved prompts against major AI models on a weekly schedule. Get your prompts right before the next run — wrong prompts skew every metric in your dashboard. When you create a rocketblue account, the system visits your website, learns what your business does, and automatically generates an initial set of prompts it thinks you want to appear in. Your job is to review that list, remove anything irrelevant, and add the prompts you actually care about. ## 1. Review and clean the auto-generated prompts Go to **Visibility Analysis** → **Prompt list**. The page is titled **Tracked Prompts**. You'll see prompts grouped into topics, along with an estimated search volume for each. The **Tutorial** button on that page plays this walkthrough: [Prompt list tutorial](https://www.youtube.com/embed/K36mJBpyP8U) Go through the list and delete any prompts that don't match your business. Prompts you don't care about aren't just noise — they drag down your Brand Presence score by adding responses where you're unlikely to appear. > [!TIP] > > If a prompt makes you think "I don't need to show up for this", delete it. You can always add it back later. ## 2. Add prompts using the Prompt Volume tool The most accurate way to find prompts people actually use is **Prompt Volume**, under **Opportunities**. The page is titled **Prompt Volume Research**. 1. Paste in keywords you already optimise for on Google — up to 10 at a time, all related to one topic. 2. The system searches three data sources (real-time AI conversation data, Google Search trends, and model training data) to find prompts with the same intent. 3. Review the results and select the ones relevant to your business. > [!NOTE] > > Volume numbers are estimates, not absolutes — they help you prioritise, not make guarantees. Low-volume prompts in a niche market are still worth tracking if they're the right ones. ## 3. Organise prompts into topics Group related prompts under named topics — for example, "ETF trading", "Account types", or "Mobile app". Topics serve two purposes: * They keep your dashboard readable as your prompt list grows. * The more descriptive the topic name, the better the system can suggest relevant new prompts later. You can rename, delete, or reorder topics at any time from Prompt list. ## 4. Add perception (branded) prompts Beyond unbranded prompts ("best trading apps in the Netherlands"), rocketblue also tracks **perception prompts** — questions that ask AI models directly about your brand. Examples: * *Is \[your brand] trustworthy?* * *Do you recommend \[your brand]?* * *What are the fees at \[your brand]?* * *How does \[your brand] compare to competitors?* Add these under **Brand Perception** → **Perception Analysis**. They run on the same weekly schedule and tell you what AI models "think" about you when customers ask. *** > [!TIP] > > **Done when:** You've removed irrelevant auto-generated prompts, added prompts from the Prompt Volume tool using your SEO keywords, organised them into topics, and added a few perception prompts about your brand. > [card] [Next: Configure competitors](/onboarding/competitors) > > Clean up who you're measured against in the dashboard. > [card] [Back: Overview](/onboarding) > > Return to the getting started overview. # Pagination Source: https://docs.rocketblue.ai/pagination How paging works across list endpoints. ## Query parameters All list endpoints accept these two query parameters: **limit** `integer` (default: varies) Number of items to return per page. Must be a positive integer. Capped at **500**. **page** `integer` (default: 1) 1-based page index. ## Paging response object Paginated endpoints return a `paging` object alongside the `data` array: ```json theme={null} { "data": [...], "paging": { "page": 1, "limit": 50, "total": 214, "nextPage": 2 } } ``` | Field | Type | Description | | - | - | - | | `page` | integer | Current page number. | | `limit` | integer | Effective limit used for this response. | | `total` | integer \| null | Total matching rows. May be `null` on some endpoints. | | `nextPage` | integer \| null | Next page number, or `null` if this is the last page. | ## Walking all pages ```python theme={null} import requests BASE_URL = "https://app.rocketblue.ai/api" HEADERS = {"x-api-key": "YOUR_API_KEY"} page, results = 1, [] while True: r = requests.get( f"{BASE_URL}/v1/runs/RUN_ID", headers=HEADERS, params={"limit": 500, "page": page}, ).json() results.extend(r["data"]) if r["paging"]["nextPage"] is None: break page += 1 ``` ## Internal limits The database enforces a hard **2000-row** cap per query. For heavy endpoints like `/sources`, the API fetches data in internal batches and merges results before responding — you do not need to handle this yourself. # Quickstart Source: https://docs.rocketblue.ai/quickstart Make your first rocketblue API call in under 2 minutes. ## Get your API key 1. Open the rocketblue app and go to **Settings → API**. 2. Copy your API key. 3. Note your **API Base URL** — it looks like `https://app.rocketblue.ai/api`. ## Verify connectivity Call the root discovery endpoint to confirm your key works and see what's available: ```bash cURL theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/" ``` ```python Python theme={null} import requests BASE_URL = "https://app.rocketblue.ai/api" HEADERS = {"x-api-key": "YOUR_API_KEY"} r = requests.get(f"{BASE_URL}/", headers=HEADERS) print(r.json()) ``` ```javascript JavaScript theme={null} const BASE_URL = "https://app.rocketblue.ai/api"; const HEADERS = { "x-api-key": "YOUR_API_KEY" }; const r = await fetch(`${BASE_URL}/`, { headers: HEADERS }); console.log(await r.json()); ``` **Response:** ```json theme={null} { "message": "rocketblue Data API", "version": "v1", "organizationId": "00000000-0000-0000-0000-000000000000", "endpoints": [ { "method": "GET", "path": "/v1/brands" }, { "method": "GET", "path": "/v1/brands/{brandId}/runs" }, { "method": "GET", "path": "/v1/runs/{runId}" } ] } ``` ## Fetch your brands ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands" ``` Save the `id` field from the brand you want to work with — you'll use it as `{brandId}` in most other endpoints. ## Pull the latest analysis results ```bash theme={null} curl -s \ -H "x-api-key: YOUR_API_KEY" \ "https://app.rocketblue.ai/api/v1/brands/BRAND_ID/last/results" ``` ## Next steps > [card] [Runs](/api-reference/runs/list) > > Browse the full history of analysis runs. > [card] [Content suggestions](/api-reference/content-suggestions/get-run-suggestions) > > Sync AI-generated content ideas into your backlog. > [card] [Sources](/api-reference/sources/get-run-sources) > > See which URLs are driving brand perception. > [card] [Perception](/api-reference/perception/get-brand-perception) > > Explore scored perception properties. # MCP best practices Source: https://docs.rocketblue.ai/rocketblue-mcp/best-practices Recommended workflows for AI agents using rocketblue MCP. These guidelines help AI assistants use rocketblue MCP safely and well. Agents can also call **`get_usage_guide`** to get this guidance as Markdown. ## Recommended session flow ```mermaid theme={null} sequenceDiagram participant Agent participant rocketblue MCP Agent->>rocketblue MCP: get_organization_context rocketblue MCP-->>Agent: plan, credits, brand IDs Agent->>rocketblue MCP: get_brand_context (include sections you need) rocketblue MCP-->>Agent: quota, schedule, topics, settings Note over Agent,rocketblue MCP: Read or write data in batched calls ``` 1. **`get_organization_context`**: call once per session. It returns the plan, remaining credits, and every brand ID. 2. **`get_brand_context`**: call before editing a brand. Use `include` to get topics, settings, and other sections in the same call. 3. **`get_usage_guide`**: call when writing or restructuring prompts. ## Use fewer calls * Tools that read a run accept `brandId` alone for the latest run. You do not need to look up the run ID first. * Batch every change set into one call: `create_topics_and_prompts`, `update_prompts`, `update_outreach`, and `delete_items` all take arrays. * `update_brand_settings` covers profile, competitors, and content settings in one call. ## Regular analysis prompts Regular prompts power your AI visibility reports. Write them like real search queries: * **Neutral and unbranded.** Do not put the client's brand name in the prompt. * **Consideration-stage** when it fits. Comparison, evaluation, pricing, and "how to choose" intents reflect real discovery. * **Organized by topic.** Every prompt belongs to a topic. ### Quota awareness `get_brand_context` returns `promptQuota.remainingSlots`. Never create more prompts than the remaining slots allow. If the quota is full, delete unused prompts with `delete_items` first. ### Generating prompts * `generate_prompts` with `method: "ai"` is free and saves about 8 prompts to the topic. * `generate_prompts` with `method: "volume_research"` costs 50 credits. It returns suggestions with real search volume but does not save them. Add the ones you want with `create_topics_and_prompts` and pass `volume`. ## Perception prompts Perception prompts are **branded**. They measure how models judge the brand on properties such as trust and clarity. * Use **`add_perception_prompts`** to create them and **`update_perception_prompts`** to change property or scoring logic. * Include `goodScore` and `badScore` so scores are easy to read. * Use **`correct_results`** to override a score that a model got wrong. Custom perception prompts must be enabled on your plan. ## Credits Some tools spend organization credits. Each tool description states its cost. * Check `creditsRemaining` from `get_organization_context` first. * Tell the user the cost and get approval before running a credit tool. * Tools check the balance first and stop with a clear message if credits run out. ## Destructive actions `delete_items` deletes data for good. Deleting a topic also deletes its prompts and their results. Confirm with the user before calling it. Update tools are marked as destructive too, because they overwrite existing values. ## Data collection New prompts are queued on the brand's latest run right away, so results start coming in shortly. Full reports still run on the brand's schedule. `nextEstimatedScheduledFetchAt` from `get_brand_context` is an estimate based on schedule frequency and last activity. ## Reading analysis data | Goal | Suggested tools | | - | - | | Latest snapshot | `get_run_stats` with `brandId` | | Historical comparison | `list_runs`, then `get_run_stats` per run | | Citations and sources | `get_run_sources` | | Outreach targets | `get_outreach_cited_urls`, then `get_outreach_contacts` | | Content backlog ideas | `get_content_suggestions` | | Full model answers | `get_run_results` with `includeAnswer: true` (large) | ## Scope and permissions * Credentials are scoped to **one organization**. * **Viewer** and **guest** accounts cannot connect MCP. * With OAuth, actions are recorded under the user who connected. With an API key, they are recorded under the organization owner. * The rate limit defaults to **120 requests per minute** per organization. ## Example agent prompts ```text theme={null} List all brands in my rocketblue organization and show how many prompts each has. ``` ```text theme={null} For brand BRAND_ID, summarize the latest run stats and top 5 mentioned competitors. ``` ```text theme={null} Add a topic called "Enterprise security" with three neutral comparison prompts. Check remaining prompt slots first. ``` ```text theme={null} Find the 10 most cited pages for BRAND_ID that don't mention us, classify their domains, and mark the best 3 as new opportunities. ``` ## Related docs > [card] [Connect an MCP client](/rocketblue-mcp/connect) > > Claude, Cursor, and generic HTTP setup. > [card] [Use cases](/rocketblue-mcp/use-cases) > > Digests, competitor watches, content pipelines. > [card] [Tools reference](/rocketblue-mcp/tools) > > Full tool list with costs. > [card] [Authentication](/authentication) > > API keys and rate limits. # Connect an MCP client Source: https://docs.rocketblue.ai/rocketblue-mcp/connect Set up Claude, ChatGPT, Cursor, and other MCP clients to talk to rocketblue. ## Before you connect 1. Open **Settings → MCP** in rocketblue (API & MCP are available on all plans for non-viewer roles). 2. Copy the **Server URL** from the MCP Setup card. The Server URL is unique per team so you can add one connector per organization, for example: ```text theme={null} https://app.rocketblue.ai/api/mcp?484aa7033e56 ``` The query string identifies the team. Claude registers an OAuth client automatically from that URL. Cursor and other header-based clients use the API key from **Settings → API**. If Claude cannot register automatically, expand **Use your own OAuth client** on the MCP Setup card and paste that Client ID and Client Secret. Keep the secret private. IT and security reviewers: see [MCP security](/rocketblue-mcp/security) and the [Security Overview](https://app.rocketblue.ai/security-overview.html). ## Claude Add a custom connector in Claude on the web or in Claude Desktop. The connector is per team. 1. In a Claude chat, click `+` → **Connectors** → **Add connector** → **Add custom connector**. 2. Name it `rocketblue` + the team name, and paste the Server URL from **Settings → MCP** into **Remote MCP server URL**. 3. Click **Continue**. Let Claude detect the settings, then click **Add**. 4. An authorization window opens. Click **Continue**, then **Approve** to allow access to this team's rocketblue data. > [!TIP] > > The first time Claude uses a tool, approve the request. To stop those prompts, open **Connectors → Manage connectors**, select this connector, and choose **Always allow**. > [!NOTE] > > Use the Server URL from Settings, including the team id in the query string. If registration fails, expand **Use your own OAuth client** on the MCP Setup card and choose that option in Claude instead. ## ChatGPT Yes — rocketblue MCP can be used from OpenAI products that support **remote MCP servers** (ChatGPT custom MCP apps / Developer mode, and the OpenAI Responses API MCP tool). ChatGPT connects over HTTPS to the same Server URL. Use **OAuth**. If ChatGPT detects automatic registration, keep that option. Otherwise expand **Use your own OAuth client** in **Settings → MCP** and paste the Client ID and Client Secret. Availability and write-tool permissions depend on the ChatGPT plan and workspace policy. Workspace admins typically enable **Developer mode**, create a custom app with your MCP URL, complete OAuth, then scan tools. Full MCP (including write/modify tools) is aimed at ChatGPT Business, Enterprise, and Edu; some personal plans may be limited to read/fetch. See [OpenAI’s Developer mode documentation](https://help.openai.com/en/articles/12584461). ### ChatGPT (workspace custom app) Exact labels in ChatGPT change over time. The flow is: 1. A workspace admin enables **Developer mode** (Workspace settings → Apps / Connected Data, depending on plan). 2. Create a custom app and paste the rocketblue **Server URL** from **Settings → MCP** as the remote MCP endpoint. 3. Choose OAuth. Enter the **Client ID** and **Client Secret** from **Settings → MCP** — do not rely on dynamic registration. 4. Complete the rocketblue consent screen while signed in as a non-viewer member of that organization. 5. Scan tools, review the catalog, then create/publish the app according to your workspace policy. > [!NOTE] > > rocketblue issues refresh tokens on the authorization-code grant (access tokens last 1 hour). If ChatGPT asks for an `offline_access` scope, our advertised scope is `spotlight:mcp`; refresh tokens are still returned after a successful authorization. OpenAI’s developer APIs can also attach the same remote MCP URL as an MCP tool. Use the Server URL plus OAuth or an organization API key, matching whatever auth method that API supports. ## Cursor Cursor supports remote MCP servers over HTTP. Add rocketblue to your MCP configuration file. ### Option A: Copy from the app 1. In rocketblue, go to **Settings → MCP**. 2. Under **Cursor**, click the copy button. 3. Paste the JSON into your Cursor MCP config (project `.cursor/mcp.json` or global settings, depending on your setup). 4. Replace `YOUR_API_KEY` with your real API key from **Settings → API** if the placeholder is still shown. ### Option B: Manual config Use a unique server name and the team-specific Server URL for each organization: ```json theme={null} { "mcpServers": { "rocketblue-484aa7033e56": { "url": "https://app.rocketblue.ai/api/mcp?484aa7033e56", "headers": { "x-spotlight-api-key": "YOUR_API_KEY" } } } } ``` After saving, restart Cursor or reload MCP servers. You should see the rocketblue server listed with tools such as `list_brands` and `get_organization_context`. > [!TIP] > > In Cursor, ask the agent to "list my rocketblue brands" as a quick connectivity test. ## Other MCP clients Any client that supports **HTTP MCP** with custom headers can connect using: | Setting | Value | | - | - | | **URL** | Team Server URL from **Settings → MCP** (includes the unique query id) | | **Auth header** | `x-spotlight-api-key: YOUR_API_KEY` | | **Transport** | HTTP | Clients that support OAuth 2.0 for remote MCP can use the same Server URL plus OAuth Client ID and Client Secret from **Settings → MCP**. Alternative header names accepted by the underlying API (if your client cannot set `x-spotlight-api-key`): | Header | Example | | - | - | | `x-api-key` | `x-api-key: YOUR_API_KEY` | | `spotlight-api-key` | `spotlight-api-key: YOUR_API_KEY` | | `Authorization` | `Authorization: Bearer YOUR_API_KEY` | ## Verify the connection Once connected, ask your assistant to: 1. Call **`get_organization_context`** — confirms auth and returns plan/brand count. 2. Call **`list_brands`** — returns brand IDs for your organization. If authentication fails, double-check the credentials in **Settings → MCP** (and **Settings → API** for header-based clients) and that you are signed into the correct rocketblue account for OAuth. ## Troubleshooting | Symptom | Likely cause | Fix | | - | - | - | | Claude registration fails | Automatic registration could not bind the team, or the Server URL is missing the team id | Use the Server URL from **Settings → MCP**, including the query id. If it still fails, expand **Use your own OAuth client** and paste the Client ID and Secret | | ChatGPT OAuth / Scan Tools fails | Dynamic registration attempted, or Developer mode not enabled | Paste the pre-issued Client ID and Secret; confirm a workspace admin enabled Developer mode | | Stuck on rocketblue loading screen during OAuth | Browser session / consent page issue | Sign into `app.rocketblue.ai` first, then retry the connector | | `401 Invalid API key` | Wrong or revoked key | Copy the current key from **Settings → API** | | `429 Too Many Requests` | Rate limit exceeded | Wait and retry; default quota is 120 requests/minute | | Tools not appearing | Client not reloaded | Restart the MCP client after config changes | | Empty brand list / wrong team | Wrong Server URL or credentials for that org | Use the unique Server URL and credentials for the intended team | | Rotating OAuth secret breaks teammates | Secret is shared per team | Share the new secret; anyone still using the old one must update | ## Security notes * Each team's Server URL and OAuth credentials are scoped to **one organization**. * Viewers and guests cannot authorize MCP access or modify data via API or MCP. * Rotate the OAuth Client Secret from **Settings → MCP** if it may have been exposed. Rotating invalidates the previous secret for everyone using that team. * For Cursor and other header-based clients, rotate the API key from **Settings → API** if needed. # MCP security Source: https://docs.rocketblue.ai/rocketblue-mcp/security Technical and security details of the rocketblue MCP server for IT and procurement review. ## Purpose of this page This page is for security, IT, and procurement teams reviewing rocketblue MCP before connecting it to an AI client (Claude, ChatGPT, Cursor, or another MCP-compatible assistant). For platform-wide controls, data residency, subprocessors, and certifications, see the [Security Overview](https://app.rocketblue.ai/security-overview.html) (customer-shareable; Print → Save as PDF). ## What MCP is in rocketblue rocketblue exposes a remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. It is **not** a local process, browser extension, or inbound connection into your network. Your AI client calls our HTTPS endpoint; we never initiate connections into your environment. MCP is a thin protocol layer over the same **organization API** used by REST integrations. Authentication, tenancy, rate limits, and data access are identical whether a client calls REST or MCP tools. | Item | Value | | - | - | | **Endpoint** | `https://app.rocketblue.ai/api/mcp` (unique per-team URL in **Settings → MCP**) | | **Transport** | Streamable HTTP (JSON-RPC over HTTPS) | | **Protocol** | MCP `2024-11-05` | | **Hosting** | Supabase Edge Functions on AWS **eu-central-1 (Frankfurt)** | | **TLS** | Required end-to-end | Discovery metadata: * Protected resource: `https://app.rocketblue.ai/api/mcp/.well-known/oauth-protected-resource` * Authorization server: `https://app.rocketblue.ai/api/mcp/oauth/.well-known/oauth-authorization-server` ## What data MCP can access A connected client can only see **that organization's rocketblue workspace**: brands, prompts/topics, analysis runs, visibility results, cited sources, perception scores, content drafts, and related settings. MCP does **not** grant access to: * Other rocketblue customers (hard organization boundary) * Your internal systems, files, CRMs, or employee directories * Payment card data (Stripe only; never stored by rocketblue) * Optional GA4 / Search Console / Cloudflare datasets (those are fetched live in the product UI and are not MCP tools) rocketblue's core dataset is public AI answers collected on the customer's behalf, plus the configuration the customer entered. See [Security Overview §2](https://app.rocketblue.ai/security-overview.html). ## Authentication Two methods, both organization-scoped: ### OAuth 2.0 (recommended for Claude and ChatGPT) | Property | Detail | | - | - | | **Flow** | Authorization code with **PKCE (S256)** | | **Grants** | `authorization_code`, `refresh_token` | | **Scope** | `spotlight:mcp` | | **Client type** | Public client when Claude uses **Register automatically**, or a confidential Client ID and Secret under **Use your own OAuth client** in **Settings → MCP** | | **Dynamic client registration** | **Supported**. Claude should keep **Register automatically** (Detected). The client is bound to the team in the Server URL. | | **User consent** | Interactive approve/deny on `app.rocketblue.ai` while signed in | | **Who can authorize** | Organization members who are not **viewer** or **guest** | | **Access token** | Signed JWT (HS256), **1 hour** TTL, audience bound to the MCP resource | | **Refresh token** | **30 days**, SHA-256 hashed at rest, **rotated on every use** | | **Authorization codes** | Single-use, **10 minutes** | Claude's automatic registration uses a public client (`none`) with PKCE. Connectors that paste a Client ID and Secret use `client_secret_post` or `client_secret_basic`. Redirect URIs must be `https` (or localhost for development). Vendor callbacks on `*.openai.com`, `*.anthropic.com`, `*.claude.ai`, `*.cursor.com`, and `*.cursor.sh` are allowed. Rotating the Client Secret in Settings immediately invalidates the previous secret. Refresh is also rejected if the authorizing user is no longer a member, or has been changed to viewer/guest. ### API key (Cursor and header-based clients) Organization API keys from **Settings → API** may be sent as `x-api-key`, `x-spotlight-api-key`, `spotlight-api-key`, or `Authorization: Bearer`. Keys are scoped to one organization and can be rotated in Settings. Viewers and guests cannot manage keys. Unauthenticated MCP calls receive `401` with RFC 6750 `WWW-Authenticate` pointing at protected-resource metadata, so compatible clients can start OAuth discovery. ## Authorization and tenancy * Every credential maps to **one organization**. Tools cannot select another org. * Application tables use PostgreSQL **Row Level Security**. MCP executes through the same organization API as REST. * **Viewer** and **guest** roles are read-only in the product and **cannot authorize MCP** or obtain tokens. * Write tools (create/update/delete prompts, update content settings) use the same permission model as the REST API. ## Rate limiting and logging * Default quota: **120 requests per minute** per organization (configurable). Shared with the REST API. Exceeding it returns `429` with `Retry-After`. * Each MCP call is recorded in an organization request log: channel (`mcp`), HTTP method, JSON-RPC method, and tool name. Request bodies and secrets are not written to that log. ## Network and client requirements * Outbound HTTPS from the AI client to `app.rocketblue.ai` (and the same path on `app.get-spotlight.com` if you use that domain). * No inbound firewall changes, agents, or on-prem components. * No IP allowlist is required. Authentication is credential-based, not network-based. * CORS is enabled so browser-based MCP clients can call the endpoint; all data access still requires a valid token or API key. ## Compatible clients | Client | Typical auth | Notes | | - | - | - | | **Claude** (custom connector) | OAuth, **Register automatically** | See [Connect](/rocketblue-mcp/connect#claude) | | **ChatGPT** (custom MCP app / Developer mode) | OAuth, your Client ID/Secret | See [Connect](/rocketblue-mcp/connect#chatgpt). Availability depends on the ChatGPT plan and workspace admin settings. | | **Cursor** | API key header | See [Connect](/rocketblue-mcp/connect#cursor) | | Other HTTP MCP clients | OAuth or API key | Same Server URL | ## Operational security (summary) * HTTPS only; data at rest in **EU (Frankfurt)**. * Service-role credentials stay on the server; they are never shipped to MCP clients. * Client secrets can be rotated in-product. Refresh tokens are hashed and rotated. * rocketblue does not currently hold its own ISO 27001 or SOC 2 report. Infrastructure providers (Supabase, AWS, Netlify, Stripe) do. Details: [Security Overview](https://app.rocketblue.ai/security-overview.html). ## Related pages * [MCP overview](/mcp-overview) * [Connect an MCP client](/rocketblue-mcp/connect) * [MCP tools reference](/rocketblue-mcp/tools) * [API authentication](/authentication) * [Security Overview](https://app.rocketblue.ai/security-overview.html) * Privacy Policy: [rocketblue.ai/privacy-policy](https://www.rocketblue.ai/privacy-policy/) Security questionnaires: [privacy@rocketblue.ai](mailto:privacy@rocketblue.ai) # MCP tools reference Source: https://docs.rocketblue.ai/rocketblue-mcp/tools Complete list of rocketblue MCP tools, what they do, and what they cost. rocketblue MCP exposes **35 tools**. Parameters use camelCase. Every tool has a title and a read-only or destructive annotation, so MCP clients such as Claude can ask before changing data. Any tool that reads a run accepts `runId`. You can also pass only `brandId` to use the brand's latest run. ## Context | Tool | What it does | Type | | - | - | - | | `get_organization_context` | Plan, remaining credits, and every brand with its ID. Call this first. | Read | | `get_brand_context` | Targeting, prompt quota, schedule, and next data collection. Add sections with `include` (see below). | Read | | `get_usage_guide` | Markdown guidance on prompt writing, quotas, credits, and outreach statuses. | Read | ### `get_brand_context` sections Pass any of these in `include` to get them in the same call: | Section | Returns | | - | - | | `settings` | Name, display name, website, description, city, region, competitors, consolidation toggle | | `contentSettings` | Brand information, tone of voice, competitor information, content creation settings | | `topics` | Topics with nested prompts (text, journey stage, volume, tags) | | `perceptionPrompts` | Perception prompts with property and scoring logic | | `mentionedBrands` | Brand names found in answers and how each one is displayed | | `trackedUrls` | Content tracker pages and domains | | `hiddenOutreach` | Hidden outreach domains and URLs | | `timeline` | Activity timeline events | | `contentJobs` | Recent AI content jobs and their status | ## Results | Tool | What it does | Type | | - | - | - | | `list_runs` | A brand's analysis runs, newest first. | Read | | `get_run_results` | Per-prompt, per-model results. `includeAnswer` adds full answers. | Read | | `get_run_stats` | Visibility metrics, per-topic breakdown, and top mentioned brands. | Read | | `get_run_sources` | Cited domains and URLs. `type`: `analysis` (default) or `perception`. | Read | | `get_web_search_queries` | Web searches the models ran per prompt. Filter by `promptId` and `llmNames`. | Read | | `get_perception_results` | Perception prompts with each model's response and score. | Read | | `get_content_suggestions` | Saved content ideas for prompts where the brand was missing. | Read | | `get_outreach_cited_urls` | The "Most cited websites" outreach list with status and notes. | Read | | `get_outreach_contacts` | People to contact at a cited domain. Optional email lookup and domain rank. | Read | | `get_created_content` | List drafts, or pass `contentId` for one full draft. | Read | ## Topics and prompts | Tool | What it does | Type | | - | - | - | | `create_topics_and_prompts` | Create topics and prompts in one call. Prompts can include `tags` and `volume`. New prompts are queued right away. | Write | | `update_prompts` | Change text, journey stage, tags, or topic on many prompts at once. | Update | | `rename_topics` | Rename one or more topics. | Update | | `generate_prompts` | `ai`: free, saves about 8 prompts to a topic. `volume_research`: **50 credits**, returns suggestions with search volume. | Write | | `estimate_prompt_volumes` | Estimate and save search volume for up to 20 prompts. **10 credits per prompt.** | Update | ## Perception | Tool | What it does | Type | | - | - | - | | `add_perception_prompts` | Add branded perception prompts with optional scoring logic. | Write | | `update_perception_prompts` | Change property or scoring logic on existing perception prompts. | Update | | `correct_results` | Fix the brand's sentiment on a result, or override a perception score. | Update | ## Brand settings | Tool | What it does | Type | | - | - | - | | `update_brand_settings` | Profile, location, competitors, consolidation toggle, and content settings in one call. | Update | | `update_mentioned_brands` | Merge brand-name variants under one display name, or reset all. | Update | ## Outreach | Tool | What it does | Type | | - | - | - | | `update_outreach` | Set URL status and notes, hide URLs or domains, mark brand mentions, mark "not an opportunity", and classify domains. | Update | ## Content | Tool | What it does | Type | | - | - | - | | `generate_content_suggestions` | Create content ideas for a run. **10 credits.** | Write | | `create_content_draft` | Write a researched article from a prompt or a brief. **30 credits.** Runs in the background. | Write | | `revise_content_draft` | Rewrite a draft from feedback. **10 credits.** | Update | | `generate_content_assets` | Featured image (**25 credits**, first one per draft free), remove image, or excerpt and schema (free). | Update | | `update_created_content` | Edit draft fields, including the live URL. | Update | | `publish_content` | Send a draft to connected WordPress or Shopify as a draft or live post. | Write | ## Tracking, audits, and reports | Tool | What it does | Type | | - | - | - | | `add_tracked_urls` | Track pages or whole domains in the content tracker. | Write | | `analyze_website` | `page`: AI-readiness grade for one page. `site_audit`: technical site audit. Free. | Write | | `save_timeline_events` | Add or edit timeline events. | Update | | `generate_visibility_report` | Shareable HTML visibility report. Agency plan only. | Write | ## Delete | Tool | What it does | Type | | - | - | - | | `delete_items` | Delete topics, prompts, perception prompts, drafts, tracked URLs, or timeline events in one call. Deleting a topic deletes its prompts. | Destructive | ## Credits Credit tools check the balance first and stop with a clear message when credits run out. `get_organization_context` returns `creditsRemaining`. | Tool | Cost | | - | - | | `create_content_draft` | 30 | | `revise_content_draft` | 10 | | `generate_content_assets` (featured image) | 25, first image per draft free | | `generate_content_suggestions` | 10 | | `generate_prompts` (`volume_research`) | 50, only when results come back | | `estimate_prompt_volumes` | 10 per prompt estimated | ## Long-running tools `create_content_draft` returns right away and finishes in 2 to 5 minutes. * With only `promptId`, it returns a `jobId`. Check `get_brand_context` with `include: ["contentJobs"]` until the job is `completed`. * With a `brief`, look for the new draft with `get_created_content`. If `revise_content_draft` takes longer than about 2 minutes, it returns `status: "processing"` and keeps working. ## Older tool names Tool names from version 1 still work for existing scripts, but they no longer appear in `tools/list`. For example, `list_brands`, `get_brand_last_results`, `delete_prompts`, `move_prompts_to_topic`, and `update_outreach_cited_urls` map to the new tools above. ## Discovering tools programmatically MCP clients call `tools/list` to get the live catalog with JSON Schema inputs and annotations. A `GET` request to the MCP endpoint returns server metadata: ```bash theme={null} curl -s "https://app.rocketblue.ai/api/mcp" ``` ```json theme={null} { "name": "rocketblue", "protocol": "mcp", "transport": "streamable-http", "endpoint": "/functions/v1/org-api-mcp" } ``` # MCP use cases Source: https://docs.rocketblue.ai/rocketblue-mcp/use-cases Practical MCP workflows for automating AI visibility monitoring, content, and prompt ops. Practical ways to automate AI visibility work with rocketblue MCP — digests, competitor monitoring, prompt hygiene, outreach, content pipelines, and more. Connect an assistant once, then ask it to run these workflows in natural language. Each use case lists the MCP tools involved so you can adapt the flow in Cursor, Claude, or any MCP client. ## Weekly visibility digest **Goal:** After each scheduled report, produce a short summary for Slack, email, or a Notion page. **Ask the agent:** ```text theme={null} For brand BRAND_ID, get the latest run stats and top mentioned competitors. Write a 5-bullet weekly digest: share of voice, biggest gains/losses vs prior run, and one recommended action. ``` **Tools:** `list_runs` → `get_run_stats` (current + previous run) ## Competitor share-of-voice watch **Goal:** Flag when a competitor jumps in mention share on priority prompts or topics. **Ask the agent:** ```text theme={null} Compare the last 4 runs for brand BRAND_ID. Highlight any competitor whose topic-level mention share rose more than 5%. List the prompts where they appear. ``` **Tools:** `list_runs` → `get_run_stats` → `get_run_results` (only for flagged prompts) ## Prompt portfolio hygiene **Goal:** Keep the tracked prompt set aligned with real buyer questions and within quota. **Ask the agent:** ```text theme={null} Check remaining prompt slots for brand BRAND_ID. Find prompts with zero brand mentions across the latest run. Propose replacements that are neutral and consideration-stage, then wait for my approval before deleting or creating. ``` **Tools:** `get_brand_context` (with `include: ["topics"]`) → `get_run_results` → `delete_items` / `create_topics_and_prompts` ## Citation gap and outreach **Goal:** See which sites LLMs cite for your category, find the ones that skip you, and work them. **Ask the agent:** ```text theme={null} For brand BRAND_ID, list the most cited pages that don't mention us. Classify their domains, mark the best 5 as opportunities with a note, and find a contact for each. ``` **Tools:** `get_outreach_cited_urls` → `update_outreach` → `get_outreach_contacts` ## AEO keyword mining from model search queries **Goal:** Turn the queries models actually searched into a content and SEO backlog. **Ask the agent:** ```text theme={null} Pull web search queries for brand BRAND_ID (ChatGPT and Perplexity only). Cluster them into themes and output a prioritized brief list of article titles. ``` **Tools:** `get_web_search_queries` (with `llmNames`) → optionally `get_content_suggestions` ## Content pipeline from gap to published post **Goal:** Go from a missing prompt to a published article. **Ask the agent:** ```text theme={null} List content suggestions from the latest run for brand BRAND_ID. Pick the top one, write a draft, add a featured image and schema, and publish it to WordPress as a draft. ``` **Tools:** `get_content_suggestions` → `create_content_draft` → `get_created_content` → `generate_content_assets` → `publish_content` Drafts and images use credits. The agent should confirm the cost first. ## Page and site audits **Goal:** Find what keeps a page from being cited, then track it. **Ask the agent:** ```text theme={null} Grade https://example.com/pricing for AI readiness and list the top fixes. Then add the page to the content tracker for brand BRAND_ID. ``` **Tools:** `analyze_website` (`mode: "page"`) → `add_tracked_urls` ## Perception score tracking **Goal:** Monitor branded perception properties (trust, clarity, etc.) over time. **Ask the agent:** ```text theme={null} Export perception responses for brand BRAND_ID for the latest run and the run before it. Table the score changes and quote one representative LLM explanation per property that dropped. ``` **Tools:** `list_runs` → `get_perception_results` (×2). To change how later responses are scored, call `update_perception_prompts`. To fix a wrong score, call `correct_results`. ## Agency multi-brand rollup **Goal:** One assistant pass across every brand in the org for leadership reporting. **Ask the agent:** ```text theme={null} List all brands. For each, pull brand context and latest run stats. Produce a table: brand, prompt slots remaining, last run date, main-brand mention rate, top competitor. Flag brands with no run in 14+ days. ``` **Tools:** `get_organization_context` → `get_brand_context` + `get_run_stats` per brand. Agency plans can follow up with `generate_visibility_report`. ## Seed prompts from a research brief **Goal:** Turn a GTM or category brief into a tracked topic and prompt set. **Ask the agent:** ```text theme={null} Read this brief: [...]. Using get_usage_guide rules, propose topics and neutral prompts for brand BRAND_ID. Check quota first. After I approve, create them. ``` **Tools:** `get_usage_guide` → `get_brand_context` → `create_topics_and_prompts` ## Tips for reliable automation * Always start with `get_organization_context` and `get_brand_context` so the agent knows plan limits, credits, and schedule. * Pass `brandId` instead of `runId` to read the latest run without an extra call. * Prefer `get_run_stats` for dashboards; use `includeAnswer: true` only when you need raw model text. * New prompts are queued right away, but full reports follow the schedule. Digests should wait for a completed run. * For bulk cleanup, call `delete_items` once with all IDs. * Viewer and guest roles cannot connect MCP. ## Related > [card] [Connect an MCP client](/rocketblue-mcp/connect) > > Wire up Claude or Cursor. > [card] [Tools reference](/rocketblue-mcp/tools) > > Full tool catalog and costs. > [card] [Best practices](/rocketblue-mcp/best-practices) > > Quotas, prompt style, and session flow. > [card] [REST API](/api-reference/discovery) > > Same data over HTTP for scripts and backends.