--- title: "Submit an AI job" method: POST path: "/api/v1/ai/jobs" tags: ["AI"] --- # Submit an AI job `POST /api/v1/ai/jobs` 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. ## Query parameters - `userId` string, uuid — Target user membership ID (for org-scoped API keys) ## Request body - AiJobSubmitBody - `attachments` AgenticJobAttachment[] — Optional image or PDF attachments (e.g. a screenshot or export of a legacy BI dashboard being migrated) giving the AI additional visual context alongside the prompt. Up to 5 files, sharing a combined 50000-token budget with the rest of the prompt. - `data` string, required — Base64-encoded file content. - `mimeType` string, required — MIME type of the attachment. Must be an image type (e.g. image/png, image/jpeg) or application/pdf. - `name` string — Optional filename, used for display/logging only. - `branchId` string, 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. - `conversationId` string, 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. - `modelId` string, 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. - `progressWebhookEnabled` boolean — 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. - `prompt` string, 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. - `topicName` string — 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. - `webhookMetadata` object — 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). - `webhookSigningSecret` string — 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. - `webhookUrl` string, 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. ## Response `201` Job created and queued for execution. Use the returned jobId to poll for status or retrieve results. - AiJobSubmitResponse - `conversationId` string, uuid, required — The conversation ID for this job. Pass this as conversationId in subsequent job submissions to continue the conversation with additional context. - `jobId` string, 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. - `omniChatUrl` string, uri, required — URL to view this conversation in the Omni chat interface. Opens the chat session where the job actions and results are visible. ## Other responses - `400` — Invalid request body. Common causes: missing or empty prompt, invalid UUID for modelId/branchId/conversationId, invalid webhook URL format. - `401` — Missing or invalid API key. - `403` — Insufficient permissions. The AI jobs API must be enabled for the organization, AI query generation must be enabled, and the user must have appropriate model access. User-scoped API keys cannot act on behalf of other users. - `404` — The specified model was not found in the organization, the branchId does not belong to the specified model, or the topicName does not exist in the model (or is excluded by ai_chat_topics restrictions). - `409` — An active job already exists for the specified conversationId. Wait for the current job to complete before submitting another job to the same conversation. --- [API](https://skmtc.net/omniapp/apis/omni-api.md) · [All operations](https://skmtc.net/omniapp/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omniapp/omni-api/versions/de7cac8b5983/schema)