API Introduction

SurfacedBy exposes two public REST APIs.

• Data API lets Professional and Agency subscribers read the same workspace data they see in the dashboard. Professional keys are read-only; Agency keys created with the write scope can also add and remove domains and prompts.
• Console API is open to anyone with a SurfacedBy Console account. You load prepaid credits and run on-demand checks. No subscription is required.

This section covers the Data API. For the Console API, see the Console docs.

Base URL

https://api.surfacedby.com/api/v1/ext

Every Data API endpoint lives under this base. The endpoint list below shows paths relative to it.

Authentication

Every request must include your API key in the X-API-Key header:

curl https://api.surfacedby.com/api/v1/ext/domains \
  -H "X-API-Key: sk_live_..."

Live keys (sk_live_) read and change your real workspace data. Test keys (sk_test_) read a fixed sample data set and keep their writes in a private sandbox, so they never touch your workspace. Both kinds count against their own rate limits. See Authentication for the full lifecycle.

Plan access

The Data API is included with the Professional and Agency plans. The plan is checked on every request against the workspace the key belongs to, so a key stops working if that workspace moves to a plan without API access. Where a response names a plan, such as min_tier on the Platforms endpoint, it uses trial, starter, professional, or agency.

A key also acts with the current workspace role of the member who created it. Reads follow that member's domain access, and a write needs the same role the dashboard asks for: an admin or the owner to add or remove a domain, an editor or above to add or remove a prompt. When the member's role no longer allows a write, or they have left the workspace, the request returns 403 workspace_access_required.

Rate limits

Rate limits are enforced per key:

Successful responses include X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Month, and X-RateLimit-Remaining-Month. A 429 response includes Retry-After with the number of seconds to wait. See Rate limits for details.

Idempotency

Every write request (POST or DELETE) must carry an Idempotency-Key header. Resending the same key with the same body returns the stored response instead of repeating the write. See Idempotency for the exact rules.

Versioning

The API version is part of the base URL; v1 is the current version. New optional fields and new endpoints ship within v1, so ignore fields you do not recognise. No v1 endpoint is currently deprecated. When an endpoint is scheduled for removal, its responses carry a Deprecation: true header and a Sunset header with the removal date.

Response format

All responses are JSON. Errors follow RFC 7807 (application/problem+json). List endpoints paginate with opaque cursors. See Conventions for details.

Endpoints at a glance

Read endpoints work on Professional and Agency. Write endpoints (marked write) need an Agency key that was created with the write scope, and a creator whose role allows the change. Paths are relative to the base URL.

GET    /domains                                       List your tracked domains
POST   /domains                                       Add a tracked domain (write)
GET    /domains/{domain_id}                           Get one domain
DELETE /domains/{domain_id}                           Remove a tracked domain (write)
GET    /domains/{domain_id}/analytics                 Analytics for the latest check, or an earlier one via scan_id
GET    /domains/{domain_id}/citations                 Sources AI platforms cited in the last 7 days
GET    /domains/{domain_id}/diff                      Trend series for the headline metrics
GET    /domains/{domain_id}/opportunities             Scored opportunities
GET    /domains/{domain_id}/competitors               Confirmed competitors
GET    /domains/{domain_id}/competitors/{competitor_id}  One competitor
GET    /domains/{domain_id}/prompts                   Tracked prompts
POST   /domains/{domain_id}/prompts                   Add a pinned prompt (write)
DELETE /domains/{domain_id}/prompts/{prompt_id}       Stop tracking a prompt (write)
GET    /domains/{domain_id}/reports                   Generated reports
GET    /domains/{domain_id}/scans                     Check history
GET    /scans/{scan_id}                               One check
GET    /platforms                                     Supported AI platforms and the plan or add-on that includes each

Request and response details for each endpoint are in the API reference, starting with Domains.