> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Create 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 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`.
## OpenAPI
````yaml /api/openapi.yaml post /v1/ai/jobs
openapi: 3.1.0
info:
title: Omni API
description: >
The Omni REST API provides programmatic access to your Omni instance for
managing users, documents, queries, schedules, and more.
version: 1.0.0
contact:
name: Omni Support
url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
description: Production
variables:
instance:
default: blobsrus
description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
description: Playground
variables:
instance:
default: blobsrus
description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: Who Am I
description: Inspect your own user permissions
- name: AI
description: AI-powered query generation
- name: AI Credit Controls
description: Manage organization-level AI credit usage
- name: AI Credit Usage
description: Monitor AI credit usage
- name: AI Evals
description: >-
Manage prompt sets and runs used to score AI quality against curated
prompt suites.
- name: AI Model Suggestions
description: Manage AI-generated suggestions for shared models
- name: AI Routines
description: >-
Manage Routines, which are scheduled, recurring AI-powered tasks that run
automatically on your data
- name: Documents v2
description: >
A draft-based workflow for creating and editing documents: create a
document, patch a draft, then publish. Replaces the one-shot `PUT`/`PATCH`
v1 document write endpoints.
- name: Documents
description: Create, retrieve, and manage documents
- name: API Tokens
description: >-
Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
grants)
- name: Connections
description: Manage database connections
- name: Connection environments
description: Manage connection environments database connections
- name: Content
description: Unified content retrieval (documents and folders)
- name: Content migration
description: Export and import dashboards
- name: Content validator
description: Validate content against models and perform find/replace operations
- name: Dashboard downloads
description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
- name: Dashboard filters and controls
description: Read and update dashboard filter and control default values
- name: dbt
description: Manage dbt configuration for connections
- name: Document favorites
description: Favorite and unfavorite documents
- name: Document labels
description: Apply and manage labels on documents
- name: Document permissions
description: Manage document-level access
- name: Labels
description: |
Manage labels in the organization
- name: Folders
description: Create and organize content folders
- name: Folder labels
description: Apply and manage labels on folders
- name: Folder permissions
description: Manage folder-level access
- name: Jobs
description: Check status of asynchronous jobs
- name: Models
description: Create and manage data models
- name: Model branches
description: Manage model branches and merge changes
- name: Model git configuration
description: Manage git configuration for shared models
- name: Queries
description: Execute workbook queries
- name: Schedules
description: Create and manage scheduled tasks
- name: Schedule recipients
description: Manage schedule recipients
- name: Schema refresh schedules
description: Manage automated schema refresh schedules for connections
- name: Topics
description: Retrieve topic information from models
- name: Uploads
description: Manage file uploads
- name: Users
description: Manage users
- name: User attributes
description: Manage user attribute definitions
- name: User groups
description: Manage user groups
- name: User model roles
description: Manage model and connection role assignments for users
- name: User group model roles
description: Manage model and connection role assignments for user groups
- name: Uploads
description: Manage CSV and spreadsheet uploads
paths:
/v1/ai/jobs:
post:
tags:
- AI
summary: Create AI job
description: >
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 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`.
operationId: createAIJob
parameters:
- name: userId
in: query
required: false
schema:
type: string
format: uuid
description: >
**Requires an Organization API key.** The ID of the user to run the
query as.
Personal Access Tokens (PATs) cannot use this parameter to act on
behalf of other users.
example: 9e8719d9-276a-4964-9395-a493189a247c
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- modelId
- prompt
properties:
modelId:
type: string
format: uuid
description: The ID of the model to run the AI job against
prompt:
type: string
description: Natural language instruction describing the desired task
conversationId:
type: string
format: uuid
description: >-
Optional conversation ID to continue an existing
conversation
branchId:
type: string
format: uuid
description: >
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:
type: string
description: >
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.
progressWebhookEnabled:
type: boolean
description: >
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:
type: string
format: uri
description: >
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:
type: string
description: An HMAC-SHA256 secret for signing webhook payloads
webhookMetadata:
type: object
description: Opaque metadata passed back unchanged in webhook payloads
attachments:
type: array
maxItems: 5
description: >
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.
Attachments are stored internally and never exposed over the public API. They will not appear in job status responses, results, or webhook payloads.
items:
type: object
required:
- data
- mimeType
properties:
data:
type: string
minLength: 1
description: Base64-encoded file content
example: iVBORw0KGgoAAAANSUhEUgAA...
mimeType:
type: string
description: >-
MIME type of the attachment. Must be an image type
(e.g., `image/png`, `image/jpeg`, `image/webp`) or
`application/pdf`
example: image/png
name:
type: string
description: Optional filename, used for display and logging only
example: legacy-dashboard-screenshot.png
examples:
basic:
summary: Basic AI job
value:
modelId: 123e4567-e89b-12d3-a456-426614174000
prompt: Analyze sales trends by region for the past year
with_attachment:
summary: AI job with visual context
value:
modelId: 123e4567-e89b-12d3-a456-426614174000
prompt: Re-create this dashboard in Omni
attachments:
- data: iVBORw0KGgoAAAANSUhEUgAAAAUA...
mimeType: image/png
name: tableau-dashboard-export.png
responses:
'201':
description: AI job created successfully
content:
application/json:
schema:
type: object
properties:
jobId:
type: string
format: uuid
description: The unique identifier for the created job
conversationId:
type: string
format: uuid
description: The conversation ID associated with this job
omniChatUrl:
type: string
description: >-
URL to view this conversation in the Omni chat interface.
Opens the chat session where the job actions and results
are visible.
example:
jobId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
conversationId: b2c3d4e5-f6a7-8901-bcde-f12345678901
omniChatUrl: >-
https://blobsrus.omni.co/chat/b2c3d4e5-f6a7-8901-bcde-f12345678901
'400':
description: >
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)`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: |
Forbidden
Possible error messages:
- `Feature not enabled`
- `Insufficient permissions`
- `User-scoped API keys cannot act on behalf of other users`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: |
Not Found
Possible error messages:
- `Model not found`
- `Topic not found or excluded by ai_chat_topics`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: |
Conflict
Possible error messages:
- `Active job exists for conversation`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- bearerAuth: []
components:
schemas:
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
responses:
TooManyRequests:
description: Too Many Requests - Rate limit exceeded (60 requests/minute)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Can be either an [Organization API
Key](/api/authentication#organization-api-keys) or [Personal Access
Token (PAT)](/api/authentication#token-types).
Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
orgApiKey:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Requires an [Organization API
Key](/api/authentication#organization-api-keys). Personal Access Tokens
(PATs) are not supported for this endpoint.
Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`
````