v4

latestOpenAPI 3.1.02026-08-01207318738.7 KB

Submit an AI job

Submit a new AI job for asynchronous execution. The AI will analyze the prompt, generate and execute queries against the specified model, and produce a summarized answer. Jobs are processed by a background worker and typically complete within 15–60 seconds. Use GET /api/v1/ai/jobs/{jobId} to poll for status, or configure a webhookUrl to receive a notification when the job completes. Optionally continue an existing conversation by providing a conversationId. The effective user's per-connector AI toggles (set in the chat + menu) govern which integration tools the agent may use.

post/api/v1/ai/jobs

Query parameters

userIdstring uuid

Target user membership ID (for org-scoped API keys)

Request body

branchIdstring uuid

Optional branch ID for the model. Must be a branch of the shared model specified by modelId. Queries run against the branch model, and if the AI makes model changes (organizations with agentic modeling enabled), they are written to this branch instead of a newly created one. If omitted and the AI makes model changes, a new branch is created automatically.

conversationIdstring uuid

Conversation ID to continue an existing conversation thread. The AI will have access to the context from previous jobs in the same conversation. If omitted, a new conversation is created. Only one active job can exist per conversation.

modelIdstring uuid required

The UUID of the model to query against. Must be a shared model, or a shared-extension model usable as a workbook base.

progressWebhookEnabledboolean

When true, real-time progress events are POSTed to webhookUrl during execution (e.g., "Searching for revenue fields", "Query returned 42 rows"). Requires webhookUrl. Progress events are best-effort: single attempt, no retries, failures do not affect job execution.

promptstring required

The natural language prompt for the AI to process. The AI will analyze your question, generate appropriate queries, execute them, and return a summarized answer.

topicNamestring

Topic name to scope query generation. Topics define a set of related views and their join paths. If not provided, the AI will automatically select the best topic. Use the pick-topic endpoint to determine the right topic programmatically.

webhookMetadataobject

Arbitrary metadata object that will be included unchanged in webhook payloads. Use this to correlate webhook notifications with your own system (e.g., tracking IDs, channel references).

webhookSigningSecretstring

Secret key for HMAC-SHA256 webhook payload signing. When provided, each webhook request includes X-Omni-Signature and X-Omni-Signature-Timestamp headers for verification. Required if webhookUrl is specified.

webhookUrlstring uri

URL to receive webhook POSTs. Always receives a terminal event (job.complete, job.failed, or job.denied) when the job finishes; a job.denied event (e.g. the organization is over its AI credit limit) additionally carries a reason field. When progressWebhookEnabled is true, also receives real-time progress events during execution.

Example request

{
  "attachments": [
    {
      "data": "iVBORw0KGgoAAAANSUhEUgAA...",
      "mimeType": "image/png",
      "name": "legacy-dashboard-screenshot.png"
    }
  ],
  "branchId": "550e8400-e29b-41d4-a716-446655440000",
  "conversationId": "660e8400-e29b-41d4-a716-446655440001",
  "modelId": "770e8400-e29b-41d4-a716-446655440002",
  "progressWebhookEnabled": true,
  "prompt": "What are the top 5 products by revenue this quarter?",
  "topicName": "order_items",
  "webhookMetadata": {
    "externalId": "task-123",
    "slackChannel": "C0123456789"
  },
  "webhookUrl": "https://example.com/webhooks/omni"
}

Response

Job created and queued for execution. Use the returned jobId to poll for status or retrieve results.

conversationIdstring uuid required

The conversation ID for this job. Pass this as conversationId in subsequent job submissions to continue the conversation with additional context.

jobIdstring uuid required

The unique identifier for the created job. Use this to poll status via GET /api/v1/ai/jobs/{jobId} or retrieve results via GET /api/v1/ai/jobs/{jobId}/result.

omniChatUrlstring uri required

URL to view this conversation in the Omni chat interface. Opens the chat session where the job actions and results are visible.

Example response

{
  "conversationId": "660e8400-e29b-41d4-a716-446655440001",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "omniChatUrl": "https://my-org.omni.co/chat/660e8400-e29b-41d4-a716-446655440001"
}