Routines

Tags: automation, routines

Routines — the unified automation primitive (schedule, webhook, and system-event triggers)

Resources

Request and response models used by the endpoints on this page.

EventRuleResponse

Field	Type	Required	Description
actionParams	Dict[str, Any]	✓
actionType	<enum EventRuleActionType	✓
active	Boolean	✓
appConnectionId	Integer
calendarEventTypeId	Integer	✓
calendarId	Integer	✓
celBlockedAt	DateTime
conditions	String	✓
createdAt	DateTime	✓
dataTypeId	Integer	✓
dataTypeName	String
delay	Integer	✓
error	String	✓
errorMessage	String	✓
eventType	<enum EventRuleEventType	✓
failedAt	DateTime	✓
id	Integer	✓
journeyId	Integer
journeyStepId	Integer	✓
name	String	✓
objectType	<enum EventRuleObjectType	✓
order	Integer	✓
routineId	Integer	✓
taskId	Integer	✓
taskName	String
taskWorkflowId	Integer
triggerParams	Dict[str, Any]	✓
updatedAt	DateTime	✓
uuid	String	✓
workflowRevisionId	Integer	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "objectType": null  // <enum EventRuleObjectType,
  "name": "string"  // String,
  "eventType": null  // <enum EventRuleEventType,
  "conditions": "string"  // String,
  "actionType": null  // <enum EventRuleActionType,
  "actionParams": {}  // Dict[str, Any],
  "triggerParams": {}  // Dict[str, Any],
  "active": false  // Boolean,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "taskId": 0  // Integer,
  "taskName": "string"  // String, optional,
  "taskWorkflowId": 0  // Integer, optional,
  "dataTypeId": 0  // Integer,
  "dataTypeName": "string"  // String, optional,
  "routineId": 0  // Integer,
  "workflowRevisionId": 0  // Integer,
  "calendarId": 0  // Integer,
  "calendarEventTypeId": 0  // Integer,
  "journeyStepId": 0  // Integer,
  "journeyId": 0  // Integer, optional,
  "appConnectionId": 0  // Integer, optional,
  "error": "string"  // String,
  "errorMessage": "string"  // String,
  "failedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "celBlockedAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "delay": 0  // Integer,
  "order": 0  // Integer
}

MemberSummary

Field	Type	Required	Description
id	Integer	✓
name	String

Example:

{
  "id": 0  // Integer,
  "name": "string"  // String, optional
}

RoutineConfigEventResponse

Field	Type	Required	Description
actor	MemberSummary
actorMemberId	Integer
actorType	<enum RoutineConfigEventActorType	✓
fieldsChanged	Array
id	Integer	✓
occurredAt	DateTime	✓
reason	<enum RoutineConfigEventReason	✓
routineId	Integer	✓
scheduleEnabledAfter	Boolean
scheduleEnabledBefore	Boolean
scheduleTransitioned	Boolean	✓
uuid	String	✓
webhookEnabledAfter	Boolean
webhookEnabledBefore	Boolean
webhookTransitioned	Boolean	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "routineId": 0  // Integer,
  "occurredAt": "2024-01-01T00:00:00Z"  // DateTime,
  "actorType": null  // <enum RoutineConfigEventActorType,
  "actorMemberId": 0  // Integer, optional,
  "reason": null  // <enum RoutineConfigEventReason,
  "scheduleEnabledBefore": false  // Boolean, optional,
  "scheduleEnabledAfter": false  // Boolean, optional,
  "webhookEnabledBefore": false  // Boolean, optional,
  "webhookEnabledAfter": false  // Boolean, optional,
  "scheduleTransitioned": false  // Boolean,
  "webhookTransitioned": false  // Boolean,
  "fieldsChanged": "string"  // Array<String>, optional,
  "actor": null  // MemberSummary, optional
}

RoutineResponse

Field	Type	Required	Description
createdAt	DateTime	✓
cronString	String
description	String
eventRules	Array		Default: []
id	Integer	✓
intervalSeconds	Integer
limit	Integer	✓
managerModel	String
managerPrompt	String
managerSkills	Array
memberFilterId	Integer
memberFilterName	String
name	String	✓
nextRun	DateTime
ownerId	Integer	✓
repeatCount	Integer
scheduleEnabled	Boolean	✓
scheduleMode	String	✓
scheduledTime	DateTime
startDate	DateTime
targetMemberId	Integer
timezone	String
updatedAt	DateTime	✓
uuid	String	✓
visibility	String	✓
webhookEnabled	Boolean		Default: False
webhookSecretPlaintext	String
workflowId	Integer

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "name": "string"  // String,
  "description": "string"  // String, optional,
  "scheduleEnabled": false  // Boolean,
  "scheduleMode": "string"  // String,
  "scheduledTime": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "intervalSeconds": 0  // Integer, optional,
  "repeatCount": 0  // Integer, optional,
  "cronString": "string"  // String, optional,
  "timezone": "string"  // String, optional,
  "startDate": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "memberFilterId": 0  // Integer, optional,
  "memberFilterName": "string"  // String, optional,
  "targetMemberId": 0  // Integer, optional,
  "workflowId": 0  // Integer, optional,
  "managerPrompt": "string"  // String, optional,
  "managerSkills": "string"  // Array<String>, optional,
  "managerModel": "string"  // String, optional,
  "limit": 0  // Integer,
  "visibility": "string"  // String,
  "ownerId": 0  // Integer,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "eventRules": []  // Array<EventRuleResponse>, optional, default: [],
  "nextRun": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "webhookEnabled": false  // Boolean, optional, default: False,
  "webhookSecretPlaintext": "string"  // String, optional
}

RoutineWorkflowAccessMissingRoleResponse

Field	Type	Required	Description
id	Integer	✓
name	String	✓

Example:

{
  "id": 0  // Integer,
  "name": "string"  // String
}

RoutineWorkflowAccessPreviewResponse

Field	Type	Required	Description
totalWarnings	Integer	✓
warnings	Array	✓

Example:

{
  "warnings": []  // Array<RoutineWorkflowAccessWarningResponse>,
  "totalWarnings": 0  // Integer
}

RoutineWorkflowAccessWarningResponse

Field	Type	Required	Description
actionType	String	✓
audienceRoleCount	Integer	✓
eventRuleId	Integer
missingRoles	Array	✓
routineId	Integer
routineName	String
targetKind	String	✓
workflowId	Integer	✓
workflowName	String	✓
workflowUuid	String	✓

Example:

{
  "routineId": 0  // Integer, optional,
  "routineName": "string"  // String, optional,
  "eventRuleId": 0  // Integer, optional,
  "actionType": "string"  // String,
  "workflowId": 0  // Integer,
  "workflowUuid": "string"  // String,
  "workflowName": "string"  // String,
  "targetKind": "string"  // String,
  "missingRoles": []  // Array<RoutineWorkflowAccessMissingRoleResponse>,
  "audienceRoleCount": 0  // Integer
}

SchedulePreviewRequest

Field	Type	Required	Description
count	Integer		Default: 5
cronString	String	✓
timezone	String

Example:

{
  "cronString": "string"  // String,
  "count": 0  // Integer, optional, default: 5,
  "timezone": "string"  // String, optional
}

SchedulePreviewResponse

Field	Type	Required	Description
nextRuns	Array	✓

Example:

{
  "nextRuns": "string"  // Array<String>
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/routines - List
• POST /api/v2/w/{workspace_uuid}/routines - Create
• POST /api/v2/w/{workspace_uuid}/routines/preview-schedule - Preview Schedule
• POST /api/v2/w/{workspace_uuid}/routines/preview-workflow-access - Preview Workflow Access
• GET /api/v2/w/{workspace_uuid}/routines/runs - Runs
• DELETE /api/v2/w/{workspace_uuid}/routines/{event_id} - Delete Event Id
• GET /api/v2/w/{workspace_uuid}/routines/{event_id} - Get Event Id
• PUT /api/v2/w/{workspace_uuid}/routines/{event_id} - Update Event Id
• GET /api/v2/w/{workspace_uuid}/routines/{event_id}/history - History
• POST /api/v2/w/{workspace_uuid}/routines/{event_id}/run - Run
• DELETE /api/v2/w/{workspace_uuid}/routines/{event_id}/runs - Delete Runs

List

GET /api/v2/w/{workspace_uuid}/routines

Description:

List all Routines for the workspace with pagination.

Visibility rules: a member sees Routines they own (any visibility) plus workspace-visible Routines owned by others. Private Routines owned by other members are hidden by default. Callers with AUTOMATIONS_ADMIN can request owner=all_including_private to see every routine in the workspace for administrative operations.

The owner query param narrows within what the caller is allowed to see — it cannot widen access beyond the caller's scopes.

Authorization: Requires automations:read scope

Parameters:

• page (Integer) — min: 1
• pageSize (Integer) — min: 1, max: 100
• sortBy (RoutineSortField)
• sortOrder (SortOrder)
• owner (String)

Response: See PaginatedResponse[RoutineResponse]

---

Create

POST /api/v2/w/{workspace_uuid}/routines

Description:

Create a new Routine.

Authorization: Requires automations:write scope

Parameters:

• request - See CreateRoutineRequest

Response: See RoutineResponse

---

Preview Schedule

POST /api/v2/w/{workspace_uuid}/routines/preview-schedule

Description:

Preview the next N run times for a cron expression.

An omitted/blank timezone falls back to the workspace's, then UTC — the same precedence the schedulers apply, so the preview cannot promise a wall-clock the dispatcher will not honour. This is what the editor already does client-side; sending the fallback through the server too keeps a direct API/CLI caller from getting a different answer.

Authorization: Requires automations:read scope

Parameters:

• request - See SchedulePreviewRequest

Response: See SchedulePreviewResponse

---

Preview Workflow Access

POST /api/v2/w/{workspace_uuid}/routines/preview-workflow-access

Description:

Non-blocking preview of which audience roles lack Workflow USE.

Warn-not-block authoring assist. Read-only and non-persisting: it evaluates the draft Routine's target audience (target Member / MemberFilter / owner fallback) against every workflow-starting reference — workflowId plus the active routine:triggered EventRule workflowUUID params — and returns role-level warnings. It does NOT change authorization, auto-grant USE, or emit an audit event (no PHI is read; role/Routine/Workflow names only).

Distinct from the two hard create/update checks, both of which block. _validate_routine_workflow validates the CURRENT ACTOR's USE of Routine.workflow_id and returns 403 on denial. _validate_routine_audience_workflow_access validates the TARGET AUDIENCE's USE across the same wider reference set this preview covers and returns 422 on a gap, but only when the save leaves the Routine schedule-enabled.

This preview always warns rather than blocks, so it also covers schedule-disabled drafts that the audience guard deliberately skips.

Authorization: Requires automations:write scope

Parameters:

• request - See RoutineWorkflowAccessPreviewRequest

Response: See RoutineWorkflowAccessPreviewResponse

---

Runs

GET /api/v2/w/{workspace_uuid}/routines/runs

Description:

List all Routine runs for the workspace with pagination.

Only runs for Routines the caller can see are returned — i.e. runs of their own Routines plus runs of workspace-visible Routines owned by others. Without the visibility join a caller with AUTOMATIONS_READ could enumerate history of any private Routine by guessing routineId.

Authorization: Requires automations:read scope

Parameters:

• page (Integer) — min: 1
• pageSize (Integer) — min: 1, max: 100
• sortBy (EventRunSortField)
• sortOrder (SortOrder)
• routineId (Integer)
• status (String)

Response: See PaginatedResponse[RoutineRunResponse]

---

Delete Event Id

DELETE /api/v2/w/{workspace_uuid}/routines/{event_id}

Description:

Delete a Routine.

Authorization: Requires automations:admin scope

Parameters:

• event_id (Integer)

---

Get Event Id

GET /api/v2/w/{workspace_uuid}/routines/{event_id}

Description:

Get a specific Routine by ID.

Authorization: Requires automations:read scope

Parameters:

• event_id (Integer)

Response: See RoutineResponse

---

Update Event Id

PUT /api/v2/w/{workspace_uuid}/routines/{event_id}

Description:

Update an existing Routine.

Authorization: Requires automations:write scope

Parameters:

• event_id (Integer)
• request - See UpdateRoutineRequest

Response: See RoutineResponse

---

History

GET /api/v2/w/{workspace_uuid}/routines/{event_id}/history

Description:

Config-change history for one Routine, newest first (GH #22937).

Access rules and rationale: lib/services/routine_history_service.py.

Authorization: Requires automations:read scope

Parameters:

• event_id (Integer)
• limit (Integer)
• before_id (Integer)
• transitions_only (Boolean)

Response: List of RoutineConfigEventResponse

---

Run

POST /api/v2/w/{workspace_uuid}/routines/{event_id}/run

Description:

Run a Routine manually.

Authorization: Requires automations:write scope

Parameters:

• event_id (Integer)
• member_id (Integer)
• member_filter_id (Integer)

---

Delete Runs

DELETE /api/v2/w/{workspace_uuid}/routines/{event_id}/runs

Description:

Reset/clear all runs for a Routine.

Orchestration, ordering and rationale: lib/services/routine_reset_service.py.

Authorization: Requires automations:admin scope

Parameters:

• event_id (Integer)

---