> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soma.evarist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask

> Get an answer with citations from a workspace, in one call or streamed.

`POST /v1/workspaces/{workspace_id}/ask` runs Soma's agent: it searches the documents and the knowledge graph as many times as it needs, reads whole documents when a table is involved, then answers.

```bash theme={null}
curl https://staging.soma.evarist.com/v1/workspaces/$WS/ask \
  -H "Authorization: Bearer $SOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "Which seal type is specified for P-101?"}'
```

```json theme={null}
{
  "thread_id": "3608dfcd-…",
  "answer": "P-101 uses a double mechanical seal of type X9 [1].",
  "citations": [
    {
      "number": 1,
      "document_id": "ac54…",
      "document_title": "P-101 datasheet",
      "page": 2,
      "source_url": "https://drive.google.com/…",
      "text": "Seal: double mechanical seal, type X9…"
    }
  ]
}
```

`answer` is markdown with `[N]` markers; `citations` lists the passage behind each `N` that the answer uses.

## Follow-up questions

Pass the `thread_id` of the previous answer:

```json theme={null}
{ "question": "And its maximum temperature?", "thread_id": "3608dfcd-…" }
```

Threads are the same as in the Soma app: the conversation shows up there too.

## Streaming

With `"stream": true` the response is a stream of Server-Sent Events:

| Event | Data |
| - | - |
| `thread` | `{ "thread_id" }` |
| `step` | `{ "tool", "args" }` each time the agent searches or reads |
| `answer` | The same body as the JSON response |
| `error` | `{ "type", "message" }` |
| `done` | `{}` |

```text theme={null}
event: step
data: {"tool": "retrieve_chunks", "args": {"query": "P-101 seal type"}}

event: answer
data: {"thread_id": "…", "answer": "…", "citations": […]}
```

Comment lines (`: keep-alive`) are sent every 15 seconds while the agent works.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.