Skip to content

automation-api.mdx

Latest commit

 

History

History
370 lines (239 loc) · 14 KB

automation-api.mdx

File metadata and controls

370 lines (239 loc) · 14 KB
Raw
title Automation Api
description Automation Api protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

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`

TypeScript Usage

import { 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';
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);

AutomationApiErrorCode

Allowed Values

  • flow_not_found
  • flow_already_exists
  • flow_validation_failed
  • flow_disabled
  • execution_not_found
  • execution_failed
  • execution_timeout
  • node_executor_not_found
  • concurrent_execution_limit

AutomationFlowPathParams

Properties

Property Type Required Description
name string ✅ Flow machine name (snake_case)

AutomationRunPathParams

Properties

Property Type Required Description
name string ✅ Flow machine name (snake_case)
runId string ✅ Execution run ID

CreateFlowRequest

Properties

Property Type Required Description
name string ✅ Machine name
label string ✅ Flow label
description string optional
successMessage string optional Toast shown when a screen flow completes (defaults to a generic "Done").
errorMessage string optional Toast shown when a screen flow fails (defaults to the raw error).
version integer optional Version number
status Enum<'draft' | 'active' | 'obsolete' | 'invalid'> optional Deployment status
template boolean optional Is logic template (Subflow)
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 | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }; … }[] ✅ Flow connections
active boolean optional Is active (Deprecated: use status)
runAs Enum<'system' | 'user'> optional Execution identity for the run: system = elevated (bypasses RLS), user = the triggering user (RLS-respecting). A schedule-triggered run has no trigger user, so under user it runs UNSCOPED (elevated) — declare system to make that explicit.
errorHandling { strategy?: Enum<'fail' | 'retry' | 'continue'>; maxRetries?: integer; retryDelayMs?: integer; backoffMultiplier?: number; … } optional Flow-level error handling configuration
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 string optional 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 string optional Owning package machine id.
_packageVersion string optional Owning package version.
_lockDocsUrl string optional Optional documentation link surfaced next to _lockReason.

CreateFlowResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } 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

DeleteFlowRequest

Properties

Property Type Required Description
name string ✅ Flow machine name (snake_case)

DeleteFlowResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } optional Response metadata
data { name: string; deleted: boolean } ✅

FlowSummary

Properties

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 integer optional Number of nodes in the flow
lastRunAt string optional Last execution timestamp

GetFlowRequest

Properties

Property Type Required Description
name string ✅ Flow machine name (snake_case)

GetFlowResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } 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

GetRunRequest

Properties

Property Type Required Description
name string ✅ Flow machine name (snake_case)
runId string ✅ Execution run ID

GetRunResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } 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' | 'timed_out' | 'retrying'>; … } ✅ Full execution log with step details

ListFlowsRequest

Properties

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 integer ✅ Maximum number of flows to return
cursor string optional Cursor for pagination

ListFlowsResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } optional Response metadata
data { flows: { name: string; label: string; type: string; status: string; … }[]; total?: integer; nextCursor?: string; hasMore: boolean } ✅

ListRunsRequest

Properties

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 integer ✅ Maximum number of runs to return
cursor string optional Cursor for pagination

ListRunsResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } optional Response metadata
data { runs: { id: string; flowName: string; flowVersion?: integer; status: Enum<'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'retrying'>; … }[]; total?: integer; nextCursor?: string; hasMore: boolean } ✅

ToggleFlowRequest

Properties

Property Type Required Description
name string ✅ Flow machine name (snake_case)
enabled boolean ✅ Whether to enable (true) or disable (false) the flow

ToggleFlowResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } optional Response metadata
data { name: string; enabled: boolean } ✅

TriggerFlowRequest

Properties

Property Type Required Description
name string ✅ Flow machine name (snake_case)
record Record<string, any> optional Record that triggered the automation
object string optional Object name the record belongs to
event string optional Trigger event type
userId string optional User who triggered the automation
params Record<string, any> optional Additional contextual data

TriggerFlowResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } 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 } ✅

UpdateFlowRequest

Properties

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

UpdateFlowResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } 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