Skip to main content

Workflows

CRUD, lifecycle, and triggering for workflow definitions. All routes are under /api/v1/workflows and require a JWT.

List workflows​

GET /api/v1/workflows?limit=50&offset=0
{ "data": [ { "id": "...", "name": "Daily digest", "status": "active", "enabled": true, "env": "dev", "version": 3 } ], "limit": 50, "offset": 0 }

Create a workflow​

POST /api/v1/workflows
{
  "name": "Daily digest",
  "description": "Summarizes RSS feeds and posts to Slack",
  "env": "dev",
  "dsl": { "id": "daily-digest", "trigger": { "type": "schedule", "config": { "cron": "0 9 * * *" } }, "steps": [ /* ... */ ] }
}

dsl must be a valid Workflow DSL document — invalid DSL returns 400. New workflows are created with status: "active" (auto-activated for dev convenience) and version: 1. If the trigger type is schedule (or another poller-backed trigger), a Temporal Schedule is registered automatically.

Creating a workflow is subject to the tenant's active workflow plan limit — exceeding it returns 403.

Response 201 Created — the created workflow_defs row.

Get a workflow​

GET /api/v1/workflows/{id}

Update a workflow​

PUT /api/v1/workflows/{id}
{ "name": "Daily digest v2", "description": "...", "dsl": { /* updated DSL */ } }

All fields optional — only provided fields are changed. Updating dsl re-validates it, recomputes its hash, and re-syncs any Temporal Schedule. This does not automatically create a version entry in the UI sense — workflow_versions is populated by the canvas's explicit save/version flow.

Delete a workflow​

DELETE /api/v1/workflows/{id}

Requires admin or owner. Cascades to executions, versions, schedules, API keys, and chat deployments for that workflow.

Enable / disable​

PUT /api/v1/workflows/{id}/enable
PUT /api/v1/workflows/{id}/disable

A disabled workflow's webhook/manual/public-API trigger routes return 409 Conflict; scheduled triggers are paused.

Approve (pending workflows)​

POST /api/v1/workflows/{id}/approve

Requires admin or owner. Transitions a workflow from pending_approval to active — see Workflow status & lifecycle.

Trigger manually​

POST /api/v1/workflows/{id}/trigger
{ "any": "trigger payload becomes trigger.* in the DSL" }

Starts a new Temporal RunWorkflow execution with trigger_type: "manual". The workflow must be enabled, or this returns 409. All {{ secret.NAME }} references in the DSL are resolved server-side before the execution starts.

Response 202 Accepted — the created workflow_executions row (status running).

Get schedule info​

GET /api/v1/workflows/{id}/schedule

For workflows whose trigger is backed by a Temporal Schedule (schedule, email, telegram, slack, airtable, typeform, notion, google-sheets), returns the live schedule state — next run times, recent runs, paused status. Returns {"schedule": null} for non-scheduled triggers.

Workflow health​

GET /api/v1/workflows/{id}/health
GET /api/v1/workflows/health

Per-workflow or bulk health summary — see Executions & Monitoring.

Import / export​

GET /api/v1/workflows/{id}/export
POST /api/v1/workflows/import

export downloads the workflow as a .goagents.json file (DSL + metadata). import accepts that same format and creates a new workflow from it — see Workflows — Import / export.

AI Workflow Generator​

POST /api/v1/workflows/generate

Generates a DSL from a natural-language prompt — see AI Workflow Generator for the request/response shape and tips.

Public API keys, chat, and batch runs​

Per-workflow public exposure (API keys, chat widget, batch evaluation runs) is documented in Deploying Workflows and Public & Webhook Routes.