Skip to main content
Beta functionality: reach out to support to express interest in our API and MCP servers. Beta users can also browse the API Reference.
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: 
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.