Domains

A tracked domain is the unit everything else in the Data API hangs off: the id returned here is the domain_id you pass to every other domain endpoint. The API sees the domains of the workspace the key belongs to, the same domains the dashboard shows for that workspace.

Professional and Agency keys can list and inspect domains. Adding and removing a domain are write operations and need an Agency key with the write scope, plus an Idempotency-Key header. A key acts with the current workspace role of the member who created it, so adding or removing a domain also needs that member to be an admin or the owner of the workspace today. Adding a domain further needs that member's access not to be limited to certain domains. Otherwise the request returns 403 workspace_access_required.

Domain object

Adding and removing

Adding a domain takes a JSON body with one field, the bare domain name:

{ "domain": "yourbrand.com" }

It returns 201 with the new domain object. The Data API cannot start checks. Adding follows the same rules as the dashboard:

• A domain that is already tracked in the workspace returns 409 domain_already_tracked.
• A workspace at its plan's or trial's domain limit returns 402 domain_limit_reached, with limit_kind, current, and max in the body.
• A domain that was removed from the workspace earlier comes back with its history: its past checks, and the prompts it tracked before removal.

Removing a domain works the same way as in the dashboard. Checks that are queued or running for it are cancelled, its tracked prompts are archived (which frees them from the workspace prompt limit), and it leaves the workspace's domain list. The response is {"id": "...", "deleted": true}. Adding the same domain again later restores its history.

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

null

curl -X POST "https://api.surfacedby.com/api/v1/ext/domains" \
  -H "X-API-Key: string" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{}'

null

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

null

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

null