Skip to main content
POST

Running a skill

Including a skill’s /identifier anywhere in prompt runs that saved skill.

Dashboard creation and publishing

The AI can build and modify dashboards. A dashboard it creates is published immediately. An edit to an existing dashboard lands on that dashboard’s draft. The AI can publish the draft when the prompt explicitly requests it (for example, “fix the revenue tile and publish it”). Publishing makes the draft live for everyone who views the dashboard.
Publishing takes any changes already in the draft live with it, not just the edits made by the AI in this job. The AI’s response will disclose when it published a dashboard and when that publish included draft changes made by someone else.
A publish request may be refused when:
  • No draft exists on the dashboard
  • The draft is stale, meaning it has been superseded by a more recent published version
  • The organization requires pull requests to merge branch changes
  • Publishing would disable the dashboard’s scheduled deliveries. In the browser, this requires user confirmation; headless jobs refuse rather than disable deliveries silently.

Choosing the LLM

By default, a job runs on the organization’s default LLM and thinking level. Pass requestedLlm to pin the job to a different one instead. Use List available LLMs to retrieve a list of the LLMs the user the job runs as may pick. A pick that user isn’t allowed to make returns a an error naming only the refused LLM.

Webhook notifications

If a webhookUrl is configured, it will receive a POST with the following body when the job reaches a terminal state:
The request will also include the following signature headers:
  • X-Omni-Signature-Timestamp - unix
  • X-Omni-Signature - (sha256=HMAC(timestamp.body, secret))
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 with credentials.

Authorizations

Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Query Parameters

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

Body

application/json
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.

Maximum string length: 400000
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.

executionProfile
enum<string>

Optional execution profile. The only accepted value is data: the job answers a single data question using a restricted, query-only toolset, with no dashboard creation, report building, or model edits. The response's dataResult field (see Stream AI job results) describes the query it ran.

This setting applies to this job only, so conversationId can continue any conversation — though continuing one this way isn't a designed use. On a new conversation, it also starts the conversation as a data conversation, which is hidden from conversation listings. Omit executionProfile to run a standard job.

Available options:
data
Example:

"data"

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 restrictions or the API will return a 404. Use the Pick topic endpoint 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 LLMs are for organization admins only, and embedded users can't pick one. Anything else returns a 422; 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.

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

Attachments are stored internally and never exposed over the public API. They will not appear in job status responses, results, or webhook payloads.
Maximum array length: 5

Response

AI job created successfully

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.