Create an AI Routine

curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/ai/routines \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Weekly user signups",
  "modelId": "770e8400-e29b-41d4-a716-446655440002",
  "prompt": "How many users signed up last week?",
  "schedule": "0 9 ? * MON *",
  "timezone": "America/New_York",
  "destination": {
    "type": "email",
    "recipientEmails": [
      "blob.ross@blobsrus.com",
      "blob.the.builder@blobsrus.com"
    ]
  }
}
'

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "condition": {
    "conditionPrompt": "there are failed orders",
    "conditionType": "RESULTS_PRESENT",
    "interpretation": "<string>",
    "query": {
      "aiGenerated": true,
      "calculations": [],
      "column_totals": {},
      "fields": [
        "orders.id"
      ],
      "fill_fields": [],
      "filters": {
        "orders.status": {
          "case_insensitive": true,
          "kind": "EQUALS",
          "type": "string",
          "values": [
            "failed"
          ]
        }
      },
      "limit": 1,
      "modelId": "770e8400-e29b-41d4-a716-446655440002",
      "pivots": [],
      "row_totals": {},
      "sorts": [],
      "table": "orders",
      "userEditedSQL": "SELECT ${orders.id}\nFROM ${orders}\nWHERE UPPER(${orders.status}) = UPPER('failed')\nLIMIT 1",
      "version": 9
    },
    "verification": {
      "rowCount": 0,
      "conditionMetNow": false
    }
  }
}

{
  "detail": "The delivery condition is too vague or subjective to evaluate. State a specific, measurable condition, then try again.",
  "status": 400,
  "code": "not_expressible"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "code": "shutoff",
  "detail": "The AI credit limit has been reached. Contact your administrator for assistance.",
  "status": 402
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "detail": "<string>",
  "status": 404
}

{
  "detail": "<string>",
  "status": 429
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "detail": "Omni was temporarily unable to compose or verify the delivery condition. Try again shortly.",
  "status": 503
}

POST

routines

curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/ai/routines \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Weekly user signups",
  "modelId": "770e8400-e29b-41d4-a716-446655440002",
  "prompt": "How many users signed up last week?",
  "schedule": "0 9 ? * MON *",
  "timezone": "America/New_York",
  "destination": {
    "type": "email",
    "recipientEmails": [
      "blob.ross@blobsrus.com",
      "blob.the.builder@blobsrus.com"
    ]
  }
}
'

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "condition": {
    "conditionPrompt": "there are failed orders",
    "conditionType": "RESULTS_PRESENT",
    "interpretation": "<string>",
    "query": {
      "aiGenerated": true,
      "calculations": [],
      "column_totals": {},
      "fields": [
        "orders.id"
      ],
      "fill_fields": [],
      "filters": {
        "orders.status": {
          "case_insensitive": true,
          "kind": "EQUALS",
          "type": "string",
          "values": [
            "failed"
          ]
        }
      },
      "limit": 1,
      "modelId": "770e8400-e29b-41d4-a716-446655440002",
      "pivots": [],
      "row_totals": {},
      "sorts": [],
      "table": "orders",
      "userEditedSQL": "SELECT ${orders.id}\nFROM ${orders}\nWHERE UPPER(${orders.status}) = UPPER('failed')\nLIMIT 1",
      "version": 9
    },
    "verification": {
      "rowCount": 0,
      "conditionMetNow": false
    }
  }
}

{
  "detail": "The delivery condition is too vague or subjective to evaluate. State a specific, measurable condition, then try again.",
  "status": 400,
  "code": "not_expressible"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "code": "shutoff",
  "detail": "The AI credit limit has been reached. Contact your administrator for assistance.",
  "status": 402
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "detail": "<string>",
  "status": 404
}

{
  "detail": "<string>",
  "status": 429
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "detail": "Omni was temporarily unable to compose or verify the delivery condition. Try again shortly.",
  "status": 503
}

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>

Organization API key required. The membership ID of the user to act as.

Body

application/json

modelId

string<uuid>

required

The UUID of the model the prompt runs against. Must be a shared model, or a shared-extension model usable as a workbook base.

Example:

"770e8400-e29b-41d4-a716-446655440002"

name

string

required

Customer-visible name of the routine. Used as the email subject for email destinations, shown on Slack deliveries, and sent as name in webhook payloads.

Required string length: 1 - 512

Example:

"Weekly user signups"

prompt

string

required

Natural language prompt Omni runs on each scheduled run. Run a skill as part of the routine by including a skill's /identifier, which will resolve as the routine owner when the routine fires.

Minimum string length: 1

Example:

"How many users signed up last week?"

schedule

string

required

Six-field cron expression (minute, hour, day-of-month, month, day-of-week, year; use ? for an unspecified day field).

Minimum frequency is once per hour; contact Omni support if you need more frequent scheduling.

Minimum string length: 1

Example:

"0 9 ? * MON *"

timezone

string

required

IANA timezone identifier used to evaluate the schedule.

Example:

"America/New_York"

destination

object

required

Single delivery destination for the routine. To send results to multiple destinations, create one routine per destination.

Option 1
Option 2
Option 3

Show child attributes

branchId

string<uuid> | null

Branch of the shared model the prompt runs against, or null.

description

string

Optional human-readable notes about the routine. Display-only — never used as model input.

Maximum string length: 2000

Example:

"Weekly signups summary for the growth team."

topicName

string

Topic name to scope query generation. If omitted, the AI picks the best topic.

Maximum string length: 256

Example:

"users"

condition

object

Delivers only when this condition is met. Omni authors and verifies a semantic query from the condition text before creating the routine.

Omit for a routine that delivers on every scheduled run.

Show child attributes

Response

Routine created successfully

string<uuid>

required

The unique identifier for the newly created routine.

Example:

"880e8400-e29b-41d4-a716-446655440003"

condition

object

The generated condition, present only when the request supplied one.

Show child attributes

Getting started

Who am I?

Administration APIs

AI APIs

App APIs

Branch APIs

Connection APIs

Content APIs

Dashboard APIs

Document APIs

Embed APIs

Folder APIs

Label APIs

Model APIs

Query APIs

Schedule APIs

Upload APIs

User APIs

User group APIs

Create an AI Routine

Authorizations

Query Parameters

Body

Response