Public REST API

Connect Cadenio to your entire stack

Automate compliance workflows, sync run data to external systems, and build custom dashboards using scoped API keys and a standard REST interface.

Create an API key

Go to Settings → Integrations and create a new key. Select only the scopes your integration requires.

Make a request

Include the key in the Authorization: Bearer header. The base URL is https://api.cadenio.com/v1.

Handle the response

All responses are JSON with snake_case fields. Errors include a machine-readable code field.

Authentication

Bearer token authentication

All API requests must include a valid API key in the Authorization header using the Bearer scheme. Keys are prefixed with sk_live_ and are available to Enterprise organizations under Settings → Integrations.

Note: API keys are shown only once at creation. Store the key securely — it cannot be retrieved afterward. If lost, revoke it and create a new one.

Required header

Authorizationstringrequired

Must be Bearer followed by your sk_live_ API key.

Content-Typestringoptional

Required for POST and PATCH requests. Set to application/json.

Request

curl https://api.cadenio.com/v1/runs \
  -H "Authorization: Bearer sk_live_a1b2c3..." \
  -H "Content-Type: application/json"

Scopes

Scopes reference

Each API key carries a set of scopes that define exactly what operations it can perform. Session-based (UI) requests are always permitted regardless of scope configuration. Scope enforcement applies only to API key requests.

Scope	Description
`runs:read`	Read run list and run details
`runs:write`	Update tasks within a run
`runs:execute`	Launch new runs from a template
`templates:read`	Read template list and template details
`templates:write`	Create and update templates
`templates:publish`	Publish a template draft
`files:read`	Download files attached to runs
`files:write`	Upload files to attach to run tasks
`data-sources:read`	Read data source records
`data-sources:write`	Create and update data source records
`users:read`	Read organization member list
`webhooks:manage`	Create, list, and delete webhook endpoints

Rate limits

Request rate limits

Rate limits are applied per API key — not per organization. Each key has its own independent quota.

600 requests per minute per API key
Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers
Exceeding the limit returns HTTP 429 with a Retry-After header
Different keys belonging to the same org do not share quota

Rate limit headers

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1746000060

429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 8

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded. Retry after 8 seconds."
}

Error codes

All errors return a JSON body with a code field (machine-readable) and a message field (human-readable). The HTTP status code reflects the error class.

Status	Code / description
400	`INVALID_REQUEST`Malformed JSON or missing required field
401	`UNAUTHORIZED`Missing or invalid API key
401	`KEY_EXPIRED`API key has passed its expiry date
401	`KEY_REVOKED`API key has been revoked
403	`MISSING_SCOPE`Key does not have the required scope for this action
403	`PLAN_REQUIRED`Feature requires a higher-tier plan
404	`NOT_FOUND`Resource does not exist or is not accessible
409	`CONFLICT`State conflict — e.g. run already completed
422	`UNPROCESSABLE`Semantically invalid request — e.g. invalid scope value
429	`RATE_LIMITED`Rate limit exceeded. Check Retry-After header
500	`INTERNAL_ERROR`Unexpected server error. Contact support if persistent

Error response

HTTP/1.1 403 Forbidden

{
  "code": "MISSING_SCOPE",
  "message": "This action requires the 'runs:write' scope.",
  "required_scope": "runs:write"
}

Runs

A run is an execution instance of a template. It represents an in-progress or completed process with assigned tasks, deadlines, and a full audit trail.

GET/v1/runsruns:read

List runs

Returns a paginated list of runs for the organization. Results are ordered by creation date, newest first. Use query parameters to filter by status, template, or assignee.

Parameters

statusstringoptional

Filter by run status. One of: IN_PROGRESS, COMPLETED, OVERDUE, CANCELLED.

template_idstringoptional

Filter runs launched from a specific template.

assignee_idstringoptional

Filter by the user assigned as run owner.

limitintegeroptional

Number of runs per page. Default: 20, max: 100.

cursorstringoptional

Pagination cursor from the previous response's next_cursor field.

Request

curl -G https://api.cadenio.com/v1/runs \
  -H "Authorization: Bearer sk_live_..." \
  -d status=IN_PROGRESS \
  -d limit=20

Response

{
  "data": [
    {
      "id": "run_abc123",
      "name": "Vendor Onboarding — ACME Corp",
      "status": "IN_PROGRESS",
      "template_id": "tmpl_def456",
      "assignee_id": "usr_ghi789",
      "due_date": "2026-05-01T00:00:00Z",
      "created_at": "2026-04-10T14:22:00Z",
      "completed_at": null
    }
  ],
  "next_cursor": "cur_xyz",
  "has_more": true
}

POST/v1/runsruns:execute

Launch a run

Creates a new run from a published template. The run opens immediately in IN_PROGRESS status with all tasks generated from the template definition. The plain_key field in the response is the only time you receive the full key value.

Parameters

template_idstringrequired

ID of the template to launch.

namestringoptional

Custom display name for this run. Defaults to the template name.

assignee_idstringoptional

User ID to assign as the run owner.

due_datedatetimeoptional

ISO 8601 timestamp for the run SLA deadline.

form_dataobjectoptional

Key-value map of form field IDs to pre-populate on run creation.

Request

curl -X POST https://api.cadenio.com/v1/runs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl_def456",
    "name": "Vendor Onboarding — ACME Corp",
    "assignee_id": "usr_ghi789",
    "due_date": "2026-05-01T00:00:00Z"
  }'

Response

HTTP/1.1 201 Created

{
  "id": "run_abc123",
  "name": "Vendor Onboarding — ACME Corp",
  "status": "IN_PROGRESS",
  "template_id": "tmpl_def456",
  "assignee_id": "usr_ghi789",
  "due_date": "2026-05-01T00:00:00Z",
  "created_at": "2026-04-10T14:22:00Z"
}

PATCH/v1/runs/:id/tasks/:taskIdruns:write

Update a task

Updates the status, value, assignee, or deadline of a single task within a run. Completing the last required task in a run automatically transitions the run status to COMPLETED.

Parameters

statusstringoptional

Set task status. One of: COMPLETED, SKIPPED.

valueanyoptional

Form field value for the task. Type depends on the field definition.

assignee_idstringoptional

Reassign the task to a different user.

due_datedatetimeoptional

Update the per-task SLA deadline.

Request

curl -X PATCH \
  https://api.cadenio.com/v1/runs/run_abc123/tasks/task_jkl012 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "COMPLETED",
    "value": "Approved by legal review on 2026-04-10"
  }'

Response

HTTP/1.1 200 OK

{
  "id": "task_jkl012",
  "run_id": "run_abc123",
  "status": "COMPLETED",
  "value": "Approved by legal review on 2026-04-10",
  "completed_at": "2026-04-10T16:05:00Z",
  "completed_by": "usr_ghi789"
}

Templates

Templates are process blueprints. A template defines the task sequence, assignment rules, form fields, and approval criteria that each run inherits.

Method	Endpoint	Scope	Description
GET	/v1/templates	`templates:read`	List all published templates
GET	/v1/templates/:id	`templates:read`	Get a single template
POST	/v1/templates	`templates:write`	Create a template draft
PATCH	/v1/templates/:id	`templates:write`	Update a template draft
POST	/v1/templates/:id/publish	`templates:publish`	Publish a template draft

Webhooks

Webhooks deliver real-time event notifications to your system. Each payload includes an X-Cadenio-Signature header with an HMAC-SHA256 signature for validation.

POST/v1/webhookswebhooks:manage

Register a webhook

Registers a new webhook endpoint. Cadenio will send POST requests to the specified URL when the subscribed events occur. Verify the X-Cadenio-Signature header to ensure payloads originate from Cadenio.

Parameters

urlstringrequired

HTTPS endpoint to deliver event payloads to.

eventsstring[]required

List of events to subscribe. Use ["*"] to subscribe to all events.

run.completedrun.overduetask.completedrun.created

descriptionstringoptional

Human-readable label for this webhook endpoint.

secretstringoptional

Signing secret used to verify payload authenticity via HMAC-SHA256.

Request

curl -X POST https://api.cadenio.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.com/hooks/cadenio",
    "events": ["run.completed", "run.overdue"],
    "description": "Sync to ERP on run completion"
  }'

Payload sample

POST https://your-system.com/hooks/cadenio
X-Cadenio-Signature: sha256=...

{
  "event": "run.completed",
  "timestamp": "2026-04-10T16:05:00Z",
  "data": {
    "run_id": "run_abc123",
    "template_id": "tmpl_def456",
    "completed_at": "2026-04-10T16:05:00Z"
  }
}

Files

Upload and download files attached to run tasks. Files are scoped to the organization and accessible only via runs that belong to it.

Method	Endpoint	Scope	Description
GET	/v1/files/:id	`files:read`	Download a file attachment
POST	/v1/files	`files:write`	Upload a file (multipart/form-data)

Data sources

Read and write records in organizational data sources. Data sources are structured tables used to populate form fields and drive conditional logic in templates.

Method	Endpoint	Scope	Description
GET	/v1/data-sources	`data-sources:read`	List data sources
GET	/v1/data-sources/:id/records	`data-sources:read`	List records
POST	/v1/data-sources/:id/records	`data-sources:write`	Create a record
PATCH	/v1/data-sources/:id/records/:rid	`data-sources:write`	Update a record

Users

Read the organization member list. Use member IDs to assign runs and tasks via the Runs API.

Method	Endpoint	Scope	Description
GET	/v1/users	`users:read`	List organization members

API key management

Managing API keys

API keys are created and revoked from Settings → Integrations. Each key has a name, a set of scopes, an optional expiry date, and a resource mode (all resources or a selected subset of templates and folders). Organization owners and admins can manage keys. Each key is shown in full only once at creation.

Important: These endpoints require session-based authentication (cookie), not an API key. An API key cannot manage other API keys.

Endpoints

GET/v1/api-keysList active API keys

POST/v1/api-keysCreate a new API key

DELETE/v1/api-keys/:idRevoke an API key

Request

curl -X POST https://api.cadenio.com/v1/api-keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ERP Sync Integration",
    "scopes": ["runs:read", "runs:execute"],
    "resource_mode": "ALL"
  }'

Response

HTTP/1.1 201 Created

{
  "id": "key_mno345",
  "name": "ERP Sync Integration",
  "plain_key": "sk_live_a1b2c3d4e5f6...",
  "key_prefix": "sk_live_...a1b2",
  "scopes": ["runs:read", "runs:execute"],
  "resource_mode": "ALL",
  "expires_at": null,
  "created_at": "2026-04-10T12:00:00Z"
}

// plain_key is shown only once — store it securely.

Public API access requires an Enterprise plan

API keys, scoped permissions, and programmatic access to run data are available on the Enterprise plan. Talk to us to enable it for your organization.

Talk to a specialist See Enterprise plan