{"openapi":"3.1.0","info":{"title":"DeepSearch API","version":"1.0.0","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."}],"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","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"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"},{"type":"array","items":{"type":"string"}}]},"format":{"type":"string","enum":["sse","json"],"default":"sse","description":"sse streams events; json returns one collected object."}}},"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"},"example":{"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"}}}},"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 { events } = await res.json();\nconsole.log(events);"},{"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()[\"events\"])"}]}},"/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","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},"headline":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":100},"tags":{"type":"array","items":{"type":"string"}},"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"}}},"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"},"example":{"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"}}}},"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 { events } = await res.json();\nconsole.log(events);"},{"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()[\"events\"])"}]}},"/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","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}}},"messages":{"type":"array","minItems":1,"description":"The conversation so far.","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","minLength":1}}}},"context":{"type":"string","description":"Optional extra grounding context."},"format":{"type":"string","enum":["sse","json"],"default":"sse"}}},"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"},"example":{"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"}}}},"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 { events } = await res.json();\nconsole.log(events);"},{"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()[\"events\"])"}]}}},"components":{"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":{"StreamEvent":{"type":"object","description":"One event in a result stream. `type` discriminates the payload (status, hit, section, summary, sources, text, related, done, error).","required":["type"],"properties":{"type":{"type":"string"}},"additionalProperties":true},"EventsResponse":{"type":"object","description":"The collected response returned when format=json.","required":["events"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/StreamEvent"}}}},"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."}}}}}}}}