Base path: /api/v1/workflows
Workflows are the core automation unit in the platform. Each workflow has a definition (steps, inputs, environment variables, schedule) and can have multiple published versions plus an active draft.
All endpoints require JWT authentication and an x-active-org header.
Endpoints Overview
| Method | Path | Auth | Description |
|---|
| GET | /api/v1/workflows | JWT | List workflows |
| GET | /api/v1/workflows/:workflowId | JWT | Get workflow details |
| GET | /api/v1/workflows/:workflowId/versions | JWT | List workflow versions |
| POST | /api/v1/workflows/:workflowId/versions/:versionId/default | JWT | Set default version |
| DELETE | /api/v1/workflows/:workflowId | JWT | Delete a workflow |
| POST | /api/v1/workflows/:workflowId/envs | JWT | Save environment variables |
| PATCH | /api/v1/workflows/:workflowId/sharing | JWT | Update team sharing |
| GET | /api/v1/workflows/:workflowId/upcoming-runs | JWT | Get upcoming scheduled runs |
| PUT | /api/v1/workflows/:workflowId/schedule | JWT | Pause or resume schedule |
| POST | /api/v1/workflows/:workflowId/schedule/parse | JWT | Parse natural-language schedule |
| DELETE | /api/v1/workflows/:workflowId/schedule | JWT | Delete schedule |
Workflow Object
The workflow field in responses is in planner format (human-readable):
GET /api/v1/workflows
Lists workflows owned by the authenticated user within the active organization.
Query Parameters
| Parameter | Type | Default | Description |
|---|
page | number | 1 | Page number (min: 1) |
limit | number | 20 | Items per page (min: 1, max: 100) |
isDraft | boolean | false | If true, lists workflows with a draft (not yet published) |
search | string | – | Search by workflow name (case-insensitive substring) |
Response 200 OK
Workflow list item fields:
| Field | Type | Description |
|---|
id | string (UUID) | Workflow ID |
name | string | Workflow name |
description | string | null | Description |
services | string[] | List of service slugs used in workflow steps |
createdAt | string (ISO 8601) | Creation time |
updatedAt | string (ISO 8601) | Last update time |
scheduleStatus | boolean | null | true = paused, false = active, null = no schedule |
sharedTeamKeys | string[] | Teams this workflow is shared with |
GET /api/v1/workflows/:workflowId
Returns full details of a specific workflow including its current published definition.
Path Parameters
| Parameter | Type | Description |
|---|
workflowId | string (UUID) | Workflow ID |
Response 200 OK
| Field | Type | Description |
|---|
id | string (UUID) | Workflow ID |
name | string | Name from default version |
description | string | null | Description from default version |
sharedTeamKeys | string[] | Teams this workflow is shared with |
isPaused | boolean | null | Schedule pause state; null if no schedule |
version | string | null | Default version number as string |
isPublic | boolean | Whether the workflow is publicly visible |
isDraft | boolean | Whether an unpublished draft exists |
createdAt | string (ISO 8601) | Creation time |
updatedAt | string (ISO 8601) | Last update time |
workflow | object | null | Full workflow definition in planner format |
GET /api/v1/workflows/:workflowId/versions
Lists published versions of a workflow, newest first.
Path Parameters
| Parameter | Type | Description |
|---|
workflowId | string (UUID) | Workflow ID |
Query Parameters
| Parameter | Type | Default | Description |
|---|
limit | number | 20 | Max versions to return (min: 1, max: 100) |
includeAll | boolean | false | If true, returns all versions (ignores limit) |
Response 200 OK
| Field | Type | Description |
|---|
versions | array | List of version objects |
total | number | Total number of versions |
truncated | boolean | Whether results were truncated by the limit |
Version object:
| Field | Type | Description |
|---|
versionId | string (UUID) | Version ID |
workflowId | string (UUID) | Parent workflow ID |
versionNumber | number | Sequential version number (1-indexed) |
isDefault | boolean | Whether this is the active/default version |
createdAt | string (ISO 8601) | When this version was created |
POST /api/v1/workflows/:workflowId/versions/:versionId/default
Sets a specific version as the default (active) version for a workflow. Requires workflow owner or write permission.
Path Parameters
| Parameter | Type | Description |
|---|
workflowId | string (UUID) | Workflow ID |
versionId | string (UUID) | Version ID to make default |
Request
No request body required.
Response 200 OK
DELETE /api/v1/workflows/:workflowId
Soft-deletes a workflow. Only the workflow owner can delete it.
Path Parameters
| Parameter | Type | Description |
|---|
workflowId | string (UUID) | Workflow ID |
Response 200 OK
POST /api/v1/workflows/:workflowId/envs
Saves (upserts) environment variables for the workflow's default published version. Only works when the workflow has a published version.
Path Parameters
| Parameter | Type | Description |
|---|
workflowId | string (UUID) | Workflow ID |
Request Body (JSON)
| Field | Type | Required | Description |
|---|
envs | array | Yes | List of environment variable objects |
Environment variable object:
| Field | Type | Required | Description |
|---|
name | string | Yes | Variable name (min length: 1) |
value | string | Yes | Variable value |
description | string | No | Human-readable description |
Response 200 OK
PATCH /api/v1/workflows/:workflowId/sharing
Replaces the team sharing configuration for a workflow.
Path Parameters
| Parameter | Type | Description |
|---|
workflowId | string (UUID) | Workflow ID |
Request Body (JSON)
| Field | Type | Required | Default | Description |
|---|
shareWithTeamKeys | string[] | Yes | [] | Team keys to share with. Pass [] to revoke all sharing. |
Response 200 OK
Returns the updated sharing result.
GET /api/v1/workflows/:workflowId/upcoming-runs
Returns the next scheduled execution times for a workflow's Temporal schedule.
Path Parameters
| Parameter | Type | Description |
|---|
workflowId | string (UUID) | Workflow ID |
Response 200 OK
Returns an empty array if no schedule is configured.
PUT /api/v1/workflows/:workflowId/schedule
Pauses or resumes the workflow's Temporal schedule.
Path Parameters
| Parameter | Type | Description |
|---|
workflowId | string (UUID) | Workflow ID |
Request Body (JSON)
| Field | Type | Required | Description |
|---|
paused | boolean | Yes | true to pause, false to resume |
Response 200 OK
Errors
| Status | Reason |
|---|
404 Not Found | No schedule exists for this workflow |
POST /api/v1/workflows/:workflowId/schedule/parse
Parses a natural language schedule description, creates/updates the Temporal schedule, and returns a human-readable description.
Path Parameters
| Parameter | Type | Description |
|---|
workflowId | string (UUID) | Workflow ID |
Request Body (JSON)
| Field | Type | Required | Description |
|---|
input | string | Yes | Natural language schedule (e.g. "every Monday at 9am", "first day of month at midnight") |
Response 200 OK
| Field | Type | Description |
|---|
success | boolean | Always true on success |
message | string | Status message |
schedule | string | null | Human-readable description of the parsed schedule |
Errors
| Status | Reason |
|---|
400 Bad Request | Could not parse a valid schedule from the input |
404 Not Found | Workflow not found or no default version |
DELETE /api/v1/workflows/:workflowId/schedule
Deletes the schedule for a workflow (removes from Temporal and the database).
Path Parameters
| Parameter | Type | Description |
|---|
workflowId | string (UUID) | Workflow ID |
Response 200 OK
Errors
| Status | Reason |
|---|
404 Not Found | No schedule found for this workflow |