Console API Reference
Base URL, authentication, rate limits, idempotency, and errors for the Console API, with links to every resource.
The Console API is served under https://api.surfacedby.com/api/v1/console. Authenticate every request with a Console key in the X-API-Key header. Console keys start with sk_live_ or sk_test_; Data API keys are rejected. Successful responses wrap the payload as {"data": ..., "meta": {"request_id": ...}}, and list responses add page_size, has_more, and next_cursor to meta. Every response carries an X-Request-Id header.
Resources
- Account: read and update your Console account settings.
- Credits: balance, ledger (JSON and CSV), pack catalog, and checkout.
- Keys: mint, list, and revoke Console API keys.
- Domains: register the domains you check.
- Scans: preview the cost of a check, submit it, follow it, and cancel it.
- Usage: request counts and error rate for your API keys.
- Platforms: the AI platforms a check can run on.
- Evidence and improvements: capability discovery, saved answers, reviewed questions, website roles, recommendations and managed jobs.
- Webhooks: register and remove delivery endpoints.
Rate limits
Limits apply per key, in a fixed one-minute window and a calendar-month window. The Console web app has its own bucket, so using it does not consume your keys' quota.
| API | Per minute | Per month |
|---|---|---|
| Agency plan (Data API) | 60 | 50,000 |
| Professional plan (Data API) | 60 | 10,000 |
| Console API (per key) | 120 | 100,000 |
Responses carry X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Month, and X-RateLimit-Remaining-Month. A 429 response includes Retry-After.
Idempotency
Submitting a check, creating a domain, and deleting a domain require an Idempotency-Key header when you authenticate with an API key. Sending the same key with the same body returns the original response for at least 24 hours, so a network retry never charges a check twice. See Idempotency. The same key with a different body returns 409 idempotency_conflict; a key whose first request is still in progress returns 409 idempotency_in_progress with Retry-After. A request that fails releases its key, so a corrected retry can reuse the same key.
Errors
Errors use RFC 7807 (application/problem+json); see Errors for the shape. Console-specific cases:
| Status | type slug | When |
|---|---|---|
| 402 | insufficient_credits | The balance does not cover the check. The body adds required_credits, current_balance, and purchase_url. |
| 404 | domain_not_found | The domain, check, key, or webhook endpoint id is not on your account. |
| 404 | console_account_required | The signed-in user has no Console account, or the account behind the key no longer exists. |
| 409 | scan_already_running | Another check is pending or running for the same domain. |
| 503 | service_disabled | The API is temporarily turned off. |
A revoked or unknown key returns 401 invalid_api_key.