> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfais.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Surfais API
> Read your AI-visibility data and manage what Surfais tracks from your own systems, over a JSON API.
The Surfais API gives your systems programmatic access to the AI-visibility data behind your dashboard: how ChatGPT, Claude, Gemini, Perplexity and Google AI Overviews talk about your brands. It also lets you manage what is tracked — own brands, competitors and prompts — and request scans. It is a JSON API built for server-to-server integrations: a warehouse export, an internal report, or a platform that runs Surfais on behalf of its own customers.
API access is enabled per account. If you do not have a key yet, see [Get a key](#get-a-key).
## What you can do
* **Read your data.** Organisations, brands, prompts, per-run results, mentions, scores, share of voice and cited sources. Start with the [data model](/api/data-model), then [export results](/api/guides/export-results).
* **Manage what is tracked.** Create and update prompts, [provision own brands and their competitors](/api/guides/provision-a-property), or [sync a brand's whole prompt set](/api/guides/sync-prompts) in one declarative call.
* **Request a scan.** [Ask for an on-demand scan](/api/guides/run-a-scan) of an own brand. It uses the organisation's manual-scan allowance, then any purchased scan credits, like a [manual scan](/scans/manual-scans) started from the dashboard.
* **Receive webhooks.** Platform partners can register an endpoint and receive [signed webhooks](/api/webhooks/overview) when a scan completes, or when a score or sentiment threshold is crossed.
The first item needs only read access. The others change something, so they need a key with write access. Whether a key can carry write access depends on your plan or, for a platform partner, on your agreement. See [Who can use it](#who-can-use-it).
Throughout these docs, an **own brand** is a brand the organisation owns, and a **competitor** is a brand it tracks against one. A **platform partner** is a company that builds Surfais into its own product and manages organisations for its customers. If you are a platform partner, each property you manage is an own brand.
## Base URL
```text theme={null}
https://api.surfais.com/v1
```
* The API is served over HTTPS. Request and response bodies are JSON.
* The `/v1` prefix is part of the base URL. Paths in these docs are relative to it, so `GET /orgs` means `GET https://api.surfais.com/v1/orgs`.
* A successful response wraps its payload in `data`, and a list adds `pagination`. An error carries a stable `error.code` and a `request_id`. See [Pagination](/api/pagination) and [Errors](/api/errors).
The API is server-to-server only. CORS is disabled, so a browser refuses the responses, and a preflight request is answered `405 cors_disabled`. A key can read an organisation's data and, with the `write` scope, change it — never ship one in a web page or a mobile app. Call the API from your own server.
## Who can use it
There are two kinds of API key.
| | Organisation key | Partner key |
| ------------ | --------------------------------------------- | ---------------------------------------------------------- |
| Reaches | Exactly one organisation | Every organisation linked to your platform-partner account |
| Made for | A customer integrating its own Surfais data | A platform that manages Surfais for its customers |
| Available to | Organisations on the Scale or Enterprise plan | Platform partners, by agreement with Surfais |
| Access | Read on Scale. Read and write on Enterprise. | Set by the agreement. |
Organisation keys are available on the **Scale** plan, the **Agency** plan (which is built on Scale) and the **Enterprise** plan. The plan is checked on every request, not only when the key is issued: see [Authentication](/api/authentication).
The plan also decides which access a key is issued with. Scale includes read access. Read-and-write access is part of Enterprise. A platform partner's access is set by its agreement with Surfais. See [Plans & limits](/billing/plans-limits) for what else each plan includes.
Both kinds of key call the same endpoints, with two exceptions that are for partner keys only: webhook management and `PATCH /orgs/{orgId}/link`.
## Get a key
There is no self-serve key page. The Surfais team issues keys on request.
1. Ask an org admin of the organisation to email [support@surfais.com](mailto:support@surfais.com).
2. Say which organisation the key is for, and which access the integration needs: read-only, or read and write. Write access depends on your plan. Ask for read-only unless the integration changes what is tracked.
3. Store the key in your secret manager as soon as you receive it. A key is shown once, when it is issued, and cannot be retrieved afterwards.
Platform partners request partner keys from the same address.
## What v1 does not include
These are deliberate exclusions:
* **The raw text of AI answers.** The API returns what Surfais measured in each answer — whether a brand was mentioned, its position, its sentiment and the sources cited — never the answer text itself.
* **Audits, reports and readiness data.** These stay in the dashboard.
* **Creating organisations.** The API works inside organisations that already exist.
* **Deleting brands or prompts.** A `DELETE` on a prompt deactivates it and keeps its history. A `DELETE` on a competitor unlinks it from the own brand. Deletion stays in the dashboard.
## Where to go next
Make your first two calls in about five minutes.
Key format, scopes, and what an authentication failure looks like.
Organisations, brands, prompts and results, and the rules to build on.
The error envelope, every error code, and which ones to retry.
Signed events for platform partners when a scan completes.
What changed in the API, and when.