Workflows API

Schedule recurring jobs and event-driven actions, and trigger or list runs from your backend. This service has no website widget - it is API and dashboard only. Your sk_* key routes the request to your workspace (or paired sandbox for sk_test_*).

Scopes

Scope	Allows
`service.workflows.workflows.view`	List and read workflows.
`service.workflows.workflows.manage`	Create, update, pause, resume, delete workflows.
`service.workflows.workflows.run`	Trigger a workflow run.
`service.workflows.runs.view`	List runs.

Workflows (server)

Method & path	Scope	Does
`GET /api/v1/services/workflows/workflows`	`workflows.view`	List workflows.
`POST /api/v1/services/workflows/workflows`	`workflows.manage`	Create a workflow (idempotent).
`POST /api/v1/services/workflows/workflows/{id}/run`	`workflows.run`	Trigger a manual run (idempotent).

Create a scheduled workflow with one step:

curl -X POST https://app.softsolz.uk/api/v1/services/workflows/workflows \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 11111111-2222-3333-4444-555555555555" \
  -d '{
    "name": "Daily overdue sweep",
    "schedule": "0 9 * * *",
    "steps": [ { "type": "mark_invoices_overdue" } ]
  }'

Request body fields (POST /workflows):

Field	Type	Required	Description
`name`	string	required	Workflow name (max 120 chars).
`steps`	array	required	Ordered workflow steps (at least one). See the step object shape below.
`description`	string \| null	optional	Optional description (max 500 chars).
`trigger_type`	string	optional	One of `schedule`, `manual` (default `schedule`).
`cron_expression`	string \| null	optional	Required 5-field cron expression when `trigger_type` is `schedule`.
`timezone`	string	optional	Schedule timezone (default `UTC`).
`status`	string	optional	One of `active`, `paused` (default `active`).
`visibility`	string	optional	One of `private`, `tenant`, `shared` (default `tenant` for API-created workflows).
`shared_user_ids`	array	optional	User ids the workflow is shared with (used when `visibility` is `shared`).
`shared_role_ids`	array	optional	Role ids the workflow is shared with (used when `visibility` is `shared`).

Each entry in steps is a { step_type, step_config } object. step_type is one of send_email, create_notification, send_invoice_reminder, generate_recurring_invoice, mark_invoices_overdue, invoicing_ar_summary, forms_submission_digest, payments_summary. step_config holds the step-type-specific settings (for example send_email takes { to, subject }; summary steps take { date_range }). Summary steps must be paired with a delivery step (send_email or create_notification).

Trigger a run (server)

POST /api/v1/services/workflows/workflows/{id}/run · scope service.workflows.workflows.run

Enqueues a manual run and returns immediately. Returns 409 if a run started in the last 30 seconds. Response 201 (inside data):

Field	Type	Description
`run_id`	string (uuid)	The enqueued run id; poll it via `GET /workflows/{id}/runs`.
`status`	string	Always `queued` on success.

Runs (server)

Method & path	Scope	Does
`GET /api/v1/services/workflows/runs`	`runs.view`	Recent runs across workflows.
`GET /api/v1/services/workflows/workflows/{id}/runs`	`runs.view`	Runs for one workflow.

Step types

GET /api/v1/services/workflows/action-catalog · scope service.workflows.workflows.view

Returns the valid step types. Summary steps (invoicing_ar_summary, payments_summary, forms_submission_digest) read your data for a period and must be paired with a delivery step; send_email and create_notification deliver; send_invoice_reminder, generate_recurring_invoice, and mark_invoices_overdue act on invoices directly.

Webhook events

Event	When
`workflows.run.started`	A workflow run begins.
`workflows.run.completed`	A workflow run finishes successfully.
`workflows.run.failed`	A workflow run fails.
`workflows.step.failed`	A step within a run fails.

See Webhooks for payload + signature format.