OMomniapp
AI

Submit an 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. 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. A /identifier in the prompt runs that saved skill, edits it when the prompt asks for a change, or deletes it when the prompt asks for that, resolved as the effective user. The effective user's per-connector AI toggles (set in the chat + menu) govern which integration tools the agent may use. The agent can also build and modify dashboards. A dashboard it creates is published; an edit to an existing dashboard lands on that dashboard's draft, and the job publishes that draft only when the prompt asks it to (for example "fix the revenue tile and publish it"). Publishing makes the draft live for everyone who views the dashboard, and takes any changes already sitting in that draft live with it.

post/api/v1/ai/jobs

Request

  • Base URL
    https://omniapp.co (the document declares no server; this is the origin it was published from)
  • URL
    https://omniapp.co/api/v1/ai/jobs
  • Auth
    HTTP bearer

Query parameters

userIdstring uuid

Target user ID (for org-scoped API keys)

Request body

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

conversationIdstring 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. With a personal access token or MCP connection, only the user who owns the conversation can continue it, and anything else returns 404.

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

progressWebhookEnabledboolean

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.

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

topicNamestring

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.

webhookMetadataobject

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

webhookSigningSecretstring

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.

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

Example request

{
  "attachments": [
    {
      "data": "iVBORw0KGgoAAAANSUhEUgAA...",
      "mimeType": "image/png",
      "name": "legacy-dashboard-screenshot.png"
    }
  ],
  "branchId": "550e8400-e29b-41d4-a716-446655440000",
  "conversationId": "660e8400-e29b-41d4-a716-446655440001",
  "modelId": "770e8400-e29b-41d4-a716-446655440002",
  "progressWebhookEnabled": true,
  "prompt": "What are the top 5 products by revenue this quarter?",
  "requestedLlm": {
    "model": "claude-sonnet-5",
    "provider": "bedrock",
    "thinking": "medium"
  },
  "topicName": "order_items",
  "webhookMetadata": {
    "externalId": "task-123",
    "slackChannel": "C0123456789"
  },
  "webhookUrl": "https://example.com/webhooks/omni"
}

Response

Job created and queued for execution. Use the returned jobId to poll for status or retrieve results.

conversationIdstring uuid required

The conversation ID for this job. Pass this as conversationId in subsequent job submissions to continue the conversation with additional context.

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

omniChatUrlstring uri

URL to view this conversation in the Omni chat interface. Opens the chat session where the job actions and results are visible. Omitted for MCP requests (X-MCP-Request: true) when the organization hides Omni links from MCP clients.

Example response

{
  "conversationId": "660e8400-e29b-41d4-a716-446655440001",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "omniChatUrl": "https://my-org.omni.co/chat/660e8400-e29b-41d4-a716-446655440001"
}

Changes