Sign in

v7

OpenAPI 3.1.02026-08-06211328764.1 KB
AI Routines

Create a routine

Create a routine that runs a saved prompt on a schedule and delivers the AI response through a single destination — email (one or more recipients / user groups) or Slack (a single channel or direct message). Each scheduled run executes once using the routine owner's permissions, and every recipient receives the same result. Organization API keys can pass ?userId=<membershipId> to create the routine for a specific organization member. For organizations with conditional routines enabled and gating 'auto' (the default), the prompt's alert intent is derived in this same request: an alert prompt persists a conditional routine (the response carries the decision and a dry-run of its trigger), while an alert whose trigger can't be composed or verified is a 400 with a stable code and no routine is created.

post/api/v1/ai/routines

Query parameters

userIdstring uuid

Target user membership ID (for org-scoped API keys)

Target user membership 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.

descriptionstring

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

gating'auto' | 'unconditional'

How the routine's delivery gating is decided. 'auto' (the default) derives it from the prompt when conditional routines are enabled for the organization: a prompt with an alert condition ("only if…", "alert me when…") becomes a conditional routine that delivers only when its trigger fires. 'unconditional' always creates a routine that delivers on every run, without evaluating the prompt for a condition.

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

namestring required

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

promptstring required

Natural language prompt Omni runs on each scheduled run.

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

timezonestring required

IANA timezone identifier used to evaluate the schedule.

topicNamestring

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

Example request

{
  "branchId": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Weekly signups summary for the growth team.",
  "gating": "auto",
  "modelId": "770e8400-e29b-41d4-a716-446655440002",
  "name": "Weekly user signups",
  "prompt": "How many users signed up last week?",
  "schedule": "0 9 ? * MON *",
  "timezone": "America/New_York",
  "topicName": "users",
  "destination": {
    "recipientEmails": [
      "alice@example.com",
      "bob@example.com"
    ],
    "type": "email",
    "userGroupIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }
}

Response

Routine created successfully. trigger is present only when the prompt was evaluated for a delivery condition (see gating).

idstring uuid required

The unique identifier for the newly created routine.

Example response

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "trigger": {
    "conditionPrompt": "total signups dropped more than 20% versus the prior week",
    "conditionType": "RESULTS_PRESENT",
    "decision": "alert",
    "deliverablePrompt": "Summarize weekly signups by region",
    "dryRun": {
      "conditionMetNow": true,
      "rowCount": 3
    }
  }
}