Routines

Endpoints for defining routines (templates that enqueue an issue on a schedule, webhook, or API call), managing their triggers and revisions, and firing runs.

Prerequisites

• API key: Authorization: Bearer <token>
• Squad-scoped access; creating routines and triggers requires task-assignment (Operator) rights

Endpoints

Method	Path	Description
GET	/api/squads/{squadId}/routines	List routines for a squad
POST	/api/squads/{squadId}/routines	Create a routine
GET	/api/routines/{id}	Read a routine (with triggers)
PATCH	/api/routines/{id}	Update a routine (creates a revision)
GET	/api/routines/{id}/revisions	List routine revisions
POST	/api/routines/{id}/revisions/{revisionId}/restore	Restore a prior revision
GET	/api/routines/{id}/runs	List runs produced by a routine
POST	/api/routines/{id}/triggers	Add a trigger
PATCH	/api/routine-triggers/{id}	Update a trigger
POST	/api/routine-triggers/{id}/rotate-secret	Rotate a webhook trigger's signing secret
DELETE	/api/routine-triggers/{id}	Delete a trigger
POST	/api/routines/{id}/run	Fire the routine manually
POST	/api/routine-triggers/public/{publicId}/fire	Fire a webhook/API trigger by its public ID

---

Create a routine

POST /api/squads/{squadId}/routines

Request body

Field	Type	Required	Description
title	string	yes	Title of the issue the routine enqueues (≤200 chars)
description	string	no	Issue body template
projectId	UUID	no	Project to file enqueued issues under
goalId	UUID	no	Associated goal
parentIssueId	UUID	no	Parent issue for enqueued issues
assigneeAgentId	UUID	no	Agent assigned to each run
priority	string	no	Issue priority (default medium)
status	string	no	active (default), paused, or archived
concurrencyPolicy	string	no	coalesce_if_active (default), always_enqueue, or skip_if_active
catchUpPolicy	string	no	skip_missed (default) or enqueue_missed_with_cap
variables	array	no	Variable definitions (see below)
env	object	no	Environment bindings (plain values or secret references)

Returns 201 Created with the routine and its initial revision.

Variable definitions

Each entry in variables declares an input collected when the routine runs:

Field	Type	Description
name	string	Identifier ([A-Za-z][A-Za-z0-9_]*)
label	string	Optional display label
type	string	text (default), textarea, number, boolean, or select
defaultValue	string | number | boolean	Optional default
required	boolean	Whether a value must be supplied (default true)
options	string[]	Allowed values; required for and exclusive to select

---

Read / update / revisions

• GET /api/routines/{id} returns the routine with its triggers.
• PATCH /api/routines/{id} accepts the same fields as create (all optional) plus an optional baseRevisionId for optimistic concurrency; each update records a new revision.
• GET /api/routines/{id}/revisions lists revisions; POST /api/routines/{id}/revisions/{revisionId}/restore rolls back to one.

---

Triggers

POST /api/routines/{id}/triggers

A trigger is one of three kinds, discriminated by kind:

Kind	Fields	Description
schedule	cronExpression (required), timezone (default UTC)	Fires on a cron expression
webhook	signingMode (default bearer), replayWindowSec (30–86400, default 300)	Fires on a signed inbound webhook
api	—	Fires on an authenticated API call

All kinds accept label and enabled (default true). Signing modes for webhooks: bearer, hmac_sha256, github_hmac, none.

Webhook and API triggers expose a publicId; fire them with POST /api/routine-triggers/public/{publicId}/fire.

Rotate a webhook signing secret

POST /api/routine-triggers/{id}/rotate-secret

Issues a new signing secret for a webhook trigger and records a routine revision. The request body is empty; the new secret is returned in the response. Existing callers must adopt the new secret to keep passing signature verification.

---

Run a routine

POST /api/routines/{id}/run

Manually enqueues a run.

Request body

Field	Type	Required	Description
triggerId	UUID	no	Attribute the run to a specific trigger
payload	object	no	Webhook/API payload made available to the run
variables	object	no	Values for the routine's declared variables
projectId	UUID	no	Override the target project
assigneeAgentId	UUID	no	Override the assignee
idempotencyKey	string	no	De-duplicate repeated submissions
source	string	no	manual (default) or api

---

Next steps

• Issues — the issues that routines enqueue
• Secrets — back routine env bindings with managed secrets
• Agents — assign routine runs to an agent