Workflows API

Docs

Workflows API

Full reference for workflow CRUD, approval, and run management.

`POST /api/workflows`

Create a new workflow from a goal description. Generates a plan via LLM, saves it as a draft, and sends a plan approval email.

Auth: Required

Request body:

{
  goal: string      // what you want the workflow to accomplish
  schedule?: string // optional cron string, e.g. "0 9 * * 1"
}

Response (201):

{
  workflowId: string,
  title: string,
  steps: WorkflowStep[],
  status: "draft",
  message: string
}

List all workflows for the current team.

Response: Array of workflow objects with stepCount and latestRun fields.

Get a single workflow with all steps and run history.

Response: Full workflow object including:

Approve a draft workflow and activate it. Called via email link — no session required.

Query params: ?token=<24h-JWT>

On success: Redirects to /dashboard/workflows/[id]

On failure: Returns 400 with an error message (expired token, wrong type, etc.)

Manually trigger a run for an active workflow.

Auth: Required

Preconditions:

Workflow must have status: "active" (returns 422 otherwise)
No run must currently be running or awaiting_approval (returns 409 if concurrent run exists)

Response (201):

{
  runId: number,
  conversationId: string,
  message: "Workflow run started"
}

Resume a paused workflow run after step approval or rejection. Called via email link — no session required.

Query params:

Param	Description
`token`	2-hour step approval JWT
`action`	`"approve"` or `"reject"`
`note`	Optional feedback text (used with `"reject"`)

Bot-prefetch protected — known bot/crawler user agents receive 200 OK with no side effects.

On success: Redirects to /dashboard/workflows/[id]

Add or update steps on a workflow. Used for editing a draft workflow's plan before approval.

Stop a currently running workflow run.

Auth: Required

Sets run status to "failed" with reason "Stopped by user".