--- title: "Create a routine" method: POST path: "/api/v1/agents/{agent}/agent_routines" --- # Create a routine `POST /api/v1/agents/{agent}/agent_routines` Creates a new routine and attaches it to the specified agent. Routines define how an agent responds to events or a cron schedule; the `handler_type` controls which execution model is used. The routine is created in `"draft"` status by default. To start processing events immediately, either pass `status: "active"` or call the activate endpoint after creation. Scheduled routines must run no more frequently than once per hour. Requires app scope. ## Path parameters - `agent` string, required ## Request body - object - `acl` object — Access control list governing who can read or manage this routine. - `add` object[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`. - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry. - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `grants` object[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`. - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry. - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `remove` object[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`. - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `config` string — Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. - `description` string — Optional human-readable description of what this routine does. - `event_config` object — Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`). - `event_type` string — Event type that triggers this routine. Deprecated — use `event_config` instead. - `handler_type` string, required — Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. - `lookup_key` string — Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. - `metadata` object — Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. - `name` string, required — Human-readable display name for the routine. - `preset_config` object — Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. - `instructions` string — Custom task or behavior instructions for the preset (max 10,000 chars). - `llm` object — LLM invocation settings (e.g. a `model` override for this routine/step). - `model` string — Model identifier to use for this routine or step, e.g. `"claude-sonnet-4-5"`. When omitted, the agent's default model is used. - `session_mode` string — Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`). - `session_scope` string — When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`. - `structured_message_template_ids` string[] — IDs of structured message templates that constrain the agent's responses to predefined structured formats. - `preset_name` string — Name of the registered preset to use. Required when `handler_type` is `"preset"`. - `schedule` string — Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. - `script` string — Inline script source. Required when `handler_type` is `"script"`. - `status` string — Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. - `steps` object[] — Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step's `handler_type`. - `config` string — ID of a saved config to use as the handler body. Required when `handler_type` is `"workflow_graph"`; also accepted for `"script"` as an alternative to an inline `script` value. - `handler_type` string, required — Execution handler for this step. One of `"preset"`, `"script"`, or `"workflow_graph"`. - `inputs` object — Optional key-value map binding outputs from prior steps to this step's input variables. - `name` string — Optional label for this step. Must be unique within the chain when provided. - `on_error` string — Error handling policy for this step. One of `"halt"` (default), `"continue"`, or `"retry"`. - `output_key` string — Key under which this step's result is stored and addressable by downstream steps. Defaults to `name` when omitted. - `preset_config` object — Configuration overrides for the preset, using the same shape as the routine-level `preset_config`. You may include an `llm` key to override the agent's default model for this step. `null` if not provided. - `instructions` string — Custom task or behavior instructions for the preset (max 10,000 chars). - `llm` object — LLM invocation settings (e.g. a `model` override for this routine/step). - `model` string — Model identifier to use for this routine or step, e.g. `"claude-sonnet-4-5"`. When omitted, the agent's default model is used. - `session_mode` string — Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`). - `session_scope` string — When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`. - `structured_message_template_ids` string[] — IDs of structured message templates that constrain the agent's responses to predefined structured formats. - `preset_name` string — Name of the preset to invoke. Required when `handler_type` is `"preset"`. - `script` string — Inline script source code to execute. Used when `handler_type` is `"script"` and no `config` is provided. - `trigger_context` string — Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. ## Response `200` Successful response - AgentRoutine — An agent routine defines a reusable handler — script, preset, or chain — that runs in response to events or on a schedule. - `acl` Acl — An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants. - `add` AclGrant[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`. - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry. - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `grants` AclGrant[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`. - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry. - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `remove` AclRemoveTarget[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`. - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `agent` string — ID of the agent that owns this routine (`agi_...`). - `app` string — Application that scopes this routine (`dap_...`). - `config` string — ID of the Config record that backs this routine's configuration (`cfg_...`). `null` when the routine is not config-backed. - `created_at` string, date-time — When this routine was created (ISO 8601). - `description` string — Optional description of what this routine does. `null` when not set. - `event_config` object — Additional configuration controlling how the event trigger is matched or filtered. Shape depends on `event_type`. `null` when not configured. - `event_type` string — Platform event type that triggers this routine, e.g. `"agentroutine.invoked"`. `null` for schedule-only routines. - `handler_type` string — Execution strategy for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. - `id` string, required — Routine ID (`arn_...`). - `last_applied_template_config` string — ID of the AgentRoutineTemplate Config this routine was last provisioned or updated from (`cfg_...`). `null` for hand-built routines. - `lookup_key` string — Unique human-readable key used to look up this routine without knowing its ID. `null` when not set. - `metadata` object — Arbitrary key-value metadata attached to this routine. `null` when not set. - `name` string — Human-readable name for the routine. - `preset_config` PresetConfig — Configuration for a preset routine handler. Controls the agent's behavior, session persistence, and model selection for a given routine or chain step. - `instructions` string — Custom task or behavior instructions for the preset (max 10,000 chars). - `llm` LLMConfig — LLM invocation settings for a routine or chain step. When present, overrides the agent-level model selection. - `model` string — Model identifier to use for this routine or step, e.g. `"claude-sonnet-4-5"`. When omitted, the agent's default model is used. - `session_mode` string — Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`). - `session_scope` string — When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`. - `structured_message_template_ids` string[] — IDs of structured message templates that constrain the agent's responses to predefined structured formats. - `preset_name` string — Name of the preset invoked when `handler_type` is `"preset"`. `null` for other handler types. - `schedule` string — Cron expression controlling when the routine fires on a schedule. `null` for event-only routines. - `script` string — Inline script body executed when `handler_type` is `"script"`. `null` for other handler types. - `status` string — Lifecycle status of the routine. One of `"draft"`, `"active"`, or `"paused"`. Only `"active"` routines respond to triggers. - `steps` object[] — Ordered list of chain steps (present when handler_type is "chain"). Each step is a plain map with handler_type, optional body fields (preset_name / preset_config / script / config), and step-local plumbing (name, inputs, output_key, on_error). - `trigger_context` string — Execution context in which runs are created. One of `"event"` (background job) or `"chat_session"` (interactive session). Defaults to `"event"`. - `updated_at` string, date-time — When this routine was last updated (ISO 8601). ## Other responses - `401` — Unauthorized - `403` — Forbidden - app scope required - `404` — Agent not found - `422` — Validation failed --- [API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)