DeepSieveDevelopers

Chat with the research agent

Ask why a value says what it says, or request a re-check — visibly, in the customer's own thread

The dataset is the deliverable, but the research agent is what can explain or correct a cell. When your user asks "why does this say $2.4B?" or "that funding number looks stale", you don't have to guess — ask.

Needs runs:write to send and runs:read to read (both in the Agent preset).

Ask a question

bash
curl -s -X POST $BASE_URL/v1/research/runs/{run_id}/chat/messages \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY" -H "Content-Type: application/json" \
  -d '{"content": "Where did the 2024 funding figure come from? Please re-check it.",
       "row_ref": {"table_name": "companies", "record_id": "<uuid>"}}'
Response· json
{"object": "chat_message", "message_id": "…", "status": "running",
 "note": "Your message is visible in the customer's own chat history for this
          report, attributed to this API key."}

row_ref is optional — omit it to ask about the report as a whole.

Chat requires an active plan. A free run previews its first ten rows, and the agent answers from the whole dossier — so this endpoint is 402 on an account without one, including a closed account inside its read-retention year. The refusal happens before any work is started, so it costs nothing and is safe to retry after subscribing. It is not retriable on its own: treat it like the other 402s and surface it to a human.

Read the thread

bash
curl -s $BASE_URL/v1/research/runs/{run_id}/chat \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY"
Response· json
{"object": "chat_thread", "in_flight": false,
 "messages": [
   {"role": "user", "content": "Where did the 2024 funding figure come from?",
    "sent_via": "api", "sent_by_key": "claude-code", "status": "complete"},
   {"role": "agent", "content": "The $2.4B figure comes from…",
    "status": "complete", "actions": [
      {"id": "…", "type": "reverify", "summary": "Re-verifying total_funding"}]}
 ]}

Poll while in_flight is true (a turn takes seconds, not minutes). Answers that changed data list them under actions — each revertible:

bash
curl -s -X POST $BASE_URL/v1/chat/actions/{action_id}/revert \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY"

Your messages are visible, and attributed

This is one shared thread, not a private side channel. Everything you send appears in the customer's own Chat view for that report, labelled "Sent by your agent" with the API key's name — so a person opening their report can always tell which questions they asked and which their agent did.

Two things follow for you:

  • Write for a human audience. Your questions are read by the customer.
  • Don't narrate. Ask when you need an answer or a correction; this isn't a logging channel.

Data changes an answer applies are audited and revertible by either side, and the research agent can never edit the active Blueprint — same boundary as everywhere else.

Chat with the research agent — DeepSieve API