---
title: "Create an AI Routine"
method: POST
path: "/v1/ai/routines"
tags: ["AI Routines"]
---

# Create an AI Routine

`POST /v1/ai/routines`

Create a new AI Routine that will run on the specified schedule.

Each scheduled run executes once using the routine owner's permissions, and every recipient receives the same result.

## Query parameters

- `userId` string, uuid

## Request body

- object
  - `branchId` string, uuid, nullable — Branch of the shared model the prompt runs against, or null.
  - `description` string, nullable — Display-only notes about the routine, or null.
  - `destination` union, required — Single delivery destination for the routine — email or Slack. To send results to multiple destinations, create one routine per destination.
    - RoutineEmailDestination — Email delivery configuration for the routine.
      - `recipientEmails` string[] — Email addresses that receive each scheduled run of the routine.
      - `type` 'email', required — Selects email delivery — each scheduled run is sent to the listed email recipients and user groups.
      - `userGroupIds` string[] — User group IDs whose active members receive each scheduled run. Omni expands each group to the members' current email addresses when the routine runs.
    - RoutineSlackDestination — Slack delivery configuration for the routine. Requires a Slack workspace connected to Omni; to deliver to a private channel, invite the Omni Slackbot to it first.
      - `recipientId` string, required — The Slack channel ID (e.g. `C01234567`) or user ID (e.g. `U01234567`) that receives each scheduled run. Exactly one recipient per Slack routine.
      - `slackRecipientType` 'channel' | 'users', required — Whether `recipientId` is a Slack channel or a user (delivered as a direct message).
      - `type` 'slack', required — Selects Slack delivery — each scheduled run is posted to one Slack channel or sent as a direct message to one user.
  - `modelId` string, uuid, required — The shared model the prompt runs against.
  - `name` string, required — Customer-visible name of the routine, used as the email subject.
  - `prompt` string, required — Natural language prompt Omni runs on each scheduled run.
  - `schedule` string, required — Six-field cron expression (minute, hour, day-of-month, month, day-of-week, year; use `?` for an unspecified day field).
  - `timezone` string, required — IANA timezone identifier used to evaluate the schedule.
  - `topicName` string, nullable — Topic scoping query generation, or null.

## Response `201`

Routine created successfully

- object
  - `id` string, uuid — The unique identifier for the newly created routine.

## Other responses

- `400` — Invalid request body, recipient configuration, timezone, or schedule. Also returned when the schedule is more frequent than the organization allows.
- `401` — Missing or invalid API key
- `403` — Forbidden AI routines or AI query generation are not enabled for the organization, or the API key cannot act on behalf of the requested user.
- `404` — Model, branch, or topic not found, or not accessible to the requested user.
- `429` — The resolved user already has the maximum number of active routines.
- `500` — Internal Server Error

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)