{"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 the account wallet: 10 requests per 7-day\nwindow, then 1 coin per metered request. Cached dossiers are free.\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.","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/account"},"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":"Developer platform discovery and changelog endpoints."}],"security":[{"bearerAuth":[]}],"paths":{"/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-Credits-Charged":{"schema":{"type":"string"}},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Limit":{"schema":{"type":"string"}},"RateLimit-Remaining":{"schema":{"type":"string"}},"RateLimit-Reset":{"schema":{"type":"string"}}},"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,"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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"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 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={\n      \"query\": \"Ada Lovelace\",\n      \"type\": \"name\",\n      \"format\": \"json\"\n    },\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 does not spend wallet credits.","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-Credits-Charged":{"schema":{"type":"string"}},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Limit":{"schema":{"type":"string"}},"RateLimit-Remaining":{"schema":{"type":"string"}},"RateLimit-Reset":{"schema":{"type":"string"}}},"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,"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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"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 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={\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\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-Credits-Charged":{"schema":{"type":"string"}},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Limit":{"schema":{"type":"string"}},"RateLimit-Remaining":{"schema":{"type":"string"}},"RateLimit-Reset":{"schema":{"type":"string"}}},"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,"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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"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 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={\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\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 the public web pages where that exact image appears, plus visually similar images. 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. Metered as one search credit.","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-Credits-Charged":{"schema":{"type":"string"}},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Limit":{"schema":{"type":"string"}},"RateLimit-Remaining":{"schema":{"type":"string"}},"RateLimit-Reset":{"schema":{"type":"string"}}},"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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"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 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={\n      \"imageUrl\": \"https://upload.wikimedia.org/wikipedia/commons/a/a4/Ada_Lovelace_portrait.jpg\"\n    },\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. Metered as one search credit.","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-Credits-Charged":{"schema":{"type":"string"}},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Limit":{"schema":{"type":"string"}},"RateLimit-Remaining":{"schema":{"type":"string"}},"RateLimit-Reset":{"schema":{"type":"string"}}},"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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"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 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={\n      \"query\": \"Stripe\"\n    },\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-Credits-Charged":{"schema":{"type":"string"}},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Limit":{"schema":{"type":"string"}},"RateLimit-Remaining":{"schema":{"type":"string"}},"RateLimit-Reset":{"schema":{"type":"string"}}},"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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"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 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={\n      \"company\": {\n        \"name\": \"Stripe\",\n        \"jurisdiction\": \"us_de\"\n      }\n    },\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-Credits-Charged":{"schema":{"type":"string"}},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Limit":{"schema":{"type":"string"}},"RateLimit-Remaining":{"schema":{"type":"string"}},"RateLimit-Reset":{"schema":{"type":"string"}}},"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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"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 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={\n      \"vin\": \"1HGCM82633A004352\"\n    },\n)\n\nprint(res.json())"}]}},"/api/v1/jobs":{"get":{"operationId":"listJobs","summary":"List recent async jobs.","description":"Returns the caller's 50 most recent async API jobs.","tags":["Async jobs"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Recent jobs.","content":{"application/json":{"schema":{"type":"object","required":["jobs"],"properties":{"jobs":{"type":"array","items":{"$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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"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-Credits-Charged":{"schema":{"type":"string"}},"X-DeepSearch-Sandbox":{"schema":{"type":"string","enum":["true"]}},"RateLimit-Limit":{"schema":{"type":"string"}},"RateLimit-Remaining":{"schema":{"type":"string"}},"RateLimit-Reset":{"schema":{"type":"string"}},"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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"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"}}}},"402":{"description":"The user has no active subscription, or the weekly allowance is spent and no coins remain. The body includes action/url/message - direct the user to subscribe or add credits, 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"}}}},"503":{"description":"A temporary service-wide spend cap was reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/developer/status":{"get":{"operationId":"developerStatus","summary":"Read developer platform status.","tags":["Platform"],"security":[],"responses":{"200":{"description":"Developer platform status and discovery links.","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.","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"}}}}}}}}}}},"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":{"Usage":{"type":"object","required":["metered","credits"],"properties":{"metered":{"type":"boolean"},"credits":{"type":"integer","minimum":0},"allowanceSource":{"type":"string","enum":["weekly","coin"]},"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/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},"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":"Public pages where the image appears.","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"sourceDomain":{"type":"string"},"thumbnailUrl":{"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."}}}}}}}}