Conventions

Response envelopes, pagination, sorting, timestamps, request ids, and degraded responses across the Data API.

The conventions on this page apply to every Data API endpoint.

Response envelope

Every successful response wraps its payload in data and carries a meta object. A single resource looks like:

{
  "data": { "id": "..." },
  "meta": { "request_id": "req_..." }
}

A list looks like:

{
  "data": [ ... ],
  "meta": {
    "has_more": true,
    "next_cursor": "W1tbImNyZWF0ZWRfYXQiLCIyMDI2...",
    "request_id": "req_..."
  }
}

Pagination

List endpoints paginate with opaque cursors. To fetch the next page, pass meta.next_cursor back as the cursor query parameter:

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

When meta.next_cursor is null, there are no more pages. See Pagination for page sizes and rules.

Sorting

Each list endpoint has one fixed sort order, newest or highest first. There is no sort parameter.

Endpoint	Order
Domains	Most recently added first
Competitors	Most recently updated first
Opportunities	Highest opportunity score first
Prompts	Pinned prompts first, then most recently added
Reports	Most recently created first
Scans	Most recently started first

Filtering

The only query parameters the Data API reads are cursor on list endpoints and scan_id on the analytics endpoint. Unknown query parameters are ignored rather than rejected.

Date and time

Timestamps are ISO 8601 strings in UTC with an explicit offset, and may include fractional seconds, for example:

2026-04-16T12:34:56.123456+00:00

Parse them with a full ISO 8601 parser rather than a fixed-width format.

Field naming

Fields in request and response bodies are lowercase snake_case. Clients should ignore fields they do not recognise: new optional fields can be added within v1.

Every response carries an X-Request-Id header, and the same value appears as meta.request_id on success and request_id on errors. If you send your own X-Request-Id header on an authenticated request, SurfacedBy uses it instead of minting one, which makes it easy to match your logs to ours. Include the request id when you contact support.

Degraded responses

If the data store is briefly unavailable, a read can be answered from the last good copy instead of failing. Such a response has status 200 and carries X-Data-Degraded: true, plus X-Data-Stale-At with the time that copy was saved. When no saved copy exists, a list endpoint returns an empty data array with X-Data-Degraded: true and no X-Data-Stale-At. Treat that as "temporarily unavailable" and retry later, not as "no records".

Content types

Request bodies and successful responses are application/json. Error responses use application/problem+json per RFC 7807. See Errors for the problem document structure.