> ## 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.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/api/ai/create-ai-job",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# 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`.

#### Webhook notifications

If a `webhookUrl` is configured, it will receive a `POST` with the following body when the job reaches a terminal state:

```json
{
  "event_id": "evt_550e8400_COMPLETE_1706123456",
  "jobId": "550e8400-...",
  "status": "COMPLETE",
  "result_summary": "Generated revenue report showing $1.2M total revenue",
  "metadata": { "slack_channel": "C123456" },
  "completed_at": "2025-01-24T10:30:00Z"
}
```

The request will also include the following signature headers:

- `X-Omni-Signature-Timestamp` - `unix`
- `X-Omni-Signature` - (`sha256=HMAC(timestamp.body, secret)`)

<Note>
  The webhook payload includes `result_summary` which can contain actual data values from query results. Full result detail (CSV data, query definitions, actions) requires calling the [Stream AI job results endpoint](/api/ai/stream-ai-job-results) with credentials.
</Note>




## 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: AI
    description: AI-powered query generation
  - 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: Documents
    description: Create, retrieve, and manage documents
  - 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 an organization. Labels can be applied to documents and
      folders to help organize and categorize content.


      **Label types:**

      - **Basic labels**: Can be created and managed by any user

      - **Verified labels**: Indicate curated or officially sanctioned content.
      Admin-only.

      - **Homepage labels**: Appear on the organization homepage. Admin-only.
  - name: Folders
    description: Create and organize content 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`.


        #### Webhook notifications


        If a `webhookUrl` is configured, it will receive a `POST` with the
        following body when the job reaches a terminal state:


        ```json

        {
          "event_id": "evt_550e8400_COMPLETE_1706123456",
          "jobId": "550e8400-...",
          "status": "COMPLETE",
          "result_summary": "Generated revenue report showing $1.2M total revenue",
          "metadata": { "slack_channel": "C123456" },
          "completed_at": "2025-01-24T10:30:00Z"
        }

        ```


        The request will also include the following signature headers:


        - `X-Omni-Signature-Timestamp` - `unix`

        - `X-Omni-Signature` - (`sha256=HMAC(timestamp.body, secret)`)


        <Note>
          The webhook payload includes `result_summary` which can contain actual data values from query results. Full result detail (CSV data, query definitions, actions) requires calling the [Stream AI job results endpoint](/api/ai/stream-ai-job-results) with credentials.
        </Note>
      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`. Use this to query
                    against in-progress model changes.
                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
            example:
              modelId: 123e4567-e89b-12d3-a456-426614174000
              prompt: Analyze sales trends by region for the past year
      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`
          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: <response_code>
        message:
          type: string
          description: Detailed error description
          example: <error_reason>
  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#personal-access-tokens-pat).


        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`

````