--- title: "Update a routine" method: PATCH path: "/api/v1/ai/routines/{id}" tags: ["AI Routines"] --- # Update a routine `PATCH /api/v1/ai/routines/{id}` Update a routine. All request fields are optional, and only supplied fields are changed. Supplying `destination` replaces the full recipient configuration. If you change the prompt for a routine that has a delivery condition, Omni updates both the condition and the content to deliver. If the new prompt describes a recurring summary instead of an alert, Omni removes the delivery condition so the routine delivers after every scheduled run. If Omni cannot create or validate a delivery condition from the new prompt, no changes are saved. ## Path parameters - `id` string, uuid, required — The UUID of the routine. ## Query parameters - `userId` string, uuid — Target user membership ID (for org-scoped API keys) ## Request body - RoutineUpdateBody - `description` string, nullable — Display-only notes about the routine. Pass null to clear it. - `destination` union - object — Replaces the routine's full recipient configuration with the supplied destination. - `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. - object — Replaces the routine's full recipient configuration with the supplied destination. - `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. - `name` string — New customer-visible name of the routine. Used as the email subject for email destinations, and shown on Slack deliveries. - `prompt` string — New natural language prompt for the routine. If the routine has a delivery condition, Omni updates both the condition and the content to deliver from this text. - `schedule` string — New 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. - `timezone` string — New IANA timezone identifier used to evaluate the schedule. ## Response `200` Updated routine details. - RoutineResponse - `branchId` string, uuid, nullable, required — Branch of the shared model the prompt runs against, or null. - `condition` RoutineCondition, nullable, required — The condition gating delivery, or null for a routine that delivers on every scheduled run. - `conditionPrompt` string, nullable, required — The delivery condition identified in the routine's current prompt, in plain language. Null on routines created before Omni stored delivery conditions. - `conditionType` 'RESULTS_CHANGED' | 'RESULTS_UNCHANGED' | 'RESULTS_PRESENT' | 'RESULTS_MISSING', required — How the condition query gates delivery. RESULTS_PRESENT fires when the condition query returns rows, RESULTS_MISSING when it returns none, RESULTS_CHANGED when its results differ from the previous scheduled run, RESULTS_UNCHANGED when they are identical. - `createdAt` string, required — ISO 8601 timestamp when the routine was created. - `description` string, nullable, required — Display-only notes about the routine, or null. - `destination` union, required — Delivery configuration for the routine. - RoutineEmailDestinationResponse - `recipientEmails` string[], required — Email addresses configured as direct recipients of each scheduled run, resolved from their current membership. - `type` 'email', required — Selects email delivery — each scheduled run is sent to the listed email recipients and user groups. - `userGroupIds` string[], required — 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 - `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. - `disabled` boolean, required — Whether the owner has paused the routine. - `id` string, uuid, required — The unique identifier of the routine. - `lastRun` RoutineLastRun, nullable, required — Most recent completed run, or null if the routine has never completed a run. - `completedAt` string, nullable, required — ISO 8601 timestamp the last completed run finished. - `label` string, required — Customer-visible status of the last completed run. - `state` string, required — Machine-readable status of the last completed run. - `modelId` string, uuid, required — The model the prompt runs against. - `name` string, required — Customer-visible name of the routine. Used as the email subject for email destinations, and shown on Slack deliveries. - `prompt` string, required — Natural language prompt Omni runs on each scheduled run. - `recipientCount` integer, required — Number of distinct deliverable recipients. For email, user groups are expanded to members and duplicates removed; a Slack routine is always 1 (its single channel or DM). - `schedule` string, required — Six-field cron expression (minute, hour, day-of-month, month, day-of-week, year; use `?` for an unspecified day field). - `systemDisabled` boolean, required — Whether Omni disabled the routine because it could no longer run successfully or safely. - `systemDisabledReason` string, nullable, required — Reason Omni disabled the routine, or null. - `timezone` string, required — IANA timezone identifier used to evaluate the schedule. - `topicName` string, nullable, required — Topic scoping query generation, or null. - `updatedAt` string, required — ISO 8601 timestamp when the routine was last updated. ## Other responses - `400` — Invalid routine ID, request body, recipient configuration, schedule, or timezone. Also returned when Omni cannot create or validate a delivery condition from the new prompt. In that case, the response includes a machine-readable `code`; no changes are saved. Make the condition specific and measurable, then retry the request. - `401` — Missing or invalid API key. - `402` — The organization's AI credit limit has been reached, so Omni cannot evaluate the new prompt. No changes are saved. - `403` — AI routines or AI query generation are not enabled for the organization, or a user-scoped API key tried to update another user's routine. - `404` — Routine not found or has been deleted. - `503` — The AI service is temporarily unavailable, so Omni cannot evaluate the new prompt. No changes are saved. Retry the request. --- [API](https://skmtc.net/omniapp/apis/omni-api.md) · [All operations](https://skmtc.net/omniapp/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omniapp/omni-api/revisions/499d4ddc73b6/schema)