# Get account information
Source: https://docs.otterly.ai/api-reference/accounts/get-account-information
https://data.otterly.ai/v1/openapi.json get /v1/accounts/info
Returns the authenticated team's subscription plan, end date, and current period usage/limits for prompts, GEO audits, public API requests, and MCP tool calls.
# Create a content check
Source: https://docs.otterly.ai/api-reference/audits/create-a-content-check
https://data.otterly.ai/v1/openapi.json post /v1/audits/geo/content-checks
# Create a crawlability check
Source: https://docs.otterly.ai/api-reference/audits/create-a-crawlability-check
https://data.otterly.ai/v1/openapi.json post /v1/audits/geo/crawlability-checks
# Create a query fan-out
Source: https://docs.otterly.ai/api-reference/audits/create-a-query-fan-out
https://data.otterly.ai/v1/openapi.json post /v1/audits/query-fan-outs
# Get a content check
Source: https://docs.otterly.ai/api-reference/audits/get-a-content-check
https://data.otterly.ai/v1/openapi.json get /v1/audits/geo/content-checks/{checkId}
# Get a crawlability check
Source: https://docs.otterly.ai/api-reference/audits/get-a-crawlability-check
https://data.otterly.ai/v1/openapi.json get /v1/audits/geo/crawlability-checks/{checkId}
# Get a query fan-out
Source: https://docs.otterly.ai/api-reference/audits/get-a-query-fan-out
https://data.otterly.ai/v1/openapi.json get /v1/audits/query-fan-outs/{fanOutId}
# List content checks
Source: https://docs.otterly.ai/api-reference/audits/list-content-checks
https://data.otterly.ai/v1/openapi.json get /v1/audits/geo/content-checks
# List crawlability checks
Source: https://docs.otterly.ai/api-reference/audits/list-crawlability-checks
https://data.otterly.ai/v1/openapi.json get /v1/audits/geo/crawlability-checks
# List query fan-outs
Source: https://docs.otterly.ai/api-reference/audits/list-query-fan-outs
https://data.otterly.ai/v1/openapi.json get /v1/audits/query-fan-outs
# Citation history for a cited URL
Source: https://docs.otterly.ai/api-reference/brand-reports/citation-history-for-a-cited-url
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/citations/history
# Get a brand report
Source: https://docs.otterly.ai/api-reference/brand-reports/get-a-brand-report
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}
# Get citation statistics for a brand report
Source: https://docs.otterly.ai/api-reference/brand-reports/get-citation-statistics-for-a-brand-report
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/citations/stats
# Get prompt details from a brand report.
Source: https://docs.otterly.ai/api-reference/brand-reports/get-prompt-details-from-a-brand-report
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/prompts/{promptId}
# Get statistics for a brand report
Source: https://docs.otterly.ai/api-reference/brand-reports/get-statistics-for-a-brand-report
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/stats
# List AI responses for a prompt in a brand report.
Source: https://docs.otterly.ai/api-reference/brand-reports/list-ai-responses-for-a-prompt-in-a-brand-report
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/prompts/{promptId}/ai-responses
# List brand reports
Source: https://docs.otterly.ai/api-reference/brand-reports/list-brand-reports
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand
# List citations for a brand report
Source: https://docs.otterly.ai/api-reference/brand-reports/list-citations-for-a-brand-report
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/citations
# List prompts for a brand report
Source: https://docs.otterly.ai/api-reference/brand-reports/list-prompts-for-a-brand-report
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/prompts
# List prompts for a cited URL
Source: https://docs.otterly.ai/api-reference/brand-reports/list-prompts-for-a-cited-url
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/citations/prompts
# List recommendations for a brand report
Source: https://docs.otterly.ai/api-reference/brand-reports/list-recommendations-for-a-brand-report
https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/recommendations
# List AI engines and supported countries
Source: https://docs.otterly.ai/api-reference/engines/list-ai-engines-and-supported-countries
https://data.otterly.ai/v1/openapi.json get /v1/engines
# Create prompts in a workspace
Source: https://docs.otterly.ai/api-reference/prompts/create-prompts-in-a-workspace
https://data.otterly.ai/v1/openapi.json post /v1/workspaces/{id}/prompts
Creates one prompt (`prompt`) or several (`prompts`) in the workspace and starts monitoring them, exactly like creation in the UI (including search-volume computation). Up to 5 prompts are created synchronously (201 with the created items); larger batches are processed asynchronously (202 with a processing summary). The whole batch is validated against the workspace's remaining prompt allocation up front — nothing is created if it would exceed the limit.
# Delete a prompt
Source: https://docs.otterly.ai/api-reference/prompts/delete-a-prompt
https://data.otterly.ai/v1/openapi.json delete /v1/workspaces/{id}/prompts/{promptId}
Deletes the prompt. It is removed from any brand report it is part of, and affected brand reports are recalculated without it (asynchronously).
# List prompts in a workspace
Source: https://docs.otterly.ai/api-reference/prompts/list-prompts-in-a-workspace
https://data.otterly.ai/v1/openapi.json get /v1/workspaces/{id}/prompts
Lists the prompts monitored in the workspace. `id` is the identifier accepted by the prompt write endpoints.
# Update the tags assigned to a prompt
Source: https://docs.otterly.ai/api-reference/prompts/update-the-tags-assigned-to-a-prompt
https://data.otterly.ai/v1/openapi.json patch /v1/workspaces/{id}/prompts/{promptId}
Replaces the prompt's tag assignments with the provided set. A prompt's text and country are immutable — requests attempting to change them are rejected; create a new prompt instead.
# Create a tag in a workspace
Source: https://docs.otterly.ai/api-reference/tags/create-a-tag-in-a-workspace
https://data.otterly.ai/v1/openapi.json post /v1/workspaces/{id}/tags
# Delete a tag
Source: https://docs.otterly.ai/api-reference/tags/delete-a-tag
https://data.otterly.ai/v1/openapi.json delete /v1/workspaces/{id}/tags/{tagId}
Deletes the tag. The tag is unassigned from all prompts asynchronously; brand reports filtered by it update accordingly.
# List tags for a workspace
Source: https://docs.otterly.ai/api-reference/tags/list-tags-for-a-workspace
https://data.otterly.ai/v1/openapi.json get /v1/workspaces/{id}/tags
# List workspaces
Source: https://docs.otterly.ai/api-reference/workspaces/list-workspaces
https://data.otterly.ai/v1/openapi.json get /v1/workspaces
# Authentication
Source: https://docs.otterly.ai/authentication
How to authenticate requests to the OtterlyAI Public API
The OtterlyAI Public API uses **Bearer token** authentication. Every request
(except `/v1/health`, `/v1/openapi.json`, and `/v1/docs`) must include an
`Authorization` header.
## Header Format
```
Authorization: Bearer oai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
## Generating an API Key
1. Sign in to the [OtterlyAI dashboard](https://app.otterly.ai).
2. Open **Settings → API Keys**.
3. Click **Create API key**, choose the workspaces and permissions, then copy
the generated key. You will only see it once.
## Permissions
API keys are scoped to:
* **Workspaces** — only data inside the granted workspaces is returned.
* **Permissions** — typically `read` for data retrieval endpoints.
A request with an insufficient permission set receives a `403 Forbidden`
response.
## Errors
| Status | Meaning |
| ------ | ----------------------------------------------------- |
| `401` | Missing or invalid `Authorization` header |
| `403` | Key lacks the required permission or workspace access |
| `429` | Rate limit exceeded |
# Claude Skill
Source: https://docs.otterly.ai/claude-skill
Use OtterlyAI directly inside Claude with the OtterlyAI skill
The OtterlyAI Claude Skill lets you query your brand visibility data — reports,
citations, prompts, recommendations, and GEO audits — directly from Claude.
## Installation
1. Download the `otterly.skill` file.
2. Open **Claude Desktop**.
3. Go to **Customize → Skills → + → Create Skill → Upload Skill** and
select the file.
The skill is automatically available in all new Claude sessions after
installation.
You can also install via the CLI if you prefer:
```bash theme={null}
claude skill add /path/to/otterly.skill
```
## Allow the OtterlyAI Domain
Before using the skill, you need to allow `data.otterly.ai` in Claude's
domain allowlist. Go to **Claude Settings → Capabilities** and add
`data.otterly.ai` to the **Domain allowlist**.
![Claude Capabilities — Domain allowlist]()
## Setting Your API Key
The skill needs an `OTTERLY_API_KEY` to authenticate against the OtterlyAI
Public API. There are two ways to provide it:
### Option 1: Set it per session
At the start of each Claude Code session, simply tell Claude your API key:
```
My OtterlyAI API key is oai_live_xxxx...
```
Claude will remember it for the duration of the session. This is the safest
option — your key is never persisted to disk.
### Option 2: Store it in the skill
You can edit the skill itself to include your API key permanently. Ask Claude
to do it for you:
```
Edit the OtterlyAI skill and set the OTTERLY_API_KEY to oai_live_xxxx...
```
Claude will update the skill's configuration so the key is available
automatically in every future session. This is more convenient but means the
key is stored locally on your machine.
Only store your API key in the skill on devices you trust. If your machine is
shared, prefer the per-session approach.
## Generating an API Key
If you don't have an API key yet:
1. Sign in to the [OtterlyAI dashboard](https://app.otterly.ai).
2. Go to [API Keys](https://app.otterly.ai/api-keys).
3. Click **Create API key**, choose the workspaces and permissions, then copy
the key. You will only see it once.
A **read-only** key is sufficient for accessing brand reports, prompts,
citations, and recommendations. To perform GEO audits or other write
operations, you need a key with **read and write** permissions.
## What You Can Do
Once the skill is active, just ask Claude naturally. For example:
* *"How's my brand doing?"* — get a summary of your brand visibility stats
* *"Which prompts mention my brand the most?"* — ranked prompt analysis
* *"Are AI bots blocked from my site?"* — crawlability audit
* *"Show me what ChatGPT said about \[topic]"* — view actual AI engine responses
* *"Run a content audit on [https://example.com](https://example.com)"* — trigger an on-demand GEO audit
* *"Compare my brand visibility this month vs last month"* — period comparison
The skill covers the full OtterlyAI Public API, including workspaces, brand
reports, KPIs, citations, prompts, recommendations, and GEO audits
(crawlability + content).
# Introduction
Source: https://docs.otterly.ai/introduction
Welcome to the OtterlyAI Public API
The OtterlyAI Public API lets you programmatically access brand reports, prompts,
citations, and workspace data from the OtterlyAI platform.
## Base URL
```
https://data.otterly.ai
```
All endpoints are prefixed with `/v1`.
## OpenAPI Spec
The full machine-readable spec is published at:
```
https://data.otterly.ai/v1/openapi.json
```
This documentation is generated directly from that spec, so it is always in
sync with the deployed API.
## Quick Start
1. Generate an API key from your [OtterlyAI dashboard](https://app.otterly.ai/api-keys).
2. Send it as a Bearer token in the `Authorization` header.
3. Call any endpoint listed in the API Reference.
```bash theme={null}
curl https://data.otterly.ai/v1/health \
-H "Authorization: Bearer YOUR_API_KEY"
```
# OtterlyAI MCP Server
Source: https://docs.otterly.ai/mcp-server
Use OtterlyAI with Model Context Protocol (MCP)–compatible clients
The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) lets AI
assistants like Claude Code, Claude Desktop, Cursor, and other compatible
clients call external tools in a structured way. The OtterlyAI MCP server exposes
your brand reports, prompts, citations, recommendations, and audit checks as
MCP tools so your assistant can answer questions about your AI search
visibility directly.
## Endpoint
```
https://data.otterly.ai/mcp
```
The server speaks the MCP **streamable HTTP** transport. Authentication is
handled entirely through **OAuth 2.0** — see below.
## Authentication
The OtterlyAI MCP server authenticates with **OAuth 2.0**. You do **not** pass
an API key. When you add the server to a compatible client, the client walks you
through a standard browser sign-in to OtterlyAI and obtains an access token on
your behalf. Permissions and workspace scoping match your OtterlyAI account.
The `oai_live_` API keys documented under
[Authentication](/authentication) are for the **REST Public API only**. The
MCP server does not accept them — it is OAuth-only.
The flow is fully automatic for MCP clients: there is nothing to configure by
hand. Under the hood the server implements OAuth 2.0 with dynamic client
registration and PKCE, and advertises discovery metadata at:
```
https://data.otterly.ai/.well-known/oauth-protected-resource/mcp
https://data.otterly.ai/.well-known/oauth-authorization-server
```
When a request arrives without a valid token, the server responds `401` with a
`WWW-Authenticate` header pointing at the protected-resource metadata, which is
the client's cue to start the OAuth flow.
## Quick sanity check
You don't need a token to confirm the server is up and correctly OAuth-gated.
An unauthenticated request returns `401` with a `WWW-Authenticate` header:
```bash theme={null}
curl -i https://data.otterly.ai/mcp -X POST \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
```
You should see `HTTP/1.1 401` and a header of the form
`WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://data.otterly.ai/.well-known/oauth-protected-resource/mcp"`.
Fetching that metadata document returns the resource and its authorization
server:
```bash theme={null}
curl https://data.otterly.ai/.well-known/oauth-protected-resource/mcp
```
## Claude.ai
In **Customize → Connectors**, choose **Add connector / "+" sign**, search for OtterlyAI, and click **Connect**:
```
https://data.otterly.ai/mcp
```
A browser window opens to sign in to OtterlyAI and authorize access. Once
approved, the OtterlyAI tools are available in your chats.
## Claude Code
```bash theme={null}
claude mcp add --transport http otterly https://data.otterly.ai/mcp
```
The first time a tool is used, Claude Code opens a browser to complete the
OAuth sign-in. Verify with `claude mcp list` — you should see
`otterly: ... - ✓ Connected`. Tools are then available as
`mcp__otterly__`.
## Claude Desktop
Add a remote connector pointing at the endpoint; Claude Desktop runs the OAuth
flow in your browser on first connect. If your version launches stdio servers
only, use the [`mcp-remote`](https://github.com/geelen/mcp-remote) bridge — it
performs the OAuth handshake for you, so **no static `Authorization` header is
needed**. Add the following to
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json theme={null}
{
"mcpServers": {
"otterly": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://data.otterly.ai/mcp"]
}
}
}
```
Restart Claude Desktop; a browser opens to authorize, and the OtterlyAI tools
appear in the tool picker.
## Cursor
In **Cursor → Settings → MCP**, add a new server using the same `mcp-remote`
bridge (the OAuth flow opens in your browser on first use):
```json theme={null}
{
"mcpServers": {
"otterly": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://data.otterly.ai/mcp"]
}
}
}
```
## Available tools
Every tool maps 1:1 to an endpoint in the
[Public API OpenAPI spec](https://data.otterly.ai/v1/openapi.json). Required
arguments match the API; optional arguments are listed below the table.
### Workspaces & engines
| Tool | Required arguments | Description |
| ------------------------ | ------------------ | ----------------------------------------------------------------------------------------------------- |
| `list_workspaces` | — | List all workspaces accessible by the API key. |
| `list_workspace_tags` | `workspaceId` | List tags defined for a workspace. |
| `list_workspace_prompts` | `workspaceId` | List the prompts monitored in a workspace. `id` is the identifier accepted by the prompt write tools. |
| `list_engines` | — | List available AI engines and their supported countries. Optional filters: `country`, `engine`. |
### Brand reports
| Tool | Required arguments | Description |
| --------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list_brand_reports` | — | List brand reports accessible by the API key. Optional `workspaceId` scopes to a single workspace. |
| `get_brand_report` | `reportId` | Get a brand report's details, including competitors, countries, and tags. |
| `get_brand_report_stats` | `reportId`, `startDate`, `endDate`, `country` | Aggregated stats — brand coverage history, brand ranks with sentiment, top domains, and engine breakdown. |
| `list_brand_report_prompts` | `reportId`, `startDate`, `endDate`, `country` | List prompts with brand and domain mention stats for a date range and country. |
| `get_brand_report_prompt` | `reportId`, `promptId`, `startDate`, `endDate`, `country` | Detailed metrics for a single prompt — brand coverage history, ranks, sentiment, domain categories, tags. |
| `list_brand_report_prompt_ai_responses` | `reportId`, `promptId`, `startDate`, `endDate`, `country` | List AI response runs collected for a prompt — raw model content, brand mentions, and citations. |
| `list_brand_report_citations` | `reportId`, `startDate`, `endDate`, `country` | List cited URLs for a brand report, filterable by AI engine, tag, and search query. |
| `get_brand_report_citation_stats` | `reportId`, `startDate`, `endDate`, `country` | Citation stats — top cited domains, share-of-citations, and most-cited URLs over a date window. |
| `list_brand_report_citation_prompts` | `reportId`, `url`, `startDate`, `endDate`, `country` | List prompts that cited a specific URL within a brand report over a date window. |
| `get_brand_report_citation_history` | `reportId`, `url`, `startDate`, `endDate`, `country` | Get Citation history for a cited URL — total citations, the change vs the previous period (`percentageChange`), and a daily breakdown by engine. |
| `list_brand_report_recommendations` | `reportId`, `country` | List AI-generated recommendations for improving brand visibility, optionally filtered by `engine`. |
### GEO audits
| Tool | Required arguments | Description |
| -------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `list_crawlability_checks` | `workspaceId` | List crawlability audit checks (robots.txt analysis, bot access) for a workspace. |
| `get_crawlability_check` | `checkId`, `workspaceId` | Get a crawlability check's full results. |
| `list_content_checks` | `workspaceId` | List content / AI-readiness checks for a workspace. |
| `get_content_check` | `checkId`, `workspaceId` | Get a content check's full results — AI readiness, PageSpeed, structural and dynamic-content scores. |
### Query fan-outs
| Tool | Required arguments | Description |
| --------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `list_query_fan_outs` | `workspaceId` | List query fan-out runs for a workspace — each run expands an original query into the related queries AI search engines may generate. |
| `get_query_fan_out` | `fanOutId`, `workspaceId` | Get a query fan-out run and its expanded queries (query, type, user intent, reasoning) split per AI engine. |
### Write tools (`write` permission only)
| Tool | Required arguments | Description |
| --------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_crawlability_check` | `workspaceId`, `url` | Create a new crawlability audit for a URL. |
| `create_content_check` | `workspaceId`, `url` | Create a new content / AI-readiness check. Optional: `crawlerIdentity` (crawler user-agent to test the page against), `sendOtterlyHeader` (send identity header). |
| `create_query_fan_out` | `workspaceId`, `query` | Generate a new query fan-out — expands an original query into related queries across AI engines. Runs asynchronously; poll `get_query_fan_out` until status is `completed` or `failed`. |
| `create_prompts` | `workspaceId`, `country`, `prompts` | Create one or more prompts in a workspace and start monitoring them, exactly like creation in the UI. Optional: `tagIds`, `brandReportIds`. Up to 5 prompts are created synchronously and returned with their IDs; larger batches are processed asynchronously and return a processing summary instead — use `list_workspace_prompts` afterward to see what was created. The whole batch is validated against the workspace's remaining prompt allocation up front. A prompt's `text` and `country` are immutable after creation. |
| `delete_prompt` | `workspaceId`, `promptId` | Delete a prompt. It's removed from any brand report it's part of, and affected brand reports are recalculated without it (asynchronously). |
| `update_prompt_tags` | `workspaceId`, `promptId`, `tagIds` | Replace the tags assigned to a prompt with the given set (pass `[]` to remove all tags). Only tags can be changed — attempting to change a prompt's text or country isn't supported; create a new prompt and delete the old one instead. |
| `create_tag` | `workspaceId`, `name`, `color` | Create a new tag in a workspace. Tags can be assigned to prompts with `update_prompt_tags`. |
| `delete_tag` | `workspaceId`, `tagId` | Delete a tag. It's unassigned from all prompts asynchronously; brand reports filtered by it update accordingly. |
These tools are only registered when your account has `write` permission; with
read-only access they are not advertised by the server.
### Common arguments
* **Dates**: `startDate` and `endDate` are inclusive. Accept `YYYY-MM-DD` or a
full ISO timestamp; only the date portion is used.
* **Country**: `country` is a lowercase ISO 3166-1 alpha-2 code (e.g. `us`,
`de`). Use `uk` for the United Kingdom.
* **Engines**: `engines` (multi-value) and `engine` (single-value) accept
`chatgpt`, `google`, `perplexity`, `copilot`, `google_ai_mode`, `gemini`.
Call `list_engines` to see which engines are available in which countries.
* **Pagination**: list tools accept `page` (default `1`) and `pageSize`
(default `50`, max `100`).
* **Extra filters on `list_brand_report_prompts` and `list_brand_report_citations`**:
`engines`, `tagId`, `search`, `sortBy`, `sortOrder`.
## Typical conversation flow
1. `list_workspaces` → pick a `workspaceId` (optional).
2. `list_brand_reports` → pick a `reportId`.
3. `list_brand_report_prompts` or `list_brand_report_citations` with
`reportId`, a date range, and a country code (e.g. `us`, `gb`, `de`).
4. Drill into `get_brand_report_stats`, `get_brand_report_citation_stats`,
`list_brand_report_recommendations`, or the GEO audit tools as needed.
## Things to know
* Most tools are **read-only**. Write tools (`create_crawlability_check`,
`create_content_check`, `create_query_fan_out`, `create_prompts`,
`delete_prompt`, `update_prompt_tags`, `create_tag`, `delete_tag`) are only
available to accounts with the `write` permission.
* Workspace scoping matches your OtterlyAI account. A `401` from a tool call
means the OAuth token is missing or expired (reconnect to refresh it); a `403`
means your account lacks permission for the requested workspace.
* The OpenAPI spec at
[`https://data.otterly.ai/v1/openapi.json`](https://data.otterly.ai/v1/openapi.json)
is the source of truth for the underlying data shapes returned by each tool.
Hitting a bug or missing a tool you'd like to see? Email
[support@otterly.ai](mailto:support@otterly.ai).