API Introduction

SurfacedBy exposes two public REST APIs.

• Data API (Mode 1) lets Professional and Business subscribers read and manage the same account data they see in the dashboard. Professional is read-only; Business has read and write access.
• Console API (Mode 2) is open to anyone with a SurfacedBy Console account. Load prepaid credits and trigger on-demand scans with your own keywords on the platforms you choose. No subscription 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 examples below show the full URL on the first reference in each section and abbreviate the path afterwards.

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_) touch production data and count against your monthly rate limit. Test keys (sk_test_) return fixture responses from the sandbox and never consume your quota. See Authentication for the full lifecycle.

Rate limits

Rate limits are enforced per key:

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. A 429 response includes Retry-After with the number of seconds to wait. See Rate limits for details.

Idempotency

Write endpoints accept an optional Idempotency-Key header. Resubmitting the same key returns the original response rather than duplicating the write. See Idempotency for the exact rules.

Versioning

The API is versioned in its base URL (/api/v1/ext). v1 is the current stable contract. A breaking change would ship under /api/v2/ext with a stated cutover window. Additive changes (new optional fields, new endpoints) ship within v1.

Response format

All responses are JSON. Errors follow RFC 7807 (application/problem+json). Timestamps are ISO 8601 in UTC. Collections paginate using opaque cursors. See Conventions for details.

Endpoints at a glance

Read-only endpoints are available on Professional and Business. Write endpoints are Business-tier only.

• GET /domains list your tracked domains.
• POST /domains add a tracked domain (Business).
• GET /domains/{domain_id} fetch a single domain.
• DELETE /domains/{domain_id} soft-delete a tracked domain (Business).
• GET /domains/{domain_id}/analytics comprehensive analytics for the latest scan, or a specific historical scan via scan_id.
• GET /domains/{domain_id}/citations external citation sources.
• GET /domains/{domain_id}/competitors competitor list for a domain.
• GET /domains/{domain_id}/competitors/{competitor_id} a single competitor.
• GET /domains/{domain_id}/diff scan-over-scan trend deltas.
• GET /domains/{domain_id}/opportunities scored opportunities.
• GET /domains/{domain_id}/prompts tracked prompts for the domain.
• POST /domains/{domain_id}/prompts pin a prompt (Business).
• DELETE /domains/{domain_id}/prompts/{prompt_id} unpin a prompt (Business).
• GET /domains/{domain_id}/reports generated reports.
• GET /domains/{domain_id}/reports/{report_id}/download download a report.
• GET /domains/{domain_id}/scans scan history for the domain.
• GET /scans/{scan_id} fetch a single scan.
• GET /platforms list AI platforms available on your account.

Request and response schemas for every endpoint are covered in detail under the reference section.