Workflow API

Base URL:

https://api.provon.dev/v1

Public routes use a project API key. The key selects the project:

Authorization: Bearer <PROVON_API_KEY>
Content-Type: application/json

The default project key includes workflows:read, not workflows:write.

Route Forms#

Every route has two forms:

The same rule applies to /workflow-runs. Public integrations should use the shorter API-key form and must not mix a path project ID with a key from another project.

Endpoints#

Definitions#

Runs#

Paths in the tables are relative to https://api.provon.dev/v1.

Definition Model#

A workflow definition contains:

{
  "id": "workflow_01J...",
  "name": "Review a risky run",
  "description": "Create a Finding from reviewed manual input.",
  "status": "draft",
  "graph": {
    "nodes": [],
    "edges": []
  },
  "owner": "Reliability",
  "activeVersionId": null,
  "createdAt": 1760000000000,
  "updatedAt": 1760000000000,
  "publishedAt": null
}

Status is draft, active, paused, or archived. The editable graph is not executed directly. Publishing snapshots it into an immutable version and sets activeVersionId.

Each graph node requires:

Each edge requires id, source, and target. Branching edges also carry a typed branch such as true, false, case, default, success, or failure.

See Automations for supported trigger and operation families. The Workbench builder is the recommended way to discover operation parameters; the API graph is the persisted contract, not a second user-facing workflow language.

Create A Workflow#

This minimal draft accepts manual input and creates a Finding:

POST /v1/workflows

{
  "name": "Manual risk review",
  "description": "Create a Finding from an explicit invocation.",
  "status": "draft",
  "owner": "Reliability",
  "graph": {
    "nodes": [
      {
        "id": "manual",
        "kind": "trigger",
        "op": "trigger.manual",
        "label": "Manual",
        "params": {
          "inputSchema": "{\"fields\":[{\"key\":\"summary\",\"label\":\"Summary\",\"type\":\"text\",\"required\":true}],\"allowExtraFields\":false}"
        }
      },
      {
        "id": "finding",
        "kind": "operation",
        "op": "diagnostics.finding.create",
        "label": "Create a finding",
        "params": {
          "title": "Manual review: {{input.summary}}",
          "severity": "medium",
          "summary": "{{input.summary}}"
        }
      }
    ],
    "edges": [
      {
        "id": "manual-to-finding",
        "source": "manual",
        "target": "finding"
      }
    ]
  }
}

Successful creation returns 201:

{
  "workflow": {
    "id": "workflow_01J...",
    "name": "Manual risk review",
    "status": "draft"
  }
}

Client-supplied workflow IDs are ignored. Names must be unique inside the project.

Update And Publish#

PATCH /workflows/:id accepts any non-empty subset of:

{
  "name": "Manual incident review",
  "description": "Updated purpose",
  "status": "paused",
  "owner": "Agent platform",
  "graph": {
    "nodes": [],
    "edges": []
  }
}

Publish after the draft graph is complete:

POST /v1/workflows/workflow_01J.../publish

Publishing validates:

• graph structure and node IDs;
• trigger count and edge topology;
• required operation parameters;
• artifact compatibility between connected nodes;
• runtime support for every operation.

An invalid graph returns 400 with error: "invalid_workflow_graph" and an issues array. A runtime that cannot report its workflow capabilities returns 503 with error: "workflow_runtime_unavailable".

Queue A Manual Run#

POST /v1/workflows/workflow_01J.../runs
Idempotency-Key: incident-1842-review

{
  "input": {
    "summary": "The agent claimed success after the refund tool returned HTTP 400."
  }
}

The API validates manual input against the trigger's input schema and enqueues execution. It does not execute the graph inside the HTTP request. Successful enqueue returns 201 with the Run detail.

Use a stable Idempotency-Key for retried client requests. The key is scoped to the manual workflow invocation and is stored as a stable trigger reference.

List Definitions#

GET /v1/workflows?status=active&limit=50

Query parameters:

List items omit the complete graph and add nodeCount, runCount, and triggerOp. Read one definition when graph or version detail is required.

List And Inspect Runs#

GET /v1/workflow-runs?workflowId=workflow_01J...&status=failed&limit=50

Run filters:

GET /workflow-runs/:id returns:

• the complete Run, including input and output;
• the current workflow definition when it still exists;
• the immutable version used by the Run;
• ordered Step Runs with node operation, attempts, input, output, and error.

Run Control#

Invalid transitions return 409. Retry or resume only after correcting the dependency that caused the failure; otherwise the same side effect can fail again.

Pagination#

Definition and Run lists return:

{
  "pagination": {
    "limit": 50,
    "nextCursor": "1760000000000\tworkflow_01J..."
  }
}

Pass nextCursor unchanged. Do not parse it or derive a new cursor from timestamps.

Errors#

Workflow-domain errors generally return a short machine-readable error string and optional message. Authentication errors use the shared structured API error body.

Related Docs#

• Automations
• Evals
• Datasets
• Connectors
• Diagnostics API
• API reference