{"openapi":"3.1.0","info":{"title":"DeepSearch API","version":"1.0.1","summary":"Programmatic people research from public sources.","description":"The DeepSearch API lets AI agents and applications research a person's PUBLIC online footprint.\nLook someone up by name, phone, email, or username; build a full sourced dossier (social accounts,\ncontact details, work history, relatives, and web mentions); and ask follow-up questions.\n\nPublic information only. Authenticate with a bearer API key created in the developer portal.\nUsage is metered against one weekly allowance shared with the app, MCP, CLI, and SDKs.\nEach request settles from the model tokens and paid tools it actually uses. Cached results and idempotent replays are free.\nAfter included usage is exhausted, non-expiring extra credits are used automatically without unlocking plan-restricted capabilities.\n\nBilling is user-managed: DeepSearch does not accept agent-initiated payments. If a request returns\n401 or 402, the error body includes an `action`, a `url`, and a `message` written for the agent to\nrelay to its user - direct the user to that URL to sign up, subscribe, or add credits, then retry.\n\n## Try it without an account\n\nSend `Authorization: Bearer dsk_test_deepsearch` and every response is a deterministic\nfixture: the production envelope, headers and error contract, with a fixed payload. Nothing\nis metered, no account is needed, and no production data is touched. Any key beginning\n`dsk_test_` behaves the same way. With your own key, add `\"sandbox\": true`\nto a request body instead. GET https://deepsearch.app/api/v1/sandbox describes the whole contract.\n\n## Versioning and deprecation\n\nThe version is in the URL path (`/api/v1/...`). Within a version, changes are additive only:\nnew endpoints, new optional request fields, and new response fields. Adding a response field is\nnot a breaking change, so parse defensively and ignore what you do not recognise.\n\nA breaking change ships as a new path version; `/api/v1` is never repurposed. When an operation\nis deprecated it keeps working and starts sending two headers: `Deprecation`, the date the\ndecision was announced, and `Sunset`, the earliest date it may stop responding. Sunset is never\nless than 12 months after Deprecation, the operation is marked `deprecated: true` in this\ndocument, and the change is listed at https://deepsearch.app/changelog and in GET /api/developer/changelog.\nAn agent that watches for a `Sunset` header has at least a year to migrate.","contact":{"name":"DeepSearch Support","email":"support@deepsearch.app","url":"https://deepsearch.app/api"},"termsOfService":"https://deepsearch.app/terms","x-onboarding":{"payment_model":"user-managed","description":"DeepSearch cannot be paid by agents directly. A human user must create an account, subscribe, and generate an API key.","signup_url":"https://deepsearch.app/developers","billing_url":"https://deepsearch.app/billing"},"x-versioning":{"strategy":"url-path","current":"v1","breaking_changes":"new path version only","in_version_changes":"additive only","deprecation_headers":["Deprecation","Sunset"],"minimum_sunset_notice_months":12,"changelog_url":"https://deepsearch.app/changelog","changelog_api":"https://deepsearch.app/api/developer/changelog"},"x-sandbox":{"supported":true,"type":"fixture-mode","description":"Deterministic fixtures served by the production routes. No separate host, no account, no credits, no production data touched.","public_api_key":"dsk_test_deepsearch","api_key_prefix":"dsk_test_","request_flag":"sandbox","response_header":"X-DeepSearch-Sandbox","operations":["search","dossier","chat"],"discovery_url":"https://deepsearch.app/api/v1/sandbox","docs_url":"https://deepsearch.app/api/docs#sandbox","example":"curl https://deepsearch.app/api/v1/search \\\n  -H \"Authorization: Bearer dsk_test_deepsearch\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"query\": \"Ada Lovelace\",\n        \"type\": \"name\",\n        \"format\": \"json\"\n      }'"},"x-rate-limit":{"supported":true,"standard":"draft-ietf-httpapi-ratelimit-headers","headers":["RateLimit-Policy","RateLimit","RateLimit-Limit","RateLimit-Remaining","RateLimit-Reset","X-RateLimit-Limit","X-RateLimit-Remaining","X-RateLimit-Reset"],"retry_after_header":"Retry-After","reset_semantics":{"RateLimit-Reset":"seconds until the window resets","X-RateLimit-Reset":"unix epoch seconds at which the window resets"},"sent_on":["200","401","404","405","429"],"cors":{"exposed":true,"note":"Access-Control-Expose-Headers names every header above on credential-free responses, auth failures, and 429s, so a browser-based caller can read them."},"observable_without_credentials":["https://deepsearch.app/api/v1","https://deepsearch.app/api/health","https://deepsearch.app/api/v1/sandbox","https://deepsearch.app/openapi.json"],"policies":{"anonymous":{"limit":120,"window_seconds":60,"scope":"per IP","applies_to":"every endpoint callable without credentials"},"search":{"limit":60,"window_seconds":60,"scope":"per API key","applies_to":"POST /api/v1/search"},"dossier":{"limit":30,"window_seconds":60,"scope":"per API key","applies_to":"POST /api/v1/dossier"},"chat":{"limit":60,"window_seconds":60,"scope":"per API key","applies_to":"POST /api/v1/chat"},"mcp":{"limit":120,"window_seconds":60,"scope":"per API key","applies_to":"https://deepsearch.app/api/mcp"}}},"x-batch":{"supported":true,"url":"https://deepsearch.app/api/v1/batch","max_operations":10,"billing":"per item, identical to calling each operation on its own"},"x-mcp":{"url":"https://deepsearch.app/api/mcp","transport":"streamable-http","description":"Hosted MCP server exposing search_people, build_dossier, and ask_about_person as tools. Authenticate with the user's API key as a bearer token."}},"servers":[{"url":"https://deepsearch.app","description":"Production"}],"tags":[{"name":"People research","description":"Search, profile, and ask questions about a person's public footprint."},{"name":"Async jobs","description":"Queue, poll, replay, and webhook long-running API work."},{"name":"Platform","description":"Discovery, health, status, and changelog. Every endpoint here is callable without credentials."},{"name":"Sandbox","description":"The deterministic test mode: fixture responses, no account, no credits, no production data."}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1":{"get":{"operationId":"apiIndex","summary":"List every endpoint, with discovery and authentication pointers.","description":"The REST entry point. Returns the endpoint inventory, the scope each one needs, where the machine-readable contract lives, how to authenticate, and how to use the sandbox. No credentials required - this is what to read before you have a key.","tags":["Platform"],"security":[],"responses":{"200":{"description":"The endpoint index.","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Link":{"schema":{"type":"string"},"description":"RFC 8288 links to the OpenAPI document, the docs, llms.txt, and auth metadata."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Present even on 200: RFC 9110 allows a challenge wherever credentials would change the response, and it lets a client discover the token endpoint without provoking a 401."},"Access-Control-Expose-Headers":{"schema":{"type":"string"},"description":"Names every header above. A cross-origin `fetch` can read no response header outside the Fetch safelist unless it is listed here, so without this the budget headers arrive and are stripped before any browser-based caller can see them."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndex"}}}},"429":{"description":"Too many anonymous requests from this IP.","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Link":{"schema":{"type":"string"},"description":"RFC 8288 links to the OpenAPI document, the docs, llms.txt, and auth metadata."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Present even on 200: RFC 9110 allows a challenge wherever credentials would change the response, and it lets a client discover the token endpoint without provoking a 401."},"Access-Control-Expose-Headers":{"schema":{"type":"string"},"description":"Names every header above. A cross-origin `fetch` can read no response header outside the Fetch safelist unless it is listed here, so without this the budget headers arrive and are stripped before any browser-based caller can see them."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/health":{"get":{"operationId":"apiHealth","summary":"Liveness probe.","description":"Returns `status: \"ok\"` when the API is serving. Reports only this service - it deliberately does not ping downstream dependencies, because every monitor and scanner in the world hits this path.","tags":["Platform"],"security":[],"responses":{"200":{"description":"The service is up.","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Link":{"schema":{"type":"string"},"description":"RFC 8288 links to the OpenAPI document, the docs, llms.txt, and auth metadata."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Present even on 200: RFC 9110 allows a challenge wherever credentials would change the response, and it lets a client discover the token endpoint without provoking a 401."},"Access-Control-Expose-Headers":{"schema":{"type":"string"},"description":"Names every header above. A cross-origin `fetch` can read no response header outside the Fetch safelist unless it is listed here, so without this the budget headers arrive and are stripped before any browser-based caller can see them."}},"content":{"application/json":{"schema":{"type":"object","required":["object","status","api_version","time"],"properties":{"object":{"const":"health"},"status":{"type":"string","enum":["ok"]},"api_version":{"const":"v1"},"developer_api":{"type":"string","enum":["enabled","disabled"]},"time":{"type":"string","format":"date-time"},"index_url":{"type":"string","format":"uri"},"openapi_url":{"type":"string","format":"uri"},"docs_url":{"type":"string","format":"uri"},"status_url":{"type":"string","format":"uri"}}}}}}}}},"/api/v1/sandbox":{"get":{"operationId":"sandboxContract","summary":"Read the sandbox contract and the public test key.","description":"Describes the test mode: the published key (`dsk_test_deepsearch`), the operations that have fixtures, the exact events each fixture emits, and what the sandbox does not simulate. Everything here works without an account.","tags":["Sandbox"],"security":[],"responses":{"200":{"description":"The sandbox contract.","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Link":{"schema":{"type":"string"},"description":"RFC 8288 links to the OpenAPI document, the docs, llms.txt, and auth metadata."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Present even on 200: RFC 9110 allows a challenge wherever credentials would change the response, and it lets a client discover the token endpoint without provoking a 401."},"Access-Control-Expose-Headers":{"schema":{"type":"string"},"description":"Names every header above. A cross-origin `fetch` can read no response header outside the Fetch safelist unless it is listed here, so without this the budget headers arrive and are stripped before any browser-based caller can see them."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxContract"}}}}}}},"/api/developer/status":{"get":{"operationId":"developerStatus","summary":"Read developer platform status.","tags":["Platform"],"security":[],"responses":{"200":{"description":"Developer platform status and discovery links.","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Link":{"schema":{"type":"string"},"description":"RFC 8288 links to the OpenAPI document, the docs, llms.txt, and auth metadata."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Present even on 200: RFC 9110 allows a challenge wherever credentials would change the response, and it lets a client discover the token endpoint without provoking a 401."},"Access-Control-Expose-Headers":{"schema":{"type":"string"},"description":"Names every header above. A cross-origin `fetch` can read no response header outside the Fetch safelist unless it is listed here, so without this the budget headers arrive and are stripped before any browser-based caller can see them."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperStatus"}}}}}}},"/api/developer/changelog":{"get":{"operationId":"developerChangelog","summary":"Read developer API changelog.","tags":["Platform"],"security":[],"responses":{"200":{"description":"Developer API changelog entries.","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Link":{"schema":{"type":"string"},"description":"RFC 8288 links to the OpenAPI document, the docs, llms.txt, and auth metadata."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Present even on 200: RFC 9110 allows a challenge wherever credentials would change the response, and it lets a client discover the token endpoint without provoking a 401."},"Access-Control-Expose-Headers":{"schema":{"type":"string"},"description":"Names every header above. A cross-origin `fetch` can read no response header outside the Fetch safelist unless it is listed here, so without this the budget headers arrive and are stripped before any browser-based caller can see them."}},"content":{"application/json":{"schema":{"type":"object","required":["enabled","api_version","changelog"],"properties":{"enabled":{"type":"boolean"},"api_version":{"const":"v1"},"changelog":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogEntry"}}}}}}}}}},"/api/v1/search":{"post":{"operationId":"search","summary":"Find people by name, phone, email, or username.","description":"Submit an identifier and stream back ranked candidate matches (PersonHit objects) drawn from public sources. Each candidate carries a confidence score and descriptive tags so you can disambiguate before requesting a full dossier.","tags":["People research"],"security":[{"bearerAuth":[]}],"x-required-scope":"search","x-rateLimit":{"limit":60,"windowMs":60000},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"For format=json, safely retries the same request and replays the completed JSON response. For SSE, it protects wallet spend but does not replay the stream."},{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Optional correlation id echoed in response headers and usage logs."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":240,"description":"Name, phone, email, or username to look up."},"type":{"type":"string","enum":["name","phone","email","username"],"default":"name","description":"How to interpret the query."},"platforms":{"description":"For a username search, restrict discovery to specific platforms.","oneOf":[{"type":"string","maxLength":320},{"type":"array","maxItems":8,"items":{"type":"string","enum":["linkedin","instagram","x","tiktok","facebook","youtube","reddit","snapchat"]}}]},"format":{"type":"string","enum":["sse","json"],"default":"sse","description":"sse streams events; json returns one collected object."},"sandbox":{"type":"boolean","default":false,"description":"Return deterministic, unmetered fixtures for tests and demos."}}},"example":{"query":"Ada Lovelace","type":"name","format":"json"}}}},"responses":{"200":{"description":"Success. With format=json a single object is returned; otherwise events stream as text/event-stream.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Stable request correlation id."},"X-DeepSearch-Operation":{"schema":{"type":"string"},"description":"The metered operation."},"X-DeepSearch-Metered":{"schema":{"type":"string","enum":["true","false"]}},"X-DeepSearch-Percentage-Charged":{"schema":{"type":"string"},"description":"Whole-number percentage of the current included allowance charged by this request."},"X-DeepSearch-Usage-Remaining":{"schema":{"type":"string"},"description":"Whole-number percentage of included usage remaining after this request."},"X-DeepSearch-Usage-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Exact boundary at which the included weekly allowance resets."},"X-DeepSearch-Usage-Source":{"schema":{"type":"string","enum":["included","extra","mixed"]},"description":"Whether the reservation used included usage, extra credits, or both."},"X-DeepSearch-Credits-Charged":{"schema":{"type":"string"},"deprecated":true,"description":"Deprecated v1 compatibility charge; use X-DeepSearch-Percentage-Charged."},"X-DeepSearch-Allowance-Source":{"schema":{"type":"string","enum":["weekly","coin"]},"deprecated":true,"description":"Deprecated v1 compatibility source; use X-DeepSearch-Usage-Source."},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Deprecation":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate at which it was declared deprecated."},"Sunset":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate after which it may stop responding. Never less than 12 months after Deprecation."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"},"example":{"object":"search_result","request_id":"req_01HZY8M7YQ2C7W9F4X9J7Z1H3A","metadata":{"api_version":"v1","operation":"search","request_id":"req_01HZY8M7YQ2C7W9F4X9J7Z1H3A","generated_at":"2026-06-19T12:00:00.000Z"},"usage":{"metered":true,"percentageCharged":2,"remainingPercent":98,"resetAt":"2026-07-01T00:00:00.000Z","source":"included","credits":1,"allowanceSource":"weekly"},"hits":[{"id":"ada-lovelace","name":"Ada Lovelace","headline":"Mathematician · London","initials":"AL","confidence":82,"location":"London, United Kingdom","tags":["3 social profiles","London"]}],"events":[{"type":"status","label":"Scanning public sources"},{"type":"hit","hit":{"id":"ada-lovelace","name":"Ada Lovelace","headline":"Mathematician · London","initials":"AL","confidence":82,"location":"London, United Kingdom","tags":["3 social profiles","London"]}},{"type":"done"}]}},"text/event-stream":{"schema":{"type":"string","description":"A stream of `data: {json}` lines, one StreamEvent each."}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl https://deepsearch.app/api/v1/search \\\n  -H \"Authorization: Bearer $DEEPSEARCH_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"query\": \"Ada Lovelace\",\n        \"type\": \"name\",\n        \"format\": \"json\"\n      }'"},{"lang":"JavaScript","label":"Node.js","source":"const res = await fetch(\"https://deepsearch.app/api/v1/search\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.DEEPSEARCH_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"query\": \"Ada Lovelace\",\n    \"type\": \"name\",\n    \"format\": \"json\"\n  }),\n});\n\nconst result = await res.json();\nconsole.log(result);"},{"lang":"Python","label":"Python","source":"import os\nimport json\nimport requests\n\nres = requests.post(\n    \"https://deepsearch.app/api/v1/search\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['DEEPSEARCH_API_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=json.loads(\"{\\\"query\\\":\\\"Ada Lovelace\\\",\\\"type\\\":\\\"name\\\",\\\"format\\\":\\\"json\\\"}\"),\n)\n\nprint(res.json())"}]}},"/api/v1/dossier":{"post":{"operationId":"dossier","summary":"Build a full public-footprint profile for a person.","description":"Pass a candidate from /search (or a minimal person object) and stream a structured dossier - identity, contact, social accounts, locations, work, mentions and a written summary with cited sources. Results are cached: a shared cache hit returns instantly and consumes no usage.","tags":["People research"],"security":[{"bearerAuth":[]}],"x-required-scope":"dossier","x-rateLimit":{"limit":30,"windowMs":60000},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"For format=json, safely retries the same request and replays the completed JSON response. For SSE, it protects wallet spend but does not replay the stream."},{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Optional correlation id echoed in response headers and usage logs."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["person"],"properties":{"person":{"type":"object","required":["name"],"additionalProperties":true,"description":"The subject to profile. Pass a candidate from /search to focus the result.","properties":{"name":{"type":"string","minLength":1,"maxLength":180},"headline":{"type":"string","maxLength":500},"confidence":{"type":"number","minimum":0,"maximum":100},"tags":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":80}},"primaryUsername":{"type":"string"}}},"refresh":{"type":"boolean","default":false,"description":"Bypass the shared cache and rebuild (always meters)."},"format":{"type":"string","enum":["sse","json"],"default":"sse"},"sandbox":{"type":"boolean","default":false,"description":"Return deterministic, unmetered fixtures for tests and demos."}}},"example":{"person":{"name":"Ada Lovelace","headline":"Mathematician · London","confidence":82,"tags":["Computing pioneer"]},"format":"json"}}}},"responses":{"200":{"description":"Success. With format=json a single object is returned; otherwise events stream as text/event-stream.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Stable request correlation id."},"X-DeepSearch-Operation":{"schema":{"type":"string"},"description":"The metered operation."},"X-DeepSearch-Metered":{"schema":{"type":"string","enum":["true","false"]}},"X-DeepSearch-Percentage-Charged":{"schema":{"type":"string"},"description":"Whole-number percentage of the current included allowance charged by this request."},"X-DeepSearch-Usage-Remaining":{"schema":{"type":"string"},"description":"Whole-number percentage of included usage remaining after this request."},"X-DeepSearch-Usage-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Exact boundary at which the included weekly allowance resets."},"X-DeepSearch-Usage-Source":{"schema":{"type":"string","enum":["included","extra","mixed"]},"description":"Whether the reservation used included usage, extra credits, or both."},"X-DeepSearch-Credits-Charged":{"schema":{"type":"string"},"deprecated":true,"description":"Deprecated v1 compatibility charge; use X-DeepSearch-Percentage-Charged."},"X-DeepSearch-Allowance-Source":{"schema":{"type":"string","enum":["weekly","coin"]},"deprecated":true,"description":"Deprecated v1 compatibility source; use X-DeepSearch-Usage-Source."},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Deprecation":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate at which it was declared deprecated."},"Sunset":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate after which it may stop responding. Never less than 12 months after Deprecation."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DossierResponse"},"example":{"object":"dossier_result","request_id":"req_01HZY8N9M52JGQ7PC1X3TPEF5R","metadata":{"api_version":"v1","operation":"dossier","request_id":"req_01HZY8N9M52JGQ7PC1X3TPEF5R","generated_at":"2026-06-19T12:00:00.000Z"},"usage":{"metered":true,"percentageCharged":9,"remainingPercent":73,"resetAt":"2026-07-01T00:00:00.000Z","source":"included","credits":1,"allowanceSource":"weekly","cached":false},"cached":false,"dossier":{"summary":"Ada Lovelace was a 19th-century mathematician widely regarded as the first computer programmer.","sections":{"identity":{"name":"Ada Lovelace","age":null}},"sources":[{"id":"src-1","position":1,"url":"https://en.wikipedia.org/wiki/Ada_Lovelace","title":"Ada Lovelace","domain":"en.wikipedia.org"}]},"events":[{"type":"section","key":"identity","data":{"name":"Ada Lovelace","age":null}},{"type":"summary","delta":"Ada Lovelace was a 19th-century mathematician "},{"type":"summary","delta":"widely regarded as the first computer programmer."},{"type":"sources","sources":[{"id":"src-1","position":1,"url":"https://en.wikipedia.org/wiki/Ada_Lovelace","title":"Ada Lovelace","domain":"en.wikipedia.org"}]},{"type":"done"}]}},"text/event-stream":{"schema":{"type":"string","description":"A stream of `data: {json}` lines, one StreamEvent each."}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl https://deepsearch.app/api/v1/dossier \\\n  -H \"Authorization: Bearer $DEEPSEARCH_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"person\": {\n          \"name\": \"Ada Lovelace\",\n          \"headline\": \"Mathematician · London\",\n          \"confidence\": 82,\n          \"tags\": [\n            \"Computing pioneer\"\n          ]\n        },\n        \"format\": \"json\"\n      }'"},{"lang":"JavaScript","label":"Node.js","source":"const res = await fetch(\"https://deepsearch.app/api/v1/dossier\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.DEEPSEARCH_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"person\": {\n      \"name\": \"Ada Lovelace\",\n      \"headline\": \"Mathematician · London\",\n      \"confidence\": 82,\n      \"tags\": [\n        \"Computing pioneer\"\n      ]\n    },\n    \"format\": \"json\"\n  }),\n});\n\nconst result = await res.json();\nconsole.log(result);"},{"lang":"Python","label":"Python","source":"import os\nimport json\nimport requests\n\nres = requests.post(\n    \"https://deepsearch.app/api/v1/dossier\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['DEEPSEARCH_API_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=json.loads(\"{\\\"person\\\":{\\\"name\\\":\\\"Ada Lovelace\\\",\\\"headline\\\":\\\"Mathematician · London\\\",\\\"confidence\\\":82,\\\"tags\\\":[\\\"Computing pioneer\\\"]},\\\"format\\\":\\\"json\\\"}\"),\n)\n\nprint(res.json())"}]}},"/api/v1/chat":{"post":{"operationId":"chat","summary":"Ask follow-up questions about a person.","description":"Continue a conversation about a subject. Send the running message history and DeepSearch streams a grounded answer plus suggested follow-up questions, drawing on the person's public footprint.","tags":["People research"],"security":[{"bearerAuth":[]}],"x-required-scope":"chat","x-rateLimit":{"limit":60,"windowMs":60000},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"For format=json, safely retries the same request and replays the completed JSON response. For SSE, it protects wallet spend but does not replay the stream."},{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Optional correlation id echoed in response headers and usage logs."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["person","messages"],"properties":{"person":{"type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"maxLength":180}}},"messages":{"type":"array","minItems":1,"maxItems":20,"description":"The conversation so far.","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","minLength":1,"maxLength":4000}}}},"context":{"type":"string","maxLength":12000,"description":"Optional extra grounding context."},"format":{"type":"string","enum":["sse","json"],"default":"sse"},"sandbox":{"type":"boolean","default":false,"description":"Return deterministic, unmetered fixtures for tests and demos."}}},"example":{"person":{"name":"Ada Lovelace"},"messages":[{"role":"user","content":"Summarize her public footprint."}],"format":"json"}}}},"responses":{"200":{"description":"Success. With format=json a single object is returned; otherwise events stream as text/event-stream.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Stable request correlation id."},"X-DeepSearch-Operation":{"schema":{"type":"string"},"description":"The metered operation."},"X-DeepSearch-Metered":{"schema":{"type":"string","enum":["true","false"]}},"X-DeepSearch-Percentage-Charged":{"schema":{"type":"string"},"description":"Whole-number percentage of the current included allowance charged by this request."},"X-DeepSearch-Usage-Remaining":{"schema":{"type":"string"},"description":"Whole-number percentage of included usage remaining after this request."},"X-DeepSearch-Usage-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Exact boundary at which the included weekly allowance resets."},"X-DeepSearch-Usage-Source":{"schema":{"type":"string","enum":["included","extra","mixed"]},"description":"Whether the reservation used included usage, extra credits, or both."},"X-DeepSearch-Credits-Charged":{"schema":{"type":"string"},"deprecated":true,"description":"Deprecated v1 compatibility charge; use X-DeepSearch-Percentage-Charged."},"X-DeepSearch-Allowance-Source":{"schema":{"type":"string","enum":["weekly","coin"]},"deprecated":true,"description":"Deprecated v1 compatibility source; use X-DeepSearch-Usage-Source."},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Deprecation":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate at which it was declared deprecated."},"Sunset":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate after which it may stop responding. Never less than 12 months after Deprecation."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"},"example":{"object":"chat_result","request_id":"req_01HZY8P8V1TXZ6YXMJ56ATJZ1J","metadata":{"api_version":"v1","operation":"chat","request_id":"req_01HZY8P8V1TXZ6YXMJ56ATJZ1J","generated_at":"2026-06-19T12:00:00.000Z"},"usage":{"metered":true,"percentageCharged":1,"remainingPercent":72,"resetAt":"2026-07-01T00:00:00.000Z","source":"included","credits":1,"allowanceSource":"weekly"},"answer":"Ada Lovelace is best known for her notes on Babbage's Analytical Engine.","related_questions":["What did she publish?","Who did she collaborate with?"],"events":[{"type":"text","delta":"Ada Lovelace is best known for "},{"type":"text","delta":"her notes on Babbage's Analytical Engine."},{"type":"related","questions":["What did she publish?","Who did she collaborate with?"]},{"type":"done"}]}},"text/event-stream":{"schema":{"type":"string","description":"A stream of `data: {json}` lines, one StreamEvent each."}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl https://deepsearch.app/api/v1/chat \\\n  -H \"Authorization: Bearer $DEEPSEARCH_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"person\": {\n          \"name\": \"Ada Lovelace\"\n        },\n        \"messages\": [\n          {\n            \"role\": \"user\",\n            \"content\": \"Summarize her public footprint.\"\n          }\n        ],\n        \"format\": \"json\"\n      }'"},{"lang":"JavaScript","label":"Node.js","source":"const res = await fetch(\"https://deepsearch.app/api/v1/chat\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.DEEPSEARCH_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"person\": {\n      \"name\": \"Ada Lovelace\"\n    },\n    \"messages\": [\n      {\n        \"role\": \"user\",\n        \"content\": \"Summarize her public footprint.\"\n      }\n    ],\n    \"format\": \"json\"\n  }),\n});\n\nconst result = await res.json();\nconsole.log(result);"},{"lang":"Python","label":"Python","source":"import os\nimport json\nimport requests\n\nres = requests.post(\n    \"https://deepsearch.app/api/v1/chat\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['DEEPSEARCH_API_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=json.loads(\"{\\\"person\\\":{\\\"name\\\":\\\"Ada Lovelace\\\"},\\\"messages\\\":[{\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"Summarize her public footprint.\\\"}],\\\"format\\\":\\\"json\\\"}\"),\n)\n\nprint(res.json())"}]}},"/api/v1/reverse-image":{"post":{"operationId":"reverse_image","summary":"Find where an image appears online + visually similar images.","description":"Submit an image URL and get candidate public pages, match provenance, and visually similar images. Provider candidates require verification; visual resemblance alone does not establish image reuse. Honest image-appearance matching - DeepSearch does NOT perform facial recognition and never identifies a person from their face. The image is re-hosted privately before it reaches the provider. Reverse-image lookup is Medium usage.","tags":["People research"],"security":[{"bearerAuth":[]}],"x-required-scope":"search","x-rateLimit":{"limit":60,"windowMs":60000},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"For format=json, safely retries the same request and replays the completed JSON response. For SSE, it protects wallet spend but does not replay the stream."},{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Optional correlation id echoed in response headers and usage logs."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imageUrl"],"additionalProperties":false,"properties":{"imageUrl":{"type":"string","format":"uri","maxLength":2048,"description":"https URL of the image to search. Re-hosted privately before the provider is queried. Honest image-appearance matching only - never facial recognition."}}},"example":{"imageUrl":"https://upload.wikimedia.org/wikipedia/commons/a/a4/Ada_Lovelace_portrait.jpg"}}}},"responses":{"200":{"description":"Success. With format=json a single object is returned; otherwise events stream as text/event-stream.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Stable request correlation id."},"X-DeepSearch-Operation":{"schema":{"type":"string"},"description":"The metered operation."},"X-DeepSearch-Metered":{"schema":{"type":"string","enum":["true","false"]}},"X-DeepSearch-Percentage-Charged":{"schema":{"type":"string"},"description":"Whole-number percentage of the current included allowance charged by this request."},"X-DeepSearch-Usage-Remaining":{"schema":{"type":"string"},"description":"Whole-number percentage of included usage remaining after this request."},"X-DeepSearch-Usage-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Exact boundary at which the included weekly allowance resets."},"X-DeepSearch-Usage-Source":{"schema":{"type":"string","enum":["included","extra","mixed"]},"description":"Whether the reservation used included usage, extra credits, or both."},"X-DeepSearch-Credits-Charged":{"schema":{"type":"string"},"deprecated":true,"description":"Deprecated v1 compatibility charge; use X-DeepSearch-Percentage-Charged."},"X-DeepSearch-Allowance-Source":{"schema":{"type":"string","enum":["weekly","coin"]},"deprecated":true,"description":"Deprecated v1 compatibility source; use X-DeepSearch-Usage-Source."},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Deprecation":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate at which it was declared deprecated."},"Sunset":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate after which it may stop responding. Never less than 12 months after Deprecation."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReverseImageResponse"},"example":{"object":"reverse_image_result","request_id":"req_01HZY8Q2RVIMG9F4X9J7Z1H3AB","result":{"provider":"serpapi-lens","matches":[{"url":"https://en.wikipedia.org/wiki/Ada_Lovelace","title":"Ada Lovelace - Wikipedia","sourceDomain":"en.wikipedia.org"}],"similar":[{"imageUrl":"https://example.com/portrait-variant.jpg","sourceUrl":"https://example.com/article","sourceDomain":"example.com"}]}}},"text/event-stream":{"schema":{"type":"string","description":"A stream of `data: {json}` lines, one StreamEvent each."}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl https://deepsearch.app/api/v1/reverse-image \\\n  -H \"Authorization: Bearer $DEEPSEARCH_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"imageUrl\": \"https://upload.wikimedia.org/wikipedia/commons/a/a4/Ada_Lovelace_portrait.jpg\"\n      }'"},{"lang":"JavaScript","label":"Node.js","source":"const res = await fetch(\"https://deepsearch.app/api/v1/reverse-image\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.DEEPSEARCH_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"imageUrl\": \"https://upload.wikimedia.org/wikipedia/commons/a/a4/Ada_Lovelace_portrait.jpg\"\n  }),\n});\n\nconst result = await res.json();\nconsole.log(result);"},{"lang":"Python","label":"Python","source":"import os\nimport json\nimport requests\n\nres = requests.post(\n    \"https://deepsearch.app/api/v1/reverse-image\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['DEEPSEARCH_API_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=json.loads(\"{\\\"imageUrl\\\":\\\"https://upload.wikimedia.org/wikipedia/commons/a/a4/Ada_Lovelace_portrait.jpg\\\"}\"),\n)\n\nprint(res.json())"}]}},"/api/v1/entity/search":{"post":{"operationId":"entity_search","summary":"Find companies by name.","description":"Submit a company name and get ranked candidate companies (legal name, jurisdiction, status). Grounded in official registries and the public web. Pass a candidate to /entity/dossier for a full profile. Company lookup is Medium usage.","tags":["People research"],"security":[{"bearerAuth":[]}],"x-required-scope":"search","x-rateLimit":{"limit":60,"windowMs":60000},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"For format=json, safely retries the same request and replays the completed JSON response. For SSE, it protects wallet spend but does not replay the stream."},{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Optional correlation id echoed in response headers and usage logs."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":240,"description":"The company name to look up."}}},"example":{"query":"Stripe"}}}},"responses":{"200":{"description":"Success. With format=json a single object is returned; otherwise events stream as text/event-stream.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Stable request correlation id."},"X-DeepSearch-Operation":{"schema":{"type":"string"},"description":"The metered operation."},"X-DeepSearch-Metered":{"schema":{"type":"string","enum":["true","false"]}},"X-DeepSearch-Percentage-Charged":{"schema":{"type":"string"},"description":"Whole-number percentage of the current included allowance charged by this request."},"X-DeepSearch-Usage-Remaining":{"schema":{"type":"string"},"description":"Whole-number percentage of included usage remaining after this request."},"X-DeepSearch-Usage-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Exact boundary at which the included weekly allowance resets."},"X-DeepSearch-Usage-Source":{"schema":{"type":"string","enum":["included","extra","mixed"]},"description":"Whether the reservation used included usage, extra credits, or both."},"X-DeepSearch-Credits-Charged":{"schema":{"type":"string"},"deprecated":true,"description":"Deprecated v1 compatibility charge; use X-DeepSearch-Percentage-Charged."},"X-DeepSearch-Allowance-Source":{"schema":{"type":"string","enum":["weekly","coin"]},"deprecated":true,"description":"Deprecated v1 compatibility source; use X-DeepSearch-Usage-Source."},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Deprecation":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate at which it was declared deprecated."},"Sunset":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate after which it may stop responding. Never less than 12 months after Deprecation."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitySearchResponse"},"example":{"object":"entity_search_result","request_id":"req_01HZY8R3ENTITYSRCH9F4X9J7Z1","companies":[{"kind":"company","id":"stripe-us-de","name":"Stripe","legalName":"Stripe, Inc.","headline":"Payments · San Francisco · ~8000 employees","initials":"ST","confidence":92,"jurisdiction":"us_de","status":"active","tags":["Payments","Private"]}]}},"text/event-stream":{"schema":{"type":"string","description":"A stream of `data: {json}` lines, one StreamEvent each."}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl https://deepsearch.app/api/v1/entity/search \\\n  -H \"Authorization: Bearer $DEEPSEARCH_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"query\": \"Stripe\"\n      }'"},{"lang":"JavaScript","label":"Node.js","source":"const res = await fetch(\"https://deepsearch.app/api/v1/entity/search\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.DEEPSEARCH_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"query\": \"Stripe\"\n  }),\n});\n\nconst result = await res.json();\nconsole.log(result);"},{"lang":"Python","label":"Python","source":"import os\nimport json\nimport requests\n\nres = requests.post(\n    \"https://deepsearch.app/api/v1/entity/search\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['DEEPSEARCH_API_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=json.loads(\"{\\\"query\\\":\\\"Stripe\\\"}\"),\n)\n\nprint(res.json())"}]}},"/api/v1/entity/dossier":{"post":{"operationId":"entity_dossier","summary":"Build a full company profile.","description":"Pass a company from /entity/search (or a minimal {name}) and get a structured business profile - registration, status, executives, estimated financials, funding, locations, corporate structure, and a written summary with cited sources. Public business records only; financial figures are estimates; not an FCRA report. Cached profiles are free.","tags":["People research"],"security":[{"bearerAuth":[]}],"x-required-scope":"dossier","x-rateLimit":{"limit":30,"windowMs":60000},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"For format=json, safely retries the same request and replays the completed JSON response. For SSE, it protects wallet spend but does not replay the stream."},{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Optional correlation id echoed in response headers and usage logs."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["company"],"properties":{"company":{"type":"object","required":["name"],"additionalProperties":true,"description":"The company to profile. Pass a candidate from /entity/search to pin the exact entity.","properties":{"name":{"type":"string","minLength":1,"maxLength":180},"jurisdiction":{"type":"string"},"seedRegistryId":{"type":"string"}}},"refresh":{"type":"boolean","default":false,"description":"Bypass the shared cache and rebuild (always meters)."}}},"example":{"company":{"name":"Stripe","jurisdiction":"us_de"}}}}},"responses":{"200":{"description":"Success. With format=json a single object is returned; otherwise events stream as text/event-stream.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Stable request correlation id."},"X-DeepSearch-Operation":{"schema":{"type":"string"},"description":"The metered operation."},"X-DeepSearch-Metered":{"schema":{"type":"string","enum":["true","false"]}},"X-DeepSearch-Percentage-Charged":{"schema":{"type":"string"},"description":"Whole-number percentage of the current included allowance charged by this request."},"X-DeepSearch-Usage-Remaining":{"schema":{"type":"string"},"description":"Whole-number percentage of included usage remaining after this request."},"X-DeepSearch-Usage-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Exact boundary at which the included weekly allowance resets."},"X-DeepSearch-Usage-Source":{"schema":{"type":"string","enum":["included","extra","mixed"]},"description":"Whether the reservation used included usage, extra credits, or both."},"X-DeepSearch-Credits-Charged":{"schema":{"type":"string"},"deprecated":true,"description":"Deprecated v1 compatibility charge; use X-DeepSearch-Percentage-Charged."},"X-DeepSearch-Allowance-Source":{"schema":{"type":"string","enum":["weekly","coin"]},"deprecated":true,"description":"Deprecated v1 compatibility source; use X-DeepSearch-Usage-Source."},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Deprecation":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate at which it was declared deprecated."},"Sunset":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate after which it may stop responding. Never less than 12 months after Deprecation."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityDossierResponse"},"example":{"object":"entity_dossier_result","request_id":"req_01HZY8S4ENTITYDOSSIER9F4X9","cached":false,"company":{"entityId":"stripe-us-de","name":"Stripe","legalName":"Stripe, Inc.","status":"active","registration":{"jurisdiction":"Delaware, US","entityType":"C Corporation","legalStatus":"Active"},"executives":[{"name":"Patrick Collison","title":"CEO"}],"summary":"Stripe is a payments company headquartered in San Francisco… [1]"}}},"text/event-stream":{"schema":{"type":"string","description":"A stream of `data: {json}` lines, one StreamEvent each."}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl https://deepsearch.app/api/v1/entity/dossier \\\n  -H \"Authorization: Bearer $DEEPSEARCH_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"company\": {\n          \"name\": \"Stripe\",\n          \"jurisdiction\": \"us_de\"\n        }\n      }'"},{"lang":"JavaScript","label":"Node.js","source":"const res = await fetch(\"https://deepsearch.app/api/v1/entity/dossier\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.DEEPSEARCH_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"company\": {\n      \"name\": \"Stripe\",\n      \"jurisdiction\": \"us_de\"\n    }\n  }),\n});\n\nconst result = await res.json();\nconsole.log(result);"},{"lang":"Python","label":"Python","source":"import os\nimport json\nimport requests\n\nres = requests.post(\n    \"https://deepsearch.app/api/v1/entity/dossier\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['DEEPSEARCH_API_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=json.loads(\"{\\\"company\\\":{\\\"name\\\":\\\"Stripe\\\",\\\"jurisdiction\\\":\\\"us_de\\\"}}\"),\n)\n\nprint(res.json())"}]}},"/api/v1/vin":{"post":{"operationId":"vin","summary":"Decode a vehicle by VIN.","description":"Submit a 17-character VIN and get the decoded vehicle profile - year/make/model/trim, engine & drivetrain, body, assembly plant - plus open NHTSA recalls and crash-test safety ratings. Specs/recalls/safety are official NHTSA public data; title/accident history is included only where a history provider is configured. Public vehicle information only; not an FCRA report. Cached VINs are free.","tags":["People research"],"security":[{"bearerAuth":[]}],"x-required-scope":"dossier","x-rateLimit":{"limit":30,"windowMs":60000},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"For format=json, safely retries the same request and replays the completed JSON response. For SSE, it protects wallet spend but does not replay the stream."},{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Optional correlation id echoed in response headers and usage logs."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vin"],"additionalProperties":false,"properties":{"vin":{"type":"string","minLength":11,"maxLength":32,"description":"The 17-character Vehicle Identification Number (no I, O, or Q)."},"refresh":{"type":"boolean","default":false,"description":"Bypass the shared cache and rebuild."}}},"example":{"vin":"1HGCM82633A004352"}}}},"responses":{"200":{"description":"Success. With format=json a single object is returned; otherwise events stream as text/event-stream.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Stable request correlation id."},"X-DeepSearch-Operation":{"schema":{"type":"string"},"description":"The metered operation."},"X-DeepSearch-Metered":{"schema":{"type":"string","enum":["true","false"]}},"X-DeepSearch-Percentage-Charged":{"schema":{"type":"string"},"description":"Whole-number percentage of the current included allowance charged by this request."},"X-DeepSearch-Usage-Remaining":{"schema":{"type":"string"},"description":"Whole-number percentage of included usage remaining after this request."},"X-DeepSearch-Usage-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Exact boundary at which the included weekly allowance resets."},"X-DeepSearch-Usage-Source":{"schema":{"type":"string","enum":["included","extra","mixed"]},"description":"Whether the reservation used included usage, extra credits, or both."},"X-DeepSearch-Credits-Charged":{"schema":{"type":"string"},"deprecated":true,"description":"Deprecated v1 compatibility charge; use X-DeepSearch-Percentage-Charged."},"X-DeepSearch-Allowance-Source":{"schema":{"type":"string","enum":["weekly","coin"]},"deprecated":true,"description":"Deprecated v1 compatibility source; use X-DeepSearch-Usage-Source."},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Deprecation":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate at which it was declared deprecated."},"Sunset":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate after which it may stop responding. Never less than 12 months after Deprecation."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VinResponse"},"example":{"object":"vin_result","request_id":"req_01HZY8T5VINLOOKUP9F4X9J7Z1","cached":false,"vehicle":{"vin":"1HGCM82633A004352","year":2003,"make":"HONDA","model":"Accord","headline":"2003 HONDA Accord EX · Sedan/Saloon","engine":{"cylinders":"6","displacementL":"3","fuelType":"Gasoline"},"recalls":[],"safety":{"airbags":["Front (1st Row (Driver & Passenger))"],"features":[],"ratings":[]},"summary":"The 2003 Honda Accord is a midsize sedan… [1]"}}},"text/event-stream":{"schema":{"type":"string","description":"A stream of `data: {json}` lines, one StreamEvent each."}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-codeSamples":[{"lang":"cURL","label":"cURL","source":"curl https://deepsearch.app/api/v1/vin \\\n  -H \"Authorization: Bearer $DEEPSEARCH_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"vin\": \"1HGCM82633A004352\"\n      }'"},{"lang":"JavaScript","label":"Node.js","source":"const res = await fetch(\"https://deepsearch.app/api/v1/vin\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.DEEPSEARCH_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"vin\": \"1HGCM82633A004352\"\n  }),\n});\n\nconst result = await res.json();\nconsole.log(result);"},{"lang":"Python","label":"Python","source":"import os\nimport json\nimport requests\n\nres = requests.post(\n    \"https://deepsearch.app/api/v1/vin\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['DEEPSEARCH_API_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    json=json.loads(\"{\\\"vin\\\":\\\"1HGCM82633A004352\\\"}\"),\n)\n\nprint(res.json())"}]}},"/api/v1/batch":{"post":{"operationId":"batch","summary":"Run up to 10 operations in one request.","description":"Executes several search / dossier / chat operations in a single round trip.\n\nBatching changes the transport and nothing else. Every item is authenticated by the\nsame key, checked against the same scope, counted against the same per-operation rate\nlimit, served from the same dossier cache, and billed exactly as it would have been on\nits own - each item settles from the provider work it actually performs, while cached dossiers remain free. Items run sequentially.\n\nA batch of 10 is the maximum; queue anything larger, or\nanything slow, with POST /api/v1/jobs.\n\nThe response is 200 whenever the batch itself was valid and authenticated, even if\nevery item failed: each result carries its own status and its own error body. An\n`Idempotency-Key` is extended per item (`<key>:<id>`), so retrying a partially failed\nbatch replays the items that succeeded instead of re-charging them.","tags":["People research"],"security":[{"bearerAuth":[]}],"x-required-scope":"one of search, dossier, chat, per item","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Extended per item as `<key>:<item id>` and replayed item by item."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"},"example":{"operations":[{"id":"a","operation":"search","body":{"query":"Ada Lovelace","type":"name"}},{"id":"b","operation":"dossier","body":{"person":{"name":"Ada Lovelace"}}}]}}}},"responses":{"200":{"description":"The batch ran. Read each result's `status` - a 200 envelope does not mean every item succeeded.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Stable request correlation id."},"X-DeepSearch-Operation":{"schema":{"type":"string"},"description":"The metered operation."},"X-DeepSearch-Metered":{"schema":{"type":"string","enum":["true","false"]}},"X-DeepSearch-Percentage-Charged":{"schema":{"type":"string"},"description":"Whole-number percentage of the current included allowance charged by this request."},"X-DeepSearch-Usage-Remaining":{"schema":{"type":"string"},"description":"Whole-number percentage of included usage remaining after this request."},"X-DeepSearch-Usage-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Exact boundary at which the included weekly allowance resets."},"X-DeepSearch-Usage-Source":{"schema":{"type":"string","enum":["included","extra","mixed"]},"description":"Whether the reservation used included usage, extra credits, or both."},"X-DeepSearch-Credits-Charged":{"schema":{"type":"string"},"deprecated":true,"description":"Deprecated v1 compatibility charge; use X-DeepSearch-Percentage-Charged."},"X-DeepSearch-Allowance-Source":{"schema":{"type":"string","enum":["weekly","coin"]},"deprecated":true,"description":"Deprecated v1 compatibility source; use X-DeepSearch-Usage-Source."},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Deprecation":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate at which it was declared deprecated."},"Sunset":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate after which it may stop responding. Never less than 12 months after Deprecation."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs":{"get":{"operationId":"listJobs","summary":"List async jobs, newest first.","description":"Returns the caller's async API jobs, newest first, in cursor pages.\n\nPage by passing the previous response's `next_cursor` back as `cursor`. `has_more` is false and `next_cursor` is null on the last page, so an agent can loop until `has_more` is false without a separate count. Cursors are opaque: treat them as strings and do not construct one yourself.","tags":["Async jobs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Jobs per page."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response's `next_cursor`."}],"responses":{"200":{"description":"One page of jobs.","content":{"application/json":{"schema":{"type":"object","required":["jobs","next_cursor","has_more"],"properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/ApiJob"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page. Null on the last page."},"has_more":{"type":"boolean","description":"Whether another page exists after this one."}}}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createJob","summary":"Create an async job.","description":"Queues a search, dossier, or chat request and returns immediately. Poll the job, replay events, or receive job webhooks.","tags":["Async jobs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Safely retry job creation. Reusing a key with a different body returns 409."},{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Optional correlation id echoed on the job."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJobRequest"},"example":{"operation":"dossier","input":{"person":{"name":"Ada Lovelace"},"format":"json"},"sandbox":true,"metadata":{"customer_id":"cus_demo"}}}}},"responses":{"200":{"description":"Idempotent replay of an already completed job.","content":{"application/json":{"schema":{"type":"object","required":["job"],"properties":{"job":{"$ref":"#/components/schemas/ApiJob"}}}}}},"202":{"description":"Job queued or running.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Stable request correlation id."},"X-DeepSearch-Operation":{"schema":{"type":"string"},"description":"The metered operation."},"X-DeepSearch-Metered":{"schema":{"type":"string","enum":["true","false"]}},"X-DeepSearch-Percentage-Charged":{"schema":{"type":"string"},"description":"Whole-number percentage of the current included allowance charged by this request."},"X-DeepSearch-Usage-Remaining":{"schema":{"type":"string"},"description":"Whole-number percentage of included usage remaining after this request."},"X-DeepSearch-Usage-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Exact boundary at which the included weekly allowance resets."},"X-DeepSearch-Usage-Source":{"schema":{"type":"string","enum":["included","extra","mixed"]},"description":"Whether the reservation used included usage, extra credits, or both."},"X-DeepSearch-Credits-Charged":{"schema":{"type":"string"},"deprecated":true,"description":"Deprecated v1 compatibility charge; use X-DeepSearch-Percentage-Charged."},"X-DeepSearch-Allowance-Source":{"schema":{"type":"string","enum":["weekly","coin"]},"deprecated":true,"description":"Deprecated v1 compatibility source; use X-DeepSearch-Usage-Source."},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."},"Deprecation":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate at which it was declared deprecated."},"Sunset":{"schema":{"type":"string"},"description":"Present only on a deprecated operation: the IMF-fixdate after which it may stop responding. Never less than 12 months after Deprecation."},"Location":{"schema":{"type":"string"},"description":"Job polling URL."}},"content":{"application/json":{"schema":{"type":"object","required":["job"],"properties":{"job":{"$ref":"#/components/schemas/ApiJob"}}}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs/{id}":{"get":{"operationId":"getJob","summary":"Fetch an async job.","tags":["Async jobs"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/JobId"}],"responses":{"200":{"description":"Job record.","content":{"application/json":{"schema":{"type":"object","required":["job"],"properties":{"job":{"$ref":"#/components/schemas/ApiJob"}}}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs/{id}/events":{"get":{"operationId":"getJobEvents","summary":"Replay async job events.","description":"Returns a Server-Sent Event replay of stored job events.","tags":["Async jobs"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/JobId"}],"responses":{"200":{"description":"Stored SSE event replay.","content":{"text/event-stream":{"schema":{"type":"string","description":"A stream of `data: {json}` lines."}}}},"400":{"description":"The request body was missing, malformed, or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"RFC 6750 challenge, always present on a 401. Leads with `resource_metadata`, which points at the RFC 9728 protected-resource document describing where to get a token. Carries `error=\"invalid_token\"` when a credential was sent and rejected."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"402":{"description":"The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope required for this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than the API accepts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying. Measures the delta to the same window boundary as RateLimit-Reset, so the two agree to within a second; Retry-After is floored at 1 so it never tells a caller to retry immediately."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota as an IETF structured field, e.g. `\"api:v1:search\";q=60;w=60` - q is the quota, w the window in seconds."},"RateLimit":{"schema":{"type":"string"},"description":"Live counters for the same policy, e.g. `\"api:v1:search\";r=59;t=42` - r is remaining, t is seconds until reset."},"RateLimit-Limit":{"schema":{"type":"string"},"description":"Requests allowed in the current window. Also sent on 401, 404, 405 and 429."},"RateLimit-Remaining":{"schema":{"type":"string"},"description":"Requests left in the window."},"RateLimit-Reset":{"schema":{"type":"string"},"description":"SECONDS UNTIL the window resets, per the IETF drafts - not a clock time. The absolute epoch form is on X-RateLimit-Reset."},"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Alias of RateLimit-Limit."},"X-RateLimit-Remaining":{"schema":{"type":"string"},"description":"Alias of RateLimit-Remaining."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"Unix epoch seconds at which the window resets (the conventional X- meaning)."}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"parameters":{"JobId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Async job id."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key in the form `dsk_...`, sent as `Authorization: Bearer <key>`. Create and manage keys in the developer portal."}},"schemas":{"ApiIndex":{"type":"object","required":["object","api_version","endpoints","links"],"properties":{"object":{"const":"api_index"},"api_version":{"const":"v1"},"base_url":{"type":"string","format":"uri"},"documentation":{"type":"object","additionalProperties":{"type":"string"}},"authentication":{"type":"object","additionalProperties":true},"sandbox":{"type":"object","additionalProperties":true},"endpoints":{"type":"array","items":{"type":"object","required":["method","path","summary"],"properties":{"method":{"type":"string"},"path":{"type":"string"},"scope":{"type":["string","null"]},"summary":{"type":"string"}}}},"links":{"type":"array","items":{"type":"object","required":["rel","url","type","title"],"properties":{"rel":{"type":"string"},"url":{"type":"string","format":"uri"},"type":{"type":"string"},"title":{"type":"string"}}}}},"additionalProperties":true},"SandboxContract":{"type":"object","required":["object","public_key","operations","metered"],"properties":{"object":{"const":"sandbox"},"description":{"type":"string"},"how_it_works":{"type":"array","items":{"type":"string"}},"public_key":{"type":"string","const":"dsk_test_deepsearch"},"key_prefix":{"type":"string","const":"dsk_test_"},"body_flag":{"type":"string","const":"sandbox"},"response_header":{"type":"string","const":"X-DeepSearch-Sandbox"},"base_url":{"type":"string","format":"uri"},"operations":{"type":"array","description":"Each supported operation, with the exact fixture events it returns.","items":{"type":"object","required":["operation","path","events"],"properties":{"operation":{"type":"string","enum":["search","dossier","chat"]},"path":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/StreamEvent"}}}}},"batch_path":{"type":"string","format":"uri"},"fixture_subject":{"type":"string"},"metered":{"const":false},"rate_limit":{"type":"object","additionalProperties":true},"limitations":{"type":"array","items":{"type":"string"}},"example":{"type":"string"},"docs_url":{"type":"string","format":"uri"},"signup_url":{"type":"string","format":"uri"}},"additionalProperties":true},"BatchOperation":{"type":"object","required":["body"],"description":"One operation. Give `operation`, or `path` if you would rather copy the endpoint path from this document.","properties":{"id":{"type":"string","maxLength":64,"description":"Echoed on the matching result. Defaults to the item's index."},"operation":{"type":"string","enum":["search","dossier","chat"]},"path":{"type":"string","enum":["/api/v1/search","/api/v1/dossier","/api/v1/chat"]},"body":{"type":"object","description":"Exactly the body that endpoint takes on its own. `format` is ignored - a batch is always collected JSON.","additionalProperties":true}},"additionalProperties":false},"BatchRequest":{"description":"1 to 10 operations, as an object or a bare array.","oneOf":[{"type":"object","required":["operations"],"properties":{"operations":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/BatchOperation"}}},"additionalProperties":false},{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/BatchOperation"}}]},"BatchResponse":{"type":"object","required":["object","request_id","metadata","usage","results"],"properties":{"object":{"const":"batch_result"},"request_id":{"type":"string"},"metadata":{"type":"object","required":["api_version","operation","request_id","generated_at"],"properties":{"api_version":{"const":"v1"},"operation":{"const":"batch"},"request_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"sandbox":{"type":"boolean"}}},"usage":{"type":"object","required":["metered","credits","items"],"description":"Batch totals. Per-item cost is in each result's own `usage`.","properties":{"metered":{"type":"boolean"},"credits":{"type":"integer","minimum":0},"items":{"type":"integer","minimum":1},"succeeded":{"type":"integer","minimum":0},"idempotencyKey":{"type":"string"},"sandbox":{"type":"boolean"}}},"results":{"type":"array","items":{"type":"object","required":["id","operation","status","body"],"properties":{"id":{"type":"string"},"operation":{"type":"string","enum":["search","dossier","chat"]},"status":{"type":"integer","description":"The HTTP status this item would have returned on its own. 504 means the batch ran out of time before the item started, so it was neither executed nor billed."},"body":{"description":"The item's own response envelope, or its error body.","oneOf":[{"$ref":"#/components/schemas/SearchResponse"},{"$ref":"#/components/schemas/DossierResponse"},{"$ref":"#/components/schemas/ChatResponse"},{"$ref":"#/components/schemas/Error"}]}}}}},"additionalProperties":false},"Usage":{"type":"object","required":["metered","percentageCharged","remainingPercent","resetAt","source"],"properties":{"metered":{"type":"boolean"},"percentageCharged":{"type":"integer","minimum":0},"remainingPercent":{"type":"integer","minimum":0,"maximum":100},"resetAt":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["included","extra","mixed"]},"credits":{"type":"integer","minimum":0,"deprecated":true,"description":"Compatibility value for API v1; use percentageCharged."},"allowanceSource":{"type":"string","enum":["weekly","coin"],"deprecated":true},"cached":{"type":"boolean"},"idempotencyKey":{"type":"string"},"replayed":{"type":"boolean"},"sandbox":{"type":"boolean"}},"additionalProperties":false},"ApiMetadata":{"type":"object","required":["api_version","operation","request_id","generated_at"],"properties":{"api_version":{"const":"v1"},"operation":{"type":"string","enum":["search","dossier","chat"]},"request_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"sandbox":{"type":"boolean"}},"additionalProperties":false},"PersonHit":{"type":"object","required":["id","name","initials","confidence","tags"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"headline":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"},"avatarCandidates":{"type":"array","items":{"type":"string","format":"uri"}},"initials":{"type":"string"},"location":{"type":"string"},"age":{"type":"integer"},"confidence":{"type":"number","minimum":0,"maximum":100},"tags":{"type":"array","items":{"type":"string"}},"primaryUsername":{"type":"string"},"primaryPlatform":{"type":"string"},"primaryUrl":{"type":"string","format":"uri"},"seedEmail":{"type":"string"},"seedPhone":{"type":"string"}},"additionalProperties":true},"Source":{"type":"object","required":["id","position","url","title","domain"],"properties":{"id":{"type":"string"},"position":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"domain":{"type":"string"},"snippet":{"type":"string"},"cited":{"type":"boolean"},"publishedAt":{"type":"string"}},"additionalProperties":true},"StreamEvent":{"oneOf":[{"$ref":"#/components/schemas/StatusEvent"},{"$ref":"#/components/schemas/StepEvent"},{"$ref":"#/components/schemas/HitEvent"},{"$ref":"#/components/schemas/SectionEvent"},{"$ref":"#/components/schemas/SummaryEvent"},{"$ref":"#/components/schemas/SourcesEvent"},{"$ref":"#/components/schemas/TextEvent"},{"$ref":"#/components/schemas/RelatedEvent"},{"$ref":"#/components/schemas/SocialEvidenceEvent"},{"$ref":"#/components/schemas/UsageSettlementEvent"},{"$ref":"#/components/schemas/DoneEvent"},{"$ref":"#/components/schemas/ErrorEvent"}],"discriminator":{"propertyName":"type"}},"StatusEvent":{"type":"object","required":["type","label"],"properties":{"type":{"const":"status"},"label":{"type":"string"}}},"StepEvent":{"type":"object","required":["type","step"],"properties":{"type":{"const":"step"},"step":{"type":"object","required":["id","label","status"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"status":{"type":"string","enum":["active","done","empty"]},"icon":{"type":"string"},"note":{"type":"string"}}}}},"HitEvent":{"type":"object","required":["type","hit"],"properties":{"type":{"const":"hit"},"hit":{"$ref":"#/components/schemas/PersonHit"}}},"SectionEvent":{"type":"object","required":["type","key","data"],"properties":{"type":{"const":"section"},"key":{"type":"string","enum":["identity","photos","contact","socials","locations","relatives","work","education","mentions","dating","relationships"]},"data":true}},"SummaryEvent":{"type":"object","required":["type","delta"],"properties":{"type":{"const":"summary"},"delta":{"type":"string"}}},"SourcesEvent":{"type":"object","required":["type","sources"],"properties":{"type":{"const":"sources"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}},"TextEvent":{"type":"object","required":["type","delta"],"properties":{"type":{"const":"text"},"delta":{"type":"string"}}},"RelatedEvent":{"type":"object","required":["type","questions"],"properties":{"type":{"const":"related"},"questions":{"type":"array","items":{"type":"string"}}}},"SocialEvidenceEvent":{"type":"object","description":"Additive social-discovery event. Clients may ignore this family if they only need final hits.","required":["type"],"properties":{"type":{"type":"string","enum":["social_account_found","account_updated","cluster_updated","evidence","avatar_updated"]}},"additionalProperties":true},"UsageSettlementEvent":{"type":"object","description":"Authoritative post-run usage settlement. For SSE responses this event supersedes the provisional usage headers sent before provider work began.","required":["type","usage","snapshot","actualCostUsd","chargedUnits"],"properties":{"type":{"const":"usage"},"usage":{"type":"object","required":["percentageCharged","remainingPercent","resetAt","source"],"properties":{"percentageCharged":{"type":"integer","minimum":0},"remainingPercent":{"type":"integer","minimum":0,"maximum":100},"resetAt":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["included","extra","mixed"]}},"additionalProperties":true},"snapshot":{"type":"object","additionalProperties":true},"actualCostUsd":{"type":"number","minimum":0},"chargedUnits":{"type":"integer","minimum":0}}},"DoneEvent":{"type":"object","required":["type"],"properties":{"type":{"const":"done"},"partial":{"type":"boolean"}}},"ErrorEvent":{"type":"object","required":["type","message"],"properties":{"type":{"const":"error"},"message":{"type":"string"}}},"SearchResponse":{"type":"object","required":["object","request_id","metadata","usage","hits","events"],"properties":{"object":{"const":"search_result"},"request_id":{"type":"string"},"metadata":{"$ref":"#/components/schemas/ApiMetadata"},"usage":{"$ref":"#/components/schemas/Usage"},"hits":{"type":"array","items":{"$ref":"#/components/schemas/PersonHit"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/StreamEvent"}}}},"DossierResponse":{"type":"object","required":["object","request_id","metadata","usage","cached","dossier","events"],"properties":{"object":{"const":"dossier_result"},"request_id":{"type":"string"},"metadata":{"$ref":"#/components/schemas/ApiMetadata"},"usage":{"$ref":"#/components/schemas/Usage"},"cached":{"type":"boolean"},"dossier":{"type":"object","required":["summary","sections","sources"],"properties":{"summary":{"type":"string"},"sections":{"type":"object","additionalProperties":true},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}},"events":{"type":"array","items":{"$ref":"#/components/schemas/StreamEvent"}}}},"ChatResponse":{"type":"object","required":["object","request_id","metadata","usage","answer","related_questions","events"],"properties":{"object":{"const":"chat_result"},"request_id":{"type":"string"},"metadata":{"$ref":"#/components/schemas/ApiMetadata"},"usage":{"$ref":"#/components/schemas/Usage"},"answer":{"type":"string"},"related_questions":{"type":"array","items":{"type":"string"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/StreamEvent"}}}},"ReverseImageResponse":{"type":"object","required":["object","request_id","result"],"properties":{"object":{"const":"reverse_image_result"},"request_id":{"type":"string"},"result":{"type":"object","required":["matches","similar","provider"],"properties":{"provider":{"type":"string","description":"The connector that ran, or 'none'."},"matches":{"type":"array","description":"Candidate public pages. Visual similarity is not proof of image reuse; consult matchKind and evidence.","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"sourceDomain":{"type":"string"},"thumbnailUrl":{"type":"string"},"matchKind":{"type":"string","enum":["verified","provider_exact","visual","unverified"]},"evidence":{"type":"object","properties":{"status":{"type":"string","enum":["unread","unavailable","page_read","image_verified"]},"reason":{"type":"string"}}}}}},"similar":{"type":"array","description":"Visually similar images.","items":{"type":"object","properties":{"imageUrl":{"type":"string"},"thumbnailUrl":{"type":"string"},"sourceUrl":{"type":"string"},"sourceDomain":{"type":"string"}}}}}}}},"EntitySearchResponse":{"type":"object","required":["request_id","companies"],"properties":{"object":{"const":"entity_search_result"},"request_id":{"type":"string"},"companies":{"type":"array","description":"Candidate companies, highest confidence first.","items":{"type":"object","properties":{"kind":{"const":"company"},"id":{"type":"string"},"name":{"type":"string"},"legalName":{"type":"string"},"headline":{"type":"string"},"jurisdiction":{"type":"string"},"status":{"type":"string","enum":["active","dissolved","unknown"]},"confidence":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"EntityDossierResponse":{"type":"object","required":["request_id","company"],"properties":{"object":{"const":"entity_dossier_result"},"request_id":{"type":"string"},"cached":{"type":"boolean"},"company":{"type":"object","description":"The assembled CompanyProfile (registration, executives, financials estimates, locations, linkage, contact, mentions, sources, summary).","additionalProperties":true}}},"VinResponse":{"type":"object","required":["request_id","vehicle"],"properties":{"object":{"const":"vin_result"},"request_id":{"type":"string"},"cached":{"type":"boolean"},"vehicle":{"type":"object","description":"The decoded VehicleProfile (identity, engine, safety, recalls, history, sources, summary). Specs/recalls/safety from NHTSA.","additionalProperties":true}}},"CreateJobRequest":{"type":"object","required":["operation","input"],"properties":{"operation":{"type":"string","enum":["search","dossier","chat"]},"input":{"oneOf":[{"type":"object","required":["query"],"additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":240,"description":"Name, phone, email, or username to look up."},"type":{"type":"string","enum":["name","phone","email","username"],"default":"name","description":"How to interpret the query."},"platforms":{"description":"For a username search, restrict discovery to specific platforms.","oneOf":[{"type":"string","maxLength":320},{"type":"array","maxItems":8,"items":{"type":"string","enum":["linkedin","instagram","x","tiktok","facebook","youtube","reddit","snapchat"]}}]},"format":{"type":"string","enum":["sse","json"],"default":"sse","description":"sse streams events; json returns one collected object."},"sandbox":{"type":"boolean","default":false,"description":"Return deterministic, unmetered fixtures for tests and demos."}}},{"type":"object","required":["person"],"properties":{"person":{"type":"object","required":["name"],"additionalProperties":true,"description":"The subject to profile. Pass a candidate from /search to focus the result.","properties":{"name":{"type":"string","minLength":1,"maxLength":180},"headline":{"type":"string","maxLength":500},"confidence":{"type":"number","minimum":0,"maximum":100},"tags":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":80}},"primaryUsername":{"type":"string"}}},"refresh":{"type":"boolean","default":false,"description":"Bypass the shared cache and rebuild (always meters)."},"format":{"type":"string","enum":["sse","json"],"default":"sse"},"sandbox":{"type":"boolean","default":false,"description":"Return deterministic, unmetered fixtures for tests and demos."}}},{"type":"object","required":["person","messages"],"properties":{"person":{"type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"maxLength":180}}},"messages":{"type":"array","minItems":1,"maxItems":20,"description":"The conversation so far.","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","minLength":1,"maxLength":4000}}}},"context":{"type":"string","maxLength":12000,"description":"Optional extra grounding context."},"format":{"type":"string","enum":["sse","json"],"default":"sse"},"sandbox":{"type":"boolean","default":false,"description":"Return deterministic, unmetered fixtures for tests and demos."}}}],"description":"The request body for the selected operation."},"sandbox":{"type":"boolean","default":false,"description":"Run the job against deterministic unmetered fixtures."},"metadata":{"type":"object","additionalProperties":true}},"additionalProperties":false},"ApiJob":{"type":"object","required":["object","id","status","operation","request_id","sandbox","created_at","updated_at","completed_at","error","links"],"properties":{"object":{"const":"job"},"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"operation":{"type":"string","enum":["search","dossier","chat"]},"request_id":{"type":["string","null"]},"sandbox":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"error":{"type":["string","null"]},"result":{"oneOf":[{"$ref":"#/components/schemas/SearchResponse"},{"$ref":"#/components/schemas/DossierResponse"},{"$ref":"#/components/schemas/ChatResponse"},{"type":"null"}]},"links":{"type":"object","required":["self","events"],"properties":{"self":{"type":"string"},"events":{"type":"string"}}}}},"DeveloperStatus":{"type":"object","required":["enabled","status","api_version","base_url","docs_url","openapi_url","changelog_url","features"],"properties":{"enabled":{"type":"boolean"},"status":{"type":"string","enum":["operational","disabled"]},"api_version":{"const":"v1"},"base_url":{"type":"string","format":"uri"},"docs_url":{"type":"string","format":"uri"},"openapi_url":{"type":"string","format":"uri"},"changelog_url":{"type":"string","format":"uri"},"usage_export_url":{"type":"string","format":"uri"},"endpoints":{"type":"array","items":{"type":"object","additionalProperties":true}},"mcp":{"type":"object","additionalProperties":true},"features":{"type":"array","items":{"type":"object","required":["id","label","description"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}}}},"latest_changes":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogEntry"}}}},"ChangelogEntry":{"type":"object","required":["version","date","title","changes"],"properties":{"version":{"type":"string"},"date":{"type":"string","format":"date"},"title":{"type":"string"},"changes":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"A stable, machine-branchable error code."},"message":{"type":"string","description":"A human-readable explanation. On 401/402 it is phrased for the agent to relay to its user."},"action":{"type":"string","enum":["direct_user_to_url"],"description":"Present on onboarding-gated errors (401/402): the agent should send the user to `url`."},"url":{"type":"string","description":"Where to direct the user (sign-in required)."},"docs_url":{"type":"string","description":"Public API overview the agent can also share."}}}}}}}}