Skip to main content
API and MCP access is included on all plans. Browse the API Reference for the full list of endpoints.
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:
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 or names (case-insensitive) from GET /api/v1/projects/{project}/tags (each tag may include a color palette name: gray, blue, cyan, purple, pink, red, orange, yellow, green, teal; null displays as grey)
  • topics: topic UUIDs or names (case-insensitive) from GET /api/v1/projects/{project}/topics, or no_topic
  • 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.