Blueprints & your schema

The customer-defined schema behind every dataset — discover it, never guess it

A Blueprint is the schema of one DeepSieve dataset: which entities exist (e.g. companies, funds), their columns, and their relationships. It's defined by its owner during onboarding — it is different for every customer and can change after you integrate.

The boundary in one sentence: an agent can build a new Blueprint end-to-end, but can never alter a live one — editing a live schema is human-only, enforced at the auth gate regardless of scopes.

That has one hard consequence for integrators: never hardcode entity or column names. Discover them — GET /v1/blueprints lists the ids and marks the active one, then read the schema of the one you mean:

bash

curl -s $BASE_URL/v1/blueprints/{blueprint_id} -H "Authorization: Bearer $DEEPSIEVE_API_KEY"

Response· json

{"object": "blueprint",
 "blueprint": {"domain_name": "…", "entities": ["companies", "funds"]},
 "entities": [{"key": "companies",
               "columns": [{"name": "name", "type": "text"},
                           {"name": "hq_city", "type": "text"}]}]}

Exports embed the same schema metadata so downstream consumers stay self-describing.

Creating a Blueprint (agent-drivable)

A key with blueprint:create can take a new Blueprint through onboarding end-to-end — describe, review the inferred draft, request adjustments, approve. That includes an additional Blueprint on an org that already has one: the draft is built separately, so approving it never touches the live one. The plan's Blueprint allowance still applies; past it you get 402 plan_upgrade_required, and topping up credit won't lift it.

bash

# 1. Start: describe the research domain in natural language → 202
curl -s -X POST $BASE_URL/v1/blueprints/drafts \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt": "Track industrial-automation vendors: products, funding, key people"}'

# 2. Poll until status is "ready" (or "awaiting_input"), then REVIEW the draft
curl -s $BASE_URL/v1/blueprints/drafts/{id} -H "Authorization: Bearer $DEEPSIEVE_API_KEY"
#    → { "draft_blueprint": {...}, "follow_up_questions": [...] }

# 3. Answer follow-ups and/or ask the inference agent for adjustments — one
#    synchronous chat turn: the reply, the measured changes, and `applied`
curl -s -X POST $BASE_URL/v1/blueprints/drafts/{id}/chat \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY" -H "Content-Type: application/json" \
  -d '{"message": "add a founded_year column to companies"}'
#    → { "reply": { "content": "...", "questions": [], "not_done": [] },
#        "changes": [ { "kind": "add_column", "entity": "companies", "tier": "green", ... } ],
#        "applied": true, "draft_revision": 2, ... }
#    (send your own "message_id" UUID to make retries idempotent; without one a
#     retry is a second model call. `/adjust` — 202 → poll — is deprecated.)

# 4. Approve → real tables are created and the draft's status becomes "active".
#    It does not change which Blueprint a call reads when it omits blueprint_id:
#    take the new id from GET /v1/blueprints and pass it.
curl -s -X POST $BASE_URL/v1/blueprints/drafts/{id}/approve \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY"                # 202 → poll until "active"

Domain knowledge on a draft

A draft can hold domain knowledge (see below) before it is approved, and its notes go live with it. Expertise your human states in their description, an answer to a follow-up question or a setup-chat message is saved as a note in their own words, marked origin.captured: true: show those to them before you approve.

GET /v1/blueprints/drafts/{session_id}/knowledge lists the draft's notes, every status (blueprint:read). Before the draft exists it returns no entries.
POST to the same path adds one, and PATCH / DELETE …/knowledge/{kid}, POST …/knowledge/{kid}/retire and POST …/knowledge/{kid}/restore change one. Each takes the live Blueprint's body and rules, including revision and 409 knowledge_revision_conflict on an edit and 409 knowledge_conflict with on_conflict, with the scope checked against the draft. Writes need blueprint:create, not knowledge:write; send an Idempotency-Key. Write only what your human told you.
On a write, 409 session_busy means a change to the draft is still running: retry after Retry-After. 409 conflict with details.reason: no_draft means the draft does not exist yet. With already_built the draft was approved and its notes are final: do not retry, write the live Blueprint's knowledge instead.

When the draft holds no knowledge yet, it asks one follow-up question, domain_knowledge, marked skippable: true. Ask your human. If they have nothing to add, send {question_id, skip: true} to /answers: the question is recorded as null and nothing re-runs. Never answer it from your own knowledge.

Editing a live schema — human-only

Edits to an already-live Blueprint (any Blueprint that has been approved) are refused for API keys and MCP sessions at the gate itself, regardless of role or scopes — an agent may propose a change to its human (POST /v1/blueprints/{blueprint_id}/propose, which returns each change's tier and writes nothing), never apply one. Humans edit in-app at Edit Blueprint (/blueprint) with data-safety tiers (green auto, amber confirm, red refused).

Domain knowledge — open to agents

In the app this is Custom Guidance (called knowledge in the API).

Knowledge is not the schema. It is what your team knows about the field: where the reliable data is, which sources mislead, what a value means and its plausible range, what to leave out. Later runs carry each entry wherever it applies, and it changes no table and no stored value, so an agent with knowledge:write and a member role may write it: /v1/blueprints/{blueprint_id}/knowledge (list, add, edit, retire, restore, delete), the MCP knowledge tools, or deepsieve knowledge. Write only what a person stated or what you verified from a source; knowledge guides research and is never evidence.

GET /v1/research/runs/{run_id}/knowledge says what a run's knowledge did, and a cell's citation (receipts=true) carries knowledge_decided (what an entry decided there, by code) and knowledge_cited (what QA's verdict cited, a model's claim). Never add the two. See the endpoint reference for the shapes.