API reference

Person chat

Ask follow-up questions about a person.

POST/api/v1/chat

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

curl https://deepsearch.app/api/v1/chat \  -H "Authorization: Bearer $DEEPSEARCH_API_KEY" \  -H "Content-Type: application/json" \  -d '{        "person": {          "name": "Ada Lovelace"        },        "messages": [          {            "role": "user",            "content": "Summarize her public footprint."          }        ],        "format": "json"      }'

Example request

Authorization

Authorizationheaderrequired

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

Authentication guide

Body parameters

personobjectrequired

The subject of the conversation. person.name is required.

messagesMessage[]required

The conversation so far. Each message has a role (user or assistant) and content string. At least one message is required.

contextstring

Optional extra grounding context (e.g. a prior dossier summary) to steer the answer.

formatenum

sse to stream the answer token-by-token, or json for the 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": "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"    }  ]}

Example responseapplication/json

Sources & coverage

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.

Usage & caching

Chat settles from the model tokens and paid tools the request actually uses.

Usage & rate limits

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