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:

{ "data": { }, "meta": { "request_id": "req_..." } }

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

{
  "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.

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)

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:

{ "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):

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:

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

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; 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.

​Using the Workflows API

​Authentication & Scopes

​Response Envelope

​Endpoints

​Create a workflow

​Execute a workflow (idempotent)

​Inspect executions

​Cancel a run

​Webhook Events

​SDKs, Postman & OpenAPI

​Next Steps

Triggers

Webhooks