> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Workflows API

> Manage and run workflows over the public /v1 API: CRUD, idempotent execution, execution history, cancellation, and completion webhooks.

# Using the Workflows API

Workflows are a first-class `/v1` resource. Everything you can do in the builder — create, update, run, inspect, and cancel — is available over the API with your tenant API key, using KnoxCall's standard response envelope, pagination, idempotency, and scopes.

## Authentication & Scopes

Authenticate with a bearer API key. The key's mode (Live/Test) scopes every response. Access is governed by workflow scopes:

| Action                   | Scope                      |
| ------------------------ | -------------------------- |
| List / read              | `workflow:read` (and list) |
| Create / update / delete | `workflow` write scopes    |
| Execute / cancel         | `workflow:execute`         |

Read-only keys can list and read; invoke keys can additionally execute; editor/member keys can manage. A key without the required scope gets `403`.

## Response Envelope

Every response is wrapped:

```json theme={"dark"}
{ "data": { }, "meta": { "request_id": "req_..." } }
```

List endpoints paginate with `page` and `per_page` query parameters and return pagination in `meta`:

```json theme={"dark"}
{
  "data": [ /* ... */ ],
  "meta": { "total": 42, "page": 1, "per_page": 20, "total_pages": 3, "request_id": "req_..." }
}
```

## Endpoints

| Method & path                                        | Description                                            |
| ---------------------------------------------------- | ------------------------------------------------------ |
| `GET /v1/workflows`                                  | List workflows (paginated)                             |
| `POST /v1/workflows`                                 | Create a workflow                                      |
| `GET /v1/workflows/{id}`                             | Get a workflow                                         |
| `PATCH /v1/workflows/{id}`                           | Update a workflow (a new definition bumps the version) |
| `DELETE /v1/workflows/{id}`                          | Delete a workflow and its executions                   |
| `POST /v1/workflows/{id}/execute`                    | Queue a run (idempotent)                               |
| `GET /v1/workflows/{id}/executions`                  | List a workflow's runs (paginated)                     |
| `GET /v1/workflows/executions/{executionId}`         | Get one run with step details                          |
| `POST /v1/workflows/executions/{executionId}/cancel` | Request cancellation of a run                          |

### Create a workflow

The `definition` is a graph with a `nodes` array containing exactly one trigger node and an `edges` array. It's validated (structure + reachable trigger) on write.

```bash theme={"dark"}
curl -X POST https://api.knoxcall.com/v1/workflows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New customer onboarding",
    "enabled": true,
    "definition": {
      "nodes": [
        { "id": "trigger-node", "type": "trigger", "position": { "x": 0, "y": 0 },
          "data": { "type": "trigger", "config": { "triggerType": "manual" } } }
      ],
      "edges": []
    }
  }'
```

Returns `201` with the created workflow (`version: 1`). An invalid graph returns `422`.

### Execute a workflow (idempotent)

```bash theme={"dark"}
curl -X POST https://api.knoxcall.com/v1/workflows/{id}/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: onboarding-42" \
  -d '{"input": {"email": "user@example.com"}}'
```

The run is queued asynchronously and the call returns `201` immediately:

```json theme={"dark"}
{ "data": { "id": "execution-uuid", "workflow_id": "{id}", "status": "queued" },
  "meta": { "request_id": "req_..." } }
```

Send the **same `X-Idempotency-Key`** again and you get the **same** execution back, with an `X-Idempotent-Replay: true` response header — a safe retry never starts a second run.

### Inspect executions

List a workflow's runs (the polling source for automation platforms):

```bash theme={"dark"}
curl "https://api.knoxcall.com/v1/workflows/{id}/executions?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Get a single run with composed step details:

```bash theme={"dark"}
curl https://api.knoxcall.com/v1/workflows/executions/{executionId} \
  -H "Authorization: Bearer YOUR_API_KEY"
```

An execution's `status` is one of `queued`, `running`, `waiting`, `paused`, `completed`, `failed`, `cancelled`, or `timed_out`. Step inputs/outputs are redacted — secret values appear as `[REDACTED]`.

### Cancel a run

```bash theme={"dark"}
curl -X POST https://api.knoxcall.com/v1/workflows/executions/{executionId}/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Cancellation aborts in-flight work (including outbound HTTP), not just a flag.

## Webhook Events

Rather than polling, subscribe an outbound webhook to run-completion events:

| Event                          | Fires when                  |
| ------------------------------ | --------------------------- |
| `workflow.execution.completed` | A run finishes successfully |
| `workflow.execution.failed`    | A run ends in failure       |

These give automation platforms (Zapier, Make, n8n) an **instant** trigger on run completion. Configure them like any other [webhook](/webhooks/webhooks-overview); payloads are signed and delivered through the same hardened egress.

## SDKs, Postman & OpenAPI

The workflows resource is available in the KnoxCall SDKs (`workflows.list / get / create / update / delete / execute / listExecutions / getExecution / cancelExecution`), in the Postman collection (**Workflows** folder), and in the OpenAPI spec. The SDK methods return the same `{ data, meta }` envelope and support the idempotency key on `create` / `execute`.

## Next Steps

<CardGroup cols={2}>
  <Card title="Triggers" icon="bolt" href="/workflows/triggers">
    Webhook and app-event triggers
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks/webhooks-overview">
    Get notified when runs finish
  </Card>
</CardGroup>