API reference

Every endpoint lives under https://deepsearch.app/api/v1 and accepts a JSON body over POST. Responses stream as Server-Sent Events by default, or return a typed JSON object when you pass "format": "json".

Quickstart

Create a key in the portal, export it, and call your first endpoint:

12345678curl https://deepsearch.app/api/v1/search \  -H "Authorization: Bearer $DEEPSEARCH_API_KEY" \  -H "Content-Type: application/json" \  -d '{        "query": "Ada Lovelace",        "type": "name",        "format": "json"      }'

Authenticate every request with a bearer token in the Authorization header. Keys are created in the developer portal and are shown in full only once - store them somewhere safe and never expose them in client-side code.

1234curl https://deepsearch.app/api/v1/search \  -H "Authorization: Bearer $DEEPSEARCH_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "query": "Ada Lovelace" }'

Scopes

Each key carries scopes that gate which endpoints it can call. New keys are granted all three by default, but production keys can be narrowed to only the endpoints they need and can be given an expiry date or per-key minute limit.

The repo includes dependency-free starters for TypeScript and Python plus reference apps for Node, Next.js server routes, and MCP clients — and a published command-line interface. Keep API keys server-side and start with sandbox: true while wiring parsers and UI states.

12345678910111213import { DeepSearchClient } from "@deepsearch/client";const deepsearch = new DeepSearchClient({  apiKey: process.env.DEEPSEARCH_API_KEY!,});const result = await deepsearch.search({  query: "Ada Lovelace",  type: "name",  sandbox: true,});console.log(result.hits);

@reloadapp/deepsearch is a single self-contained CLI — no runtime dependencies — that shares the same scopes, wallet metering, and sandbox behavior as the REST API. Run it with npx or install it globally as deepsearch. Requires Node.js ≥ 20.9.

123456# Run without installing anythingnpx @reloadapp/deepsearch search "Ada Lovelace" --sandbox# Or install globally, then call `deepsearch`npm install -g @reloadapp/deepsearchdeepsearch --help

Authentication

The CLI resolves your key in order: --api-key › DEEPSEARCH_API_KEY › ~/.deepsearch/config.json (written by deepsearch login, stored with 0600 permissions). Every command takes --json, --sandbox, and --stream.

12345678910# Save a key once (written to ~/.deepsearch/config.json, 0600)deepsearch login# Name search, then a streaming dossierdeepsearch search "Ada Lovelace" --type name --sandboxdeepsearch dossier "Ada Lovelace" --stream# Ask a follow-up, or queue an async job from a payload filedeepsearch chat "Ada Lovelace" "Summarize the public sources" --sandboxdeepsearch jobs create dossier --input @job.json --idempotency-key demo-1

Commands

DeepSearch also exposes a hosted MCP server for agents and IDEs that support Streamable HTTP. Use the same API key as a bearer token; scopes, expiry, rate limits, wallet metering, and onboarding errors behave the same as REST.

1234567891011{  "mcpServers": {    "deepsearch": {      "type": "streamable-http",      "url": "https://deepsearch.app/api/mcp",      "headers": {        "Authorization": "Bearer ${DEEPSEARCH_API_KEY}"      }    }  }}

Sandbox mode returns deterministic Ada Lovelace fixtures for search, dossier, and chat. It still requires a valid scoped API key, but it does not spend credits and includes usage.sandbox, metadata.sandbox, and X-DeepSearch-Sandbox.

12345curl https://deepsearch.app/api/v1/search \  -H "Authorization: Bearer $DEEPSEARCH_API_KEY" \  -H "Content-Type: application/json" \  -H "X-DeepSearch-Sandbox: true" \  -d '{ "query": "anything", "type": "name", "format": "json" }'

API usage draws on the same wallet as the app. Every account gets 10 metered requests per 7-day window; after that, each metered request costs 1 coin.

• The weekly allowance is spent first, then coins - automatically, with no separate configuration.
• /dossier results are cached and shared. A cache hit returns instantly and does not spend credits; only a fresh build meters.
• When the weekly allowance is exhausted and no coins remain, metered requests return 402.
• Default per-key limits are 60/min for search, 30/min for dossier, and 60/min for chat, plus an IP abuse ceiling.
• Production keys can also carry an optional monthly credit budget. Budgeted keys return 402 api_key_budget_exceeded before spending more credits.

Endpoints stream text/event-stream by default - each chunk is a data: line carrying one JSON event. Pass "format": "json" in the body to receive a typed response once the run completes: search_result includes hits, dossier_result includes dossier, and chat_result includes answer.

Clients should ignore unknown event types - new ones may be added over time without a version bump.

Send Idempotency-Key on retries. For format=json, DeepSearch stores and replays the completed JSON response when the same key and body are used again. If the same key is reused with a different body, the API returns 409 idempotency_conflict.

• For SSE requests, idempotency protects wallet spend but does not replay a prior event stream.
• Responses include X-Request-Id, X-DeepSearch-Metered, X-DeepSearch-Credits-Charged, and standard RateLimit-* headers.
• Request bodies are capped at 64KB; chat requests accept up to 20 messages.

Queue long-running API work through POST /api/v1/jobs. Jobs support idempotent creation, background execution, polling, stored SSE replay, sandbox mode, and signed webhook delivery.

123456789101112curl https://deepsearch.app/api/v1/jobs \  -H "Authorization: Bearer $DEEPSEARCH_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: demo-job-1" \  -d '{    "operation": "dossier",    "input": {      "person": { "name": "Ada Lovelace" },      "format": "json"    },    "sandbox": true  }'

Webhooks notify your backend when background work finishes. Endpoints receive signed JSON with a stable event id, type, v1 API version, timestamp, and event data.

123X-DeepSearch-Event: job.succeededX-DeepSearch-Delivery: evt_...X-DeepSearch-Signature: t=1760000000,v1=<hmac_sha256>

The developer portal includes usage charts, request tables, key breakdowns, credits, cache hit rate, latency, MCP vs REST transport, errors, and request IDs. The same window can be exported as CSV from the portal or from /api/developer/usage/export?windowDays=30.

DeepSearch is for public-footprint research only. Keep API keys server-side, use the narrowest key scopes that work for your integration, and preserve X-Request-Id in your logs for auditability.

• Do not scrape login-gated, private, or paywalled profiles.
• Do not collect breached contents, passwords, secrets, or credentials.
• Do not make credit, housing, employment, insurance, education, or similar eligibility decisions from API output.
• Surface sources and confidence so a human can verify important claims.

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.

Body parameters

12345678curl https://deepsearch.app/api/v1/search \  -H "Authorization: Bearer $DEEPSEARCH_API_KEY" \  -H "Content-Type: application/json" \  -d '{        "query": "Ada Lovelace",        "type": "name",        "format": "json"      }'

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

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.

Body parameters

1234567891011121314curl 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"      }'

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

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.

Body parameters

123456789101112131415curl 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"      }'

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

Errors return the matching HTTP status and a JSON body of the shape { "error": { "code", "message" } }. The code is stable and safe to branch on.