API reference

Person dossier

Build a full public-footprint profile for a person.

POST/api/v1/dossier

Scope: dossier
Formats: JSON · SSE
Sandbox: Free fixtures

curl https://deepsearch.app/api/v1/dossier \  -H "Authorization: Bearer $DEEPSEARCH_API_KEY" \  -H "Content-Type: application/json" \  -d '{        "person": {          "name": "Ada Lovelace",          "headline": "Mathematician · London",          "confidence": 82,          "tags": [            "Computing pioneer"          ]        },        "format": "json"      }'

Example request

Authorization

Authorizationheaderrequired

Send Bearer $DEEPSEARCH_API_KEY with the dossier scope. The free sandbox uses the published test key.

Authentication guide

Body parameters

personobjectrequired

The subject to profile. Only person.name is required; pass the full PersonHit from /search to focus on the exact candidate.

person.namestringrequired

The person's full name.

refreshboolean

Bypass the shared cache and rebuild from scratch (this always meters).

Default: false

formatenum

sse to stream sections as they fill, or json for a single collected response.

ssejson

Default: sse

sandboxboolean

Return deterministic, unmetered fixtures for CI, demos, and parser development.

Default: false

Response

JSON responses preserve the operation result and include request metadata, usage, and collected events. SSE delivers progress and result events as they arrive.

Streaming & formats

{  "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"    }  ]}

Example responseapplication/json

Sources & coverage

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.

Usage & caching

A fresh dossier is High usage and covers all nested work. Cached dossiers use no usage.

Usage & rate limits

Examples illustrate the contract. Test request runs the selected deployment; sandbox fixtures are unmetered.