---
title: "Create a routine — scheduled agent execution [write]"
method: POST
path: "/routines"
---

# Create a routine — scheduled agent execution \[write\]

`POST /routines`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/routines`
- Auth: HTTP bearer

initial_events (1–50 user.message events) are delivered on every fire. target picks the mode: new_session creates a fresh session per run, or with reuse_session: true one session that every run continues; session sends the turn into an existing session (busy target → failed run session_busy_error). schedule is a 5-field POSIX cron with an IANA timezone; omit it for a manual-run-only routine. budget bounds each run separately. The answer carries effective_deliver_to: where each run's result goes (metadata created_in_session names the conversation the routine was made in, which receives results by default).

## Headers

- `Idempotency-Key` string

## Request body

- CreateRoutine
  - `name` string, required
  - `description` string
  - `metadata` object
  - `target` union, required
    - object
      - `type` 'new_session', required
      - `agent` string, required
      - `environment_id` string
      - `vault_ids` string[]
      - `reuse_session` boolean
    - object
      - `type` 'session', required
      - `session_id` string, required
  - `initial_events` object[], required
    - `type` 'user.message', required
    - `content` union[], required
      - union
        - object
          - `type` 'text', required
          - `text` string, required
        - object
          - `type` 'image', required
          - `source` union, required
            - object
              - …
            - object
              - …
            - object
              - …
        - object
          - `type` 'document', required
          - `source` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `title` string, nullable
          - `context` string, nullable
    - `interaction_mode` 'plan' | 'build', nullable
  - `schedule` object, nullable
    - `type` 'cron', required
    - `expression` string, required
    - `timezone` string, required
  - `budget` object, nullable
    - `type` 'limit', required
    - `max_list_cost` object, required
      - `amount` string, required: Whole US cents as an integer decimal string, e.g. "125" for $1.25
      - `currency` 'USD', required

## Response `201`

Created

- object
  - `routine` Routine, required: Scheduled agent execution: initial_events + a target (new_session per fire, or an existing session) bound to a cron schedule. Fires record routine runs.
    - `id` string: rtn_… identifier
    - `name` string
    - `description` string, nullable
    - `metadata` object
    - `target` object: {type:"new_session", agent, environment_id?, vault_ids?, reuse_session?} — a fresh session per fire (CMA parity); with reuse_session: true the first fire starts the session and every later fire posts into it (a new one only once it is archived or deleted; a fire while it is working or waiting on a person is skipped) · {type:"session", session_id} — a turn into the existing session every fire (busy target skips with session_busy_error)
    - `initial_events` object[]
    - `schedule` object, nullable: 5-field POSIX cron + IANA timezone, wall-clock matching, minute granularity; null = manual-run only
      - `type` 'cron'
      - `expression` string
      - `timezone` string
      - `last_run_at` string, nullable
      - `upcoming_runs_at` string[]: ≤5 upcoming fire times; empty once archived
    - `budget` object, nullable: Per-run cap (RFC-0080 shape): copied onto each new session (mode new_session) or granted as a per-fire delta allowance consumed+budget (mode session). Clearable.
    - `status` 'active' | 'paused'
    - `paused_reason` object, nullable: {type:"manual"} | {type:"error", error:{type}, consecutive_failures, message?} — non-null exactly when paused. A routine pauses itself after 3 runs in a row fail with an error that the next run would repeat, insufficient_credits_error included (the wallet that pays for it is empty); add credit, then unpause.
    - `archived_at` string, nullable
    - `created_at` string
    - `updated_at` string
  - `effective_deliver_to` object: Where each run's result goes in effect. channel_thread: the chosen chat. session: a conversation — the one the routine runs in (source target) or the one it was made in (source origin, from metadata created_in_session or proposed_by_session). notification: no conversation. The owner is notified in every case.
    - `type` 'channel_thread' | 'session' | 'notification', required
    - `connection_id` string
    - `thread_id` string
    - `session_id` string
    - `source` 'target' | 'origin'
    - `notify_owner` true, required

## Other responses

- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 8 info
  - added the new optional `header` request parameter `Idempotency-Key`
  - added the new optional request property `initial_events/items/interaction_mode`
  - added the new optional request property `target/oneOf[subschema #1]/reuse_session`
  - added the optional property `effective_deliver_to` to the response with the `201` status
  - …4 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/routines/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)