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.

The request does not accept conversation IDs, thread IDs, run IDs, model selection, retrieval-policy controls, project IDs, or provider placement. Unknown 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.