Tasks

A task sends one message into an existing Omni workspace. Omni resolves the appropriate ongoing conversation and returns a public task identifier for polling or streaming.

{
  "workspace_id": "workspace_...",
  "message": "What decisions did we make about launch?",
  "attachments": ["file_01ARZ3NDEKTSV4RRFFQ69G5FAV"]
}

attachments is optional and accepts at most three ready public file IDs. Without attachments, Omni applies normal automatic workspace recall.

Omni resolves the underlying conversation and infrastructure automatically. Unknown request fields return validation_error.

Lifecycle

POST /v1/tasks → queued → running → completed | failed

Use GET /v1/tasks/{task_id} to poll. A completed task includes output.text, an assistant message ID, and validated citations when the answer uses grounded context.

Retry safely

Idempotency-Key is required when creating a task. Reusing the key with the same logical body returns the existing task. Reusing it with a different body returns 409 idempotency_conflict.

See Stream a response for live events and Citations for grounded output.