# DeepSieve API

> DeepSieve is a deep-research API: define a schema (Blueprint), start
> research runs from a natural-language query, and read back a cited dataset,
> re-verified while monitoring is on.

## Agent instructions

- SETUP: if you are a coding agent being connected to DeepSieve for the first time, fetch https://deepsieve.ai/setup.md and follow it — it configures the MCP server, skill, and rules file for whichever agent you are
- Base URL: https://deepsieve.ai
- Auth: two ways. MCP over http → browser login (OAuth), no key needed. REST or headless MCP → `Authorization: Bearer ds_live_...` (mint at /settings/api-keys, Agent preset)
- Verify first: `GET /v1/me`
- Discover the schema before querying data: `GET /v1/blueprints` for the ids, then `GET /v1/blueprints/{id}` (never guess columns)
- Test FREE first: `POST /v1/research/runs` with `{"query": "...", "dry_run": true}` → a free simulated run: 202 + Location, completes in ~15s of polling, sample cited rows (nothing billed/persisted)
- Real runs are async: `POST /v1/research/runs` returns 202 + Location; poll `GET /v1/research/runs/{id}` every ~15s until `done`; they bill prepaid credits and take 15-60 min
- Always send `Idempotency-Key` on POST /v1/research/runs — runs bill real money and retries must not double-charge
- Ask the research agent about a finished run (`POST /v1/research/runs/{id}/chat/messages`) — your messages appear in the customer's own chat history attributed to your key, so write for a human reader
- Schema boundary: you may CREATE a new Blueprint (POST /v1/blueprints/drafts) but can NEVER edit the active one — propose changes to your human
- Citations carry a `verdict` (supported…contradicted) and `cited` flag — never present a contradicted or uncited cell as fact
- If an entity-read response has `truncated: true` / `preview_row_cap`, you have a PREVIEW, not the dataset — tell the human
- Errors: every failure has `{error: {code, message, retriable, request_id}}`; `retriable=false` means do NOT retry the same request
- Terminal/CLI: `uv tool install deepsieve-cli` then `deepsieve login` (browser device flow) then `deepsieve --json data get <entity>` — stable exit codes, `--profile` per deployment
- Machine-readable spec: /openapi.json — markdown mirror of any docs page: append `.md` to its URL

## Get started

- [Quickstart](https://deepsieve.ai/developers/index.md): Set up DeepSieve in your coding agent with one prompt
- [Authentication & API keys](https://deepsieve.ai/developers/authentication.md): Scoped, revocable bearer keys — mint, rotate, revoke, and the scope model
- [Your first research run](https://deepsieve.ai/developers/first-run.md): The async job contract — create, poll, read results, retry safely
## API components

- [Blueprints & your schema](https://deepsieve.ai/developers/blueprints-and-data.md): The customer-defined schema behind every dataset — discover it, never guess it
- [Research runs](https://deepsieve.ai/developers/runs.md): Statuses, retries, refunds, depth, and monitoring — the run lifecycle in full
- [Webhooks](https://deepsieve.ai/developers/webhooks.md): Signed run.* and dataset.updated events — Standard Webhooks verification in 10 lines
- [Dataset sync](https://deepsieve.ai/developers/dataset-sync.md): Read the cited dataset incrementally — cursors, updated_since, per-cell citations
- [Global Reports](https://deepsieve.ai/developers/reports.md): Create, edit, and read saved cross-run reports programmatically
- [Chat with the research agent](https://deepsieve.ai/developers/chat.md): Ask why a value says what it says, or request a re-check — visibly, in the customer's own thread
## Integrations

- [The API](https://deepsieve.ai/developers/api.md): There is a REST API — this is its whole surface, one link per component
- [Choosing an integration](https://deepsieve.ai/developers/integrations.md): Which way to connect DeepSieve — MCP, skill, SDK, or raw REST
- [MCP server](https://deepsieve.ai/developers/mcp.md): Add DeepSieve to Claude Code, Cursor, or any MCP client — browser login, no key to paste
- [SDKs](https://deepsieve.ai/developers/sdks.md): Python SDK (generated, typed, sync+async) — TypeScript next
- [CLI](https://deepsieve.ai/developers/cli.md): Run cited research from your terminal — browser sign-in, no key to paste
## Reference

- [Errors](https://deepsieve.ai/developers/errors.md): The typed error envelope and the closed code registry — what to retry, what not to
- [Rate limits & budgets](https://deepsieve.ai/developers/rate-limits.md): RateLimit headers, 429 semantics, and per-key spend ceilings
- [Versioning & stability](https://deepsieve.ai/developers/versioning.md): The /v1 contract — what is promised now, and what is promised at GA
- [Changelog](https://deepsieve.ai/developers/changelog.md): API changes, newest first