Ask

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.

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?"}'

{
  "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:

{ "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`	`{}`

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.

Get started

Connect your agents

CLI

API

MCP

Follow-up questions

Streaming

​Follow-up questions

​Streaming

Follow-up questions

Streaming