---
title: "Create AI job"
method: POST
path: "/v1/ai/jobs"
tags: ["AI"]
---

# Create AI job

`POST /v1/ai/jobs`

## Request

- Base URL: `https://blobsrus.omniapp.co/api`
- URL: `https://blobsrus.omniapp.co/api/v1/ai/jobs`
- Auth: HTTP bearer

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. The AI chat returned in the response will remain blank until the AI is finished processing.

Use [Get AI job status](/api/ai/get-ai-job-status) 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`.

## Query parameters

- `userId` string, uuid

## Request body

- object
  - `modelId` string, uuid, required: The ID of the model to run the AI job against
  - `prompt` string, required: Natural language instruction describing the desired task. Include a skill's `/identifier` to run that [skill](/ai/skills).
  - `conversationId` string, uuid: Optional conversation ID to continue an existing conversation. With a Personal Access Token or MCP OAuth grant, only the conversation's owner can continue it; any other caller gets a `404`.
  - `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 Omni Agent makes model changes, they are written to this branch instead of a newly created one. If omitted and the Agent makes model changes, a new branch is created automatically.
  - `topicName` string: Topic name to scope query generation. If not provided, the AI will automatically select the best topic based on the prompt. For multi-turn conversations, the AI will carry forward the topic from the previous turn. The topic must exist in the model and be allowed by any [`ai_chat_topics`](/modeling/models/ai-chat-topics) restrictions or the API will return a `404`. Use the [Pick topic endpoint](/api/ai/pick-topic) to programmatically determine the right topic.
  - `requestedLlm` object: Optional LLM to run the job on, as `{ provider, model, thinking? }`. Must be one the organization has approved under AI Hub → LLM settings and that the user the job runs as may pick: [test-only](/ai/settings/llm-settings#test-only) LLMs are for organization admins only, and embedded users can't pick one. Anything else returns a `422`; [List available LLMs](/api/ai/list-available-llms) lists the LLMs that user may pick. Omit to run on the organization default. `model` is the LLM's catalog name on an Omni-hosted provider (e.g. `claude-sonnet-5`) or the id the admin entered for a bring-your-own-key provider. `thinking` is one of `default`, `none`, `low`, `medium`, `high`; which of them an LLM honors depends on the LLM, and one it does not is rejected. Omit `thinking` to run at the organization default's level where the LLM honors it, else `default`.
    - `model` string, required
    - `provider` 'bedrock' | 'anthropic' | 'openai' | 'grok' | 'snowflake_cortex' | 'openai_compatible' | 'fireworks' | 'fireworks_managed' | 'databricks_genie' | 'vertex_ai', required
    - `thinking` 'default' | 'none' | 'low' | 'medium' | 'high'
  - `progressWebhookEnabled` boolean: When `true`, real-time progress events are sent using `POST` to the defined `webhookUrl` during execution (e.g., _"Searching for revenue fields"_, _"Query returned 42 rows"_). **`webhookUrl` is required if enabled.** Progress events are best-effort: single attempt, no retries, failures do not affect job execution.
  - `webhookUrl` string, uri: An optional webhook URL to receive webhook updates. Always receives a terminal event (job.complete or job.failed) when the job finishes. When `progressWebhookEnabled: true`, also receives real-time progress events during execution. **Required if `progressWebhookEnabled: true`.**
  - `webhookSigningSecret` string: An HMAC-SHA256 secret for signing webhook payloads
  - `webhookMetadata` object: Opaque metadata passed back unchanged in webhook payloads
  - `attachments` object[]: Optional image or PDF attachments giving the AI additional visual context alongside the prompt (e.g., a screenshot or export of a legacy Tableau/Power BI/Looker dashboard being migrated). Image files are limited to 3MB each; text files such as CSVs have a ~50KB limit. All attachments in a single request share a combined size budget of roughly 15 MB, shared with your prompt text. Requests can be rejected if the attachments exceed this limit, whether on their own or combined with the prompt. In this case, try attaching fewer files or using smaller/lower-resolution exports. <Note> Attachments are stored internally and never exposed over the public API. They will not appear in job status responses, results, or webhook payloads. </Note>
    - `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`, `image/webp`) or `application/pdf`
    - `name` string: Optional filename, used for display and logging only

## Response `201`

AI job created successfully

- object
  - `jobId` string, uuid: The unique identifier for the created job
  - `conversationId` string, uuid: The conversation ID associated with this job
  - `omniChatUrl` string: URL to view this conversation in the Omni chat interface. Opens the chat session where the job actions and results are visible. The AI Chat will remain blank until the AI job is finished processing. Omitted for MCP requests (`X-MCP-Request: true`) when the organization hides Omni links from MCP clients.

## Other responses

- `400`: Bad Request Possible error messages: - `Invalid modelId/branchId/conversationId` - `Missing required field: prompt` - `Invalid webhook URL format` - `Invalid attachment MIME type (must be image or PDF)` - `Malformed base64 data in attachment` - `Too many attachments (maximum 5)` - `Attachment token budget exceeded (50,000 tokens shared with prompt)` - `Cannot publish: no draft exists on dashboard`
- `403`: Forbidden Possible error messages: - `Feature not enabled` - `Insufficient permissions` - `User-scoped API keys cannot act on behalf of other users` - `Cannot publish: organization requires pull request to merge branch changes` - `Cannot publish: would disable dashboard's scheduled deliveries`
- `404`: Not Found Possible error messages: - `Model not found` - `Topic not found or excluded by ai_chat_topics` - `Conversation not found`
- `409`: Conflict Possible error messages: - `Active job exists for conversation` - `Cannot publish: draft is stale or has been superseded`
- `422`: `requestedLlm` names an LLM the user may not seelct, a thinking level it does not honor, or comes from an embedded user. Use [List available LLMs](/api/ai/list-available-llms) to retrieve a list of available LLMs.
- `429`: Too Many Requests - Rate limit exceeded (60 requests/minute)
- `500`: Internal Server Error

## Changes

- **2026-11-03** `43290040f88f`: 1 breaking, 11 info
  - added required request body
  - api operation id `createAIJob` was added
  - the endpoint scheme security `bearerAuth` was added to the API
  - added the new optional `query` request parameter `userId`
  - …8 more

[Operation history](https://skmtc.dev/omni/apis/omni-api/changes/v1/ai/jobs/post.md)

---

[API](https://skmtc.dev/omni/apis/omni-api.md) - [All operations](https://skmtc.dev/omni/apis/omni-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omni/apis/omni-api/revisions/43290040f88f?raw)