Skip to main content
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.

​
What you can do

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. 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

  • 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 and 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 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. 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 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.
  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

Quickstart

Make your first two calls in about five minutes.

Authentication

Key format, scopes, and what an authentication failure looks like.

Data model

Organisations, brands, prompts and results, and the rules to build on.

Errors

The error envelope, every error code, and which ones to retry.

Webhooks

Signed events for platform partners when a scan completes.

API changelog

What changed in the API, and when.