# Surfacd

- [Introduction](https://docs.surfacd.com/docs/introduction.md): Understand your brand's AI search performance and identify the sources that influence it.
- [Quickstart](https://docs.surfacd.com/docs/getting-started.md): This guide walks you through setting up your first Surfacd project and collecting your first data.
- [Joining a Team](https://docs.surfacd.com/docs/joining-a-team.md): How to accept a team invitation and set up your account on Surfacd.
- [Supported Platforms](https://docs.surfacd.com/docs/supported-platforms.md): Surfacd monitors the AI platforms your buyers actually use. Here is every service we support and what makes each one unique.
- [Managing Projects](https://docs.surfacd.com/docs/managing-projects.md): Create, configure, and manage your Surfacd projects to monitor brand visibility across AI platforms.
- [Pitch Projects](https://docs.surfacd.com/docs/pitch-projects.md): Run a free 7-day AI visibility snapshot, then convert it to ongoing monitoring.
- [Managing Prompts](https://docs.surfacd.com/docs/managing-prompts.md): Prompts are the questions you monitor across AI platforms. Learn how to manage, organise, and optimise them.
- [Adding Prompts](https://docs.surfacd.com/docs/adding-prompts.md): Learn the different ways to add prompts to your project, from manual entry and file import to AI-generated suggestions.
- [Suggested Prompts](https://docs.surfacd.com/docs/suggested-prompts.md): Let AI generate topic-specific prompts that you can review, accept, or decline before adding to your project.
- [Copying Prompts to Other Countries](https://docs.surfacd.com/docs/copying-prompts.md): Duplicate your prompts across multiple countries to track regional differences in AI visibility.
- [Topics & Tags](https://docs.surfacd.com/docs/tags-organisation.md): Topics group your prompts into categories for structured analysis. Tags add flexible labels for cross-cutting filtering and comparison.
- [Competitors](https://docs.surfacd.com/docs/competitors.md): Curate which brands you actively track to focus your analysis on the competitors that matter most.
- [Sharing & Collaboration](https://docs.surfacd.com/docs/sharing-collaboration.md): Share view-only access to your dashboards with stakeholders who don't have accounts.
- [Dashboard](https://docs.surfacd.com/docs/dashboard.md): The Dashboard provides an at-a-glance overview of your brand's AI visibility with key metrics and trends.
- [Brand Rankings](https://docs.surfacd.com/docs/brand-rankings.md): Compare your brand's visibility against competitors across AI platforms.
- [Brand Mentions](https://docs.surfacd.com/docs/brand-mentions.md): Scan every captured AI answer and focus on where your brand appears.
- [Prompts Report](https://docs.surfacd.com/docs/prompts-report.md): Analyse how each prompt performs across AI services with visibility scores and brand data.
- [Source Analysis](https://docs.surfacd.com/docs/source-analysis.md): See which websites AI services cite in their responses.
- [Matrix Analysis](https://docs.surfacd.com/docs/matrix-analysis.md): Cross-dimensional analysis to compare brands, services, countries, and topics side by side.
- [Exporting Data](https://docs.surfacd.com/docs/exporting-data.md): Download your AI visibility data as Excel files for reporting and further analysis.
- [Taking Action on Your Data](https://docs.surfacd.com/docs/taking-action.md): Practical strategies for turning AI visibility insights into measurable improvements for your brand.
- [Reputation](https://docs.surfacd.com/docs/reputation.md): Understand what AI platforms say about your brand, not just whether you appear.
- [Themes & Narratives](https://docs.surfacd.com/docs/themes-narratives.md): Explore the recurring stories AI platforms tell about your brand, grouped by topic.
- [Reputation Insights](https://docs.surfacd.com/docs/reputation-insights.md): Spot narratives on the move and compare how each AI platform tells your story.
- [Competitor Reputation](https://docs.surfacd.com/docs/reputation-competitors.md): Benchmark your sentiment and reach against competitors, theme by theme.
- [API Keys](https://docs.surfacd.com/docs/api-keys.md): Create and manage API keys for your team's scripts, curl commands, or integrations.
- [API Routing](https://docs.surfacd.com/docs/api-routing.md): How Surfacd API URLs are organised, including team-scoped and project-scoped endpoints, and how to discover the public identifiers you need.
- [MCP for AI Assistants](https://docs.surfacd.com/docs/mcp.md): Connect Claude, Cowork, ChatGPT, Codex and other AI assistants to Surfacd so they can read your data and run actions on your behalf.
- [Team Settings](https://docs.surfacd.com/docs/team-settings.md): Configure your team's members, project defaults, and operational controls.
- [Customising Your Brand](https://docs.surfacd.com/docs/customising-your-brand.md): Make Surfacd your own with custom colours, logos, team branding, and your own domain.
- [Custom Domains](https://docs.surfacd.com/docs/custom-domains.md): Connect your own branded domain to access Surfacd under your company's URL.
- [How Credits Work](https://docs.surfacd.com/docs/how-credits-work.md): Understand how Surfacd's credit system works, how costs are calculated, and how to manage your team's usage.
- [Usage & Credits](https://docs.surfacd.com/docs/usage-billing.md): Track credit consumption across your team and projects.
- [List available countries](https://docs.surfacd.com/api-reference/reference/list-available-countries.md): Returns the active countries a project can target, ordered by name. Use a returned `code` as the `default_country_code` when creating a project or as a prompt's `country_code`.
- [List available platforms](https://docs.surfacd.com/api-reference/reference/list-available-platforms.md): Returns the active AI platforms a project can run against, ordered by display name. Use the returned `provider` value in reporting `services` filters. For project service selection, send either the returned `provider` or `uuid`.
- [List domain categories](https://docs.surfacd.com/api-reference/reference/list-domain-categories.md): Returns domain category enum values that can be passed in `categories` reporting filters.
- [List Brands](https://docs.surfacd.com/api-reference/reference/list-brands.md): Returns the project brands. Use the returned `uuid` values in `brands` reporting filters.
- [List Topics](https://docs.surfacd.com/api-reference/reference/list-topics.md): Returns the project topics. Use a returned `uuid` or `name` in `topics` reporting filters (names are case-insensitive). Topic creation is handled through prompt creation/update workflows.
- [List Projects](https://docs.surfacd.com/api-reference/projects/list-projects.md): Returns paginated projects for the current team. Excludes archived projects by default; pass `include_archived=1` to include them.
- [Create Project](https://docs.surfacd.com/api-reference/projects/create-project.md): Creates a project for the current team, with its primary brand and the set of services (AI platforms) to monitor. The brand domain is normalised (protocol, `www`, and path are stripped).
- [Show Project](https://docs.surfacd.com/api-reference/projects/show-project.md): Returns a single project for the current team, including primary brand, default country, and enabled services. Returns 404 if the project does not belong to the current team.
- [Delete Project](https://docs.surfacd.com/api-reference/projects/delete-project.md): Soft-deletes a project. The project must be archived first: deletion is the exit from the archived state, not a shortcut from active. Deleting a project that is not archived is rejected with a `422` and no change is made; archive it via `PATCH /projects/{project}/archive` first.
- [Update Project](https://docs.surfacd.com/api-reference/projects/update-project.md): Partially updates a project. Only the fields present in the request body are changed. Services are matched by UUID or provider slug; supplying `services` replaces the monitored set. Changing the monitored services on a scheduled project triggers a new data collection run (which consumes credits). To…
- [Archive or Restore Project](https://docs.surfacd.com/api-reference/projects/archive-or-restore-project.md): Archives a project, or restores it when `archived` is `false`. Archiving releases the project's reserved credits. Restoring resumes collection at the project's stored frequency and re-reserves the credits that schedule needs; if the team lacks sufficient available credits the restore is rejected wit…
- [Promote Pitch Project](https://docs.surfacd.com/api-reference/projects/promote-pitch-project.md): Promotes an ended pitch project to an ongoing standard project at the given cadence, lifting the pitch limits and reserving the credits the new schedule needs. Rejected with a 422 if the pitch window is still open, the team's active-project limit is reached, or there are insufficient credits; no cha…
- [Manage Project Sharing](https://docs.surfacd.com/api-reference/projects/manage-project-sharing.md): Manages a project's public share link. Send any combination of: `enabled` to turn sharing on/off, `password` to set or clear (null) a password, and `refresh_token` to rotate the share token (invalidating the previous link). Returns the current share state, including the share URL when sharing is ena…
- [List Projects (team-scoped)](https://docs.surfacd.com/api-reference/projects/list-projects-team-scoped.md): Team-scoped variant of the projects endpoint; identical contract with the team resolved from the path instead of the token's default team.
- [Create Project (team-scoped)](https://docs.surfacd.com/api-reference/projects/create-project-team-scoped.md): Team-scoped variant of the projects endpoint; identical contract with the team resolved from the path instead of the token's default team.
- [List Prompts](https://docs.surfacd.com/api-reference/prompts/list-prompts.md): Returns paginated prompts for a project in the current team. Returns 404 if the project does not belong to the current team.
- [Create Prompts](https://docs.surfacd.com/api-reference/prompts/create-prompts.md): Creates one or more prompts on a project.
- [Show Prompt](https://docs.surfacd.com/api-reference/prompts/show-prompt.md): Returns a single prompt by UUID. Returns 404 if the prompt's project does not belong to the current team.
- [Delete Prompt](https://docs.surfacd.com/api-reference/prompts/delete-prompt.md): Soft-deletes a prompt and recalculates the project's reserved credits. Returns 404 if the prompt's project does not belong to the current team.
- [Update Prompt](https://docs.surfacd.com/api-reference/prompts/update-prompt.md): Partially updates a prompt. Only the fields present are applied. `status` toggles between `active` and `inactive`; activating a prompt is subject to the project's prompt limit and the team's available credits. Pass `topic: null` to clear the topic. Keyword and search volume are pipeline-generated an…
- [Update Prompt Tags](https://docs.surfacd.com/api-reference/prompts/update-prompt-tags.md): Bulk-updates tags across one or more of a project's prompts. Each entry targets a prompt by UUID and either replaces its tags wholesale (`sync`) or applies incremental changes (`add` / `remove`). `sync` cannot be combined with `add`/`remove`, and each entry must specify at least one of the three. Ta…
- [Brand Rankings](https://docs.surfacd.com/api-reference/reporting/brand-rankings.md): Returns paginated brand rankings within a date range, with optional filters for brands, tags, services, countries, prompts, topics, and brand search. Each row includes visibility, mention-weighted sentiment score (0–100 Net Sentiment Index), mentions, and average position. Use `brands` with `only_br…
- [Visibility Over Time](https://docs.surfacd.com/api-reference/reporting/visibility-over-time.md): Returns a per-brand series of visibility and sentiment metrics across a date range, optionally rolled up to weekly or monthly buckets. Use `brands` with brand UUIDs to select the series.
- [Visibility Change Decomposition](https://docs.surfacd.com/api-reference/reporting/visibility-change-decomposition.md): Explains why the brand's visibility score changed between the selected period and the previous period of equal length. The comparison window is derived automatically and echoed back as `comparison_start_date` / `comparison_end_date`.
- [Brand Mentions](https://docs.surfacd.com/api-reference/reporting/brand-mentions.md): Returns paginated brand mentions matched within the requested date range. Supports filtering by brand, AI service, country, tag, topic, prompt, rank range, sentiment, and free-text search across snippets.
- [Matrix Analysis](https://docs.surfacd.com/api-reference/reporting/matrix-analysis.md): Returns a metric (visibility, mentions, industry rank, or average position) broken out across two public dimensions. Row, column, and cell identifiers use the same public identifiers as filters: provider strings, country codes, enum values, UUIDs, or stable sentinels.
- [Sources (Domains)](https://docs.surfacd.com/api-reference/reporting/sources-domains.md): Paginated list of domains cited by AI responses for the project across the date range. Each row includes citation count, rank, optional category, and comparison fields versus the previous period.
- [Sources (Hostnames)](https://docs.surfacd.com/api-reference/reporting/sources-hostnames.md): Paginated list of hostnames (e.g. `blog.example.com`) cited by AI responses for the project across the date range.
- [Sources (URLs)](https://docs.surfacd.com/api-reference/reporting/sources-urls.md): Paginated list of individual URLs cited by AI responses for the project. Supply either `domain` or `hostname` to scope to citations under that source; if both are sent, `hostname` wins.
- [Sources (Category Distribution)](https://docs.surfacd.com/api-reference/reporting/sources-category-distribution.md): Returns the distribution of cited source categories for a single brand across the requested date range, along with total source and response counts.
- [List Tags](https://docs.surfacd.com/api-reference/tags/list-tags.md): Returns the project tags. Use a returned `uuid` for prompt tag assignment. Reporting filters accept a tag `uuid` or `name` (names are case-insensitive).
- [Create Tag](https://docs.surfacd.com/api-reference/tags/create-tag.md): Creates a tag on the project and returns it with its public UUID.
- [Show Tag](https://docs.surfacd.com/api-reference/tags/show-tag.md)
- [Delete Tag](https://docs.surfacd.com/api-reference/tags/delete-tag.md): Deletes a project tag and detaches it from prompts.
- [Update Tag](https://docs.surfacd.com/api-reference/tags/update-tag.md)
- [Reputation Overview](https://docs.surfacd.com/api-reference/reputation/reputation-overview.md): Headline reputation KPIs for the project across the date range, with comparison values versus the equal-length previous period.
- [List Themes](https://docs.surfacd.com/api-reference/reputation/list-themes.md): Paginated list of reputation themes (clusters of related narratives) for the project across the date range.
- [Get Theme](https://docs.surfacd.com/api-reference/reputation/get-theme.md): A single theme with its narratives, per-platform sentiment split, and trajectory across the date range.
- [List Narratives](https://docs.surfacd.com/api-reference/reputation/list-narratives.md): Paginated list of reputation narratives (recurring storylines) for the project across the date range.
- [Get Narrative](https://docs.surfacd.com/api-reference/reputation/get-narrative.md): A single narrative with its windowed summary, per-platform sentiment split, and sibling narratives sharing its theme.
- [List Responses](https://docs.surfacd.com/api-reference/reputation/list-responses.md): Paginated list of AI responses scoped to a narrative or theme (a theme expands to its narratives' mentions), windowed to the date range.
- [Get Response](https://docs.surfacd.com/api-reference/reputation/get-response.md): Full detail for a single AI response: the response record, its prompt (with target country), the platform, cited sources, and any brand mentions.
- [Reputation Sources (Domains)](https://docs.surfacd.com/api-reference/reputation/reputation-sources-domains.md): Paginated list of domains cited by the AI responses behind a narrative, theme, or brand, across the date range.
- [Reputation Sources (URLs)](https://docs.surfacd.com/api-reference/reputation/reputation-sources-urls.md): Paginated list of individual URLs cited by the AI responses behind a narrative, theme, or brand. Supply either `domain` or `hostname` to scope to citations under that source; if both are sent, `hostname` wins.
- [Reputation Sources (Prompts)](https://docs.surfacd.com/api-reference/reputation/reputation-sources-prompts.md): Paginated list of prompts whose AI responses cited a specific URL, within a narrative, theme, or brand scope, across the date range.
- [Sentiment Over Time](https://docs.surfacd.com/api-reference/reputation/sentiment-over-time.md): Daily positive/neutral/negative mention counts for the project across the date range, on a contiguous day axis.
- [Sentiment by Platform](https://docs.surfacd.com/api-reference/reputation/sentiment-by-platform.md): Per-platform sentiment distribution and Net Sentiment Index for the project across the date range.
- [Get Team Settings](https://docs.surfacd.com/api-reference/team/get-team-settings.md): Returns settings for the current team, plus its plan name, display prices, and the features included on that plan. The plan is read-only and cannot be changed through the API.
- [Get Team Usage](https://docs.surfacd.com/api-reference/team/get-team-usage.md): Returns the current team's credit summary plus a per-project breakdown of scheduled credit usage. The breakdown lists projects that currently reserve credits or have consumed one-off credits this calendar month.
- [List Team Members](https://docs.surfacd.com/api-reference/team/list-team-members.md): Returns all members of the current team, including those with a pending invitation.
- [Invite Team Member](https://docs.surfacd.com/api-reference/team/invite-team-member.md): Invites a member to the current team by email. The member starts with `pending` status until they accept. If the email isn't a registered user yet, an account is created for them. Owner cannot be assigned via the API.
- [Show Team Member](https://docs.surfacd.com/api-reference/team/show-team-member.md): Returns a single team member by email.
- [Remove Team Member](https://docs.surfacd.com/api-reference/team/remove-team-member.md): Removes a member from the current team (revokes access or a pending invitation). The team owner cannot be removed.
- [Update Member Role](https://docs.surfacd.com/api-reference/team/update-member-role.md): Changes a member's role. The team owner's role cannot be changed, and Owner cannot be assigned (ownership is transferred through a separate flow).
- [List teams](https://docs.surfacd.com/api-reference/team/list-teams.md)
- [Get Team Settings](https://docs.surfacd.com/api-reference/team/get-team-settings-1.md): Returns settings for the current team, plus its plan name, display prices, and the features included on that plan. The plan is read-only and cannot be changed through the API. Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
- [Get Team Usage](https://docs.surfacd.com/api-reference/team/get-team-usage-1.md): Returns the current team's credit summary plus a per-project breakdown of scheduled credit usage. The breakdown lists projects that currently reserve credits or have consumed one-off credits this calendar month. Operates on the token's default team; use the /teams/{teamUuid} variant to target a spec…
- [List Team Members](https://docs.surfacd.com/api-reference/team/list-team-members-1.md): Returns all members of the current team, including those with a pending invitation. Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
- [Invite Team Member](https://docs.surfacd.com/api-reference/team/invite-team-member-1.md): Invites a member to the current team by email. The member starts with `pending` status until they accept. If the email isn't a registered user yet, an account is created for them. Owner cannot be assigned via the API.
- [Show Team Member](https://docs.surfacd.com/api-reference/team/show-team-member-1.md): Returns a single team member by email. Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
- [Remove Team Member](https://docs.surfacd.com/api-reference/team/remove-team-member-1.md): Removes a member from the current team (revokes access or a pending invitation). The team owner cannot be removed. Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
- [Update Member Role](https://docs.surfacd.com/api-reference/team/update-member-role-1.md): Changes a member's role. The team owner's role cannot be changed, and Owner cannot be assigned (ownership is transferred through a separate flow). Operates on the token's default team; use the /teams/{teamUuid} variant to target a specific team.
- [Changelog](https://docs.surfacd.com/changelog.md): New features, improvements, and fixes in Surfacd, newest first.

## OpenAPI Specs

- [openapi](/openapi.json)