OMomni
AI

Create AI job

Changed on

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

post/v1/ai/jobs

Request

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

Query parameters

userIdstring uuid

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.

Request body

modelIdstring uuid required

The ID of the model to run the AI job against

promptstring required

Natural language instruction describing the desired task. Include a skill's /identifier to run that skill.

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

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

topicNamestring

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 restrictions or the API will return a 404. Use the Pick topic endpoint to programmatically determine the right topic.

progressWebhookEnabledboolean

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.

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

webhookSigningSecretstring

An HMAC-SHA256 secret for signing webhook payloads

webhookMetadataobject

Opaque metadata passed back unchanged in webhook payloads

Example request

{
  "requestedLlm": {
    "model": "claude-sonnet-5",
    "provider": "bedrock",
    "thinking": "medium"
  },
  "attachments": [
    {
      "data": "iVBORw0KGgoAAAANSUhEUgAA...",
      "mimeType": "image/png",
      "name": "legacy-dashboard-screenshot.png"
    }
  ]
}

Response

AI job created successfully

jobIdstring uuid

The unique identifier for the created job

conversationIdstring uuid

The conversation ID associated with this job

omniChatUrlstring

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.

Changes

  • 43290040f88fRevision changes
    • breaking

      added required request body

    • info

      api operation id createAIJob was added

    • info

      the endpoint scheme security bearerAuth was added to the API

    • info

      added the new optional query request parameter userId

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the success response with the status