# 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>"}}'
```

```json-response
{"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 `402`s 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"
```

```json-response
{"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.