Automation Api Automation Api protocol schemas
Automation API Protocol
Defines REST CRUD endpoint schemas for managing automation flows,
triggering executions, and querying execution history.
Base path: /api/automation
@example Endpoints
GET /api/automation — List flows
GET /api/automation/:name — Get flow
POST /api/automation — Create flow
PUT /api/automation/:name — Update flow
DELETE /api/automation/:name — Delete flow
POST /api/automation/:name/trigger — Trigger flow execution
POST /api/automation/:name/toggle — Enable/disable flow
GET /api/automation/:name/runs — List execution runs
GET /api/automation/:name/runs/:runId — Get single execution run
Source: packages/spec/src/api/automation-api.zod.ts
import { AutomationApiErrorCode, AutomationFlowPathParamsSchema, AutomationRunPathParamsSchema, CreateFlowRequestSchema, CreateFlowResponseSchema, DeleteFlowRequestSchema, DeleteFlowResponseSchema, FlowSummarySchema, GetFlowRequestSchema, GetFlowResponseSchema, GetRunRequestSchema, GetRunResponseSchema, ListFlowsRequestSchema, ListFlowsResponseSchema, ListRunsRequestSchema, ListRunsResponseSchema, ToggleFlowRequestSchema, ToggleFlowResponseSchema, TriggerFlowRequestSchema, TriggerFlowResponseSchema, UpdateFlowRequestSchema, UpdateFlowResponseSchema } from '@objectstack/spec/api' ; import type { AutomationApiErrorCode, AutomationFlowPathParams, AutomationRunPathParams, CreateFlowRequest, CreateFlowResponse, DeleteFlowRequest, DeleteFlowResponse, FlowSummary, GetFlowRequest, GetFlowResponse, GetRunRequest, GetRunResponse, ListFlowsRequest, ListFlowsResponse, ListRunsRequest, ListRunsResponse, ToggleFlowRequest, ToggleFlowResponse, TriggerFlowRequest, TriggerFlowResponse, UpdateFlowRequest, UpdateFlowResponse } from '@objectstack/spec/api' ; // Validate data const result = AutomationApiErrorCode. parse (data);
flow_not_foundflow_already_existsflow_validation_failedflow_disabledexecution_not_foundexecution_failedexecution_timeoutnode_executor_not_foundconcurrent_execution_limit
Property Type Required Description name string✅ Flow machine name (snake_case)
Property Type Required Description name string✅ Flow machine name (snake_case) runId string✅ Execution run ID
Property Type Required Description name string✅ Machine name label string✅ Flow label description stringoptional successMessage stringoptional Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of a generic "Done". errorMessage stringoptional Message carried on AutomationResult for every terminal run (not only screen flows); the screen-flow UI shows it as a toast instead of the raw error. version integeroptional (default: 1) Version number status Enum<'draft' | 'active' | 'obsolete' | 'invalid'>optional (default: "draft") Deployment status template neveroptional [REMOVED] flow.template was removed in @objectstack/spec 17.0.0 (#3896 audit close-out) — no designer or engine path ever read it, so flagging a flow as a template/subflow did nothing. Delete the key. Shared logic is invoked via a subflow NODE referencing the flow by name. Run os migrate meta --from 16 to list the mechanical edits for existing sources; apply them by hand. type Enum<'autolaunched' | 'record_change' | 'schedule' | 'screen' | 'api'>✅ Flow type variables { name: string; type: string; isInput?: boolean; isOutput?: boolean; … }[]optional Flow variables nodes { id: string; type: string; label: string; config?: Record<string, any>; … }[]✅ Flow nodes edges { id: string; source: string; target: string; condition?: string | object; … }[]✅ Flow connections active neveroptional [REMOVED] flow.active was removed in @objectstack/spec 17.0.0 (#3896 audit close-out) — it never had an effect: the engine arms flows from status, and active: false did NOT stop a flow (worse, the default read as disabled while the engine treated unset as enabled). Delete the key. Use status: 'obsolete' (or 'invalid') to unbind and disable a flow, status: 'active' to arm it. Run os migrate meta --from 16 to list the mechanical edits for existing sources; apply them by hand. runAs Enum<'system' | 'user'>optional (default: "user") Execution identity for the run: system = elevated (bypasses RLS), user = the triggering user (RLS-respecting). A run with no trigger user has no identity to scope to, so under user its data operations are REFUSED — declare system to make the elevation explicit. This covers schedule/time-relative/api triggers AND any record-change flow fired by a write that carried no user. errorHandling { strategy?: Enum<'fail' | 'retry' | 'continue'>; maxRetries?: integer; backoffMs?: integer; backoffMultiplier?: number; … }optional Flow-level error handling configuration. A durable pause ends the retry-governed segment: strategy: 'retry' describes one synchronous dispatch, so a run that parks on an approval/screen/wait node and later resumes gets one attempt for anything that fails after the pause. Protect the post-pause half with its own failure handling in the flow — a try_catch node's retry around the post-resume work, or fault edges to a handler node. protection { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string }optional Package author protection block — lock policy for this flow. _lock Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>optional Item-level lock — controls overlay & delete (ADR-0010). _lockReason stringoptional Human-readable reason shown when a write is refused by _lock. _lockSource Enum<'artifact' | 'package' | 'env-forced'>optional Layer that set _lock (artifact | package | env-forced). _provenance Enum<'package' | 'org' | 'env-forced'>optional Origin of the item (package | org | env-forced). _packageId stringoptional Owning package machine id. _packageVersion stringoptional Owning package version. _lockDocsUrl stringoptional Optional documentation link surfaced next to _lockReason.
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { name: string; label: string; description?: string; successMessage?: string; … }✅ The created flow definition
Property Type Required Description name string✅ Flow machine name (snake_case)
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { name: string; deleted: boolean }✅
Property Type Required Description name string✅ Flow machine name label string✅ Flow display label type string✅ Flow type status string✅ Flow deployment status version integer✅ Flow version number enabled boolean✅ Whether the flow is enabled for execution nodeCount integeroptional Number of nodes in the flow lastRunAt stringoptional Last execution timestamp
Property Type Required Description name string✅ Flow machine name (snake_case)
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { name: string; label: string; description?: string; successMessage?: string; … }✅ Full flow definition
Property Type Required Description name string✅ Flow machine name (snake_case) runId string✅ Execution run ID
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { id: string; flowName: string; flowVersion?: integer; status: Enum<'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled' | …>; … }✅ Full execution log with step details
Property Type Required Description status Enum<'draft' | 'active' | 'obsolete' | 'invalid'>optional Filter by flow status type Enum<'autolaunched' | 'record_change' | 'schedule' | 'screen' | 'api'>optional Filter by flow type limit integeroptional (default: 50) Maximum number of flows to return cursor stringoptional Cursor for pagination
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { flows: object[]; total?: integer; nextCursor?: string; hasMore: boolean }✅
Property Type Required Description name string✅ Flow machine name (snake_case) status Enum<'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'retrying'>optional Filter by execution status limit integeroptional (default: 20) Maximum number of runs to return cursor stringoptional Cursor for pagination
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { runs: object[]; total?: integer; nextCursor?: string; hasMore: boolean }✅
Property Type Required Description name string✅ Flow machine name (snake_case) enabled boolean✅ Whether to enable (true) or disable (false) the flow
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { name: string; enabled: boolean }✅
Property Type Required Description name string✅ Flow machine name (snake_case) record Record<string, any>optional Record that triggered the automation object stringoptional Object name the record belongs to event stringoptional Trigger event type userId stringoptional User who triggered the automation params Record<string, any>optional Additional contextual data
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { success: boolean; output?: any; error?: string; durationMs?: number }✅
Property Type Required Description name string✅ Flow machine name (snake_case) definition { name?: string; label?: string; description?: string; successMessage?: string; … }✅ Partial flow definition to update
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { name: string; label: string; description?: string; successMessage?: string; … }✅ The updated flow definition
ObjectStack