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, using KnoxCall’s standard response envelope, pagination, idempotency, and scopes.

Authentication & Scopes

Authenticate with a short-lived OAuth 2.1 access token (recommended — see Authentication; legacy tk_… API keys also work as Bearer tokens). The credential’s mode (Live/Test) scopes every response. The curl examples below assume a minted token:

# Mint a 1-hour OAuth token (client_credentials) — see /api-reference/authentication
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

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 credentials can list and read; invoke credentials can additionally execute; editor/member credentials can manage. A credential without the required scope gets 403.

Response Envelope

Every response is wrapped:

{ "data": { }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" } }

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": "550e8400-e29b-41d4-a716-446655440000" }
}

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 $TOKEN" \
  -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 $TOKEN" \
  -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": "550e8400-e29b-41d4-a716-446655440000" } }

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 $TOKEN"

Get a single run with composed step details:

curl https://api.knoxcall.com/v1/workflows/executions/{executionId} \
  -H "Authorization: Bearer $TOKEN"

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 $TOKEN"

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 list methods (list / listExecutions) return the { data, meta } envelope; single-object methods (get / create / execute / …) return the unwrapped resource. The idempotency key is supported 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