> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Routing

> How Surfacd API URLs are organised, including team-scoped and project-scoped endpoints, and how to discover the public identifiers you need.

<Note>
  Beta functionality: reach out to support to express interest in our API and MCP servers. Beta users can also browse the [API Reference](/api-reference).
</Note>

The Surfacd API uses two URL families. Both authenticate with a team API key as a `Bearer` token; they only differ in how the resource is addressed.

## Two URL families

* **Team-scoped:** `https://app.surfacd.com/api/v1/team/...`. Use these when the operation is about the team: reading settings (`GET /api/v1/team`), team usage (`/usage`), and members (`/members`, `/members/{email}`).
* **Project-scoped:** `https://app.surfacd.com/api/v1/projects/{project}/...`. Use these for anything that targets a single project: project CRUD (read, update, delete, archive, share), prompts (`/prompts`, `/prompts/{prompt}`), and reporting (`/brand-rankings`, `/mentions`, `/visibility-over-time`, `/matrix-analysis`, `/sources-data/...`).

Project collection endpoints, such as `GET /api/v1/projects`, list the projects for your API key's team.

## Discovering identifiers

To find project UUIDs for the key's team, call the project collection:

```bash theme={null}
curl 'https://app.surfacd.com/api/v1/projects' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'
```

Each project in the response includes a `uuid` you can use as `{project}` on project-scoped endpoints.

Reporting filters use public identifiers only. Numeric database IDs are not part of the API contract.

* `brands`: brand UUIDs from `GET /api/v1/projects/{project}/brands`
* `tags`: tag UUIDs from `GET /api/v1/projects/{project}/tags`
* `topics`: topic UUIDs from `GET /api/v1/projects/{project}/topics`
* `services`: platform provider strings from `GET /api/v1/platforms`
* `countries`: country codes from `GET /api/v1/countries`
* `categories`: enum values from `GET /api/v1/domain-categories`
* `prompt`: a prompt UUID from `GET /api/v1/projects/{project}/prompts`

Project service selection also uses `services`, but it accepts either platform provider strings, for example `chatgpt` or `perplexity`, or platform UUIDs. `GET /api/v1/platforms` returns both.