Knouds workflows and models are reachable from any external system through a REST API. To call the API, you generate a key, attach it to your requests with the x-api-key header, and your account must hold the right capabilities for the endpoint. This page covers each step end-to-end.
Generate a key
Sign in to knouds.ai and open the Developer Dashboard (also accessible from Settings → API Keys, which redirects). Click Create Key and pick a preset:
| Preset | Capabilities granted |
|---|
| Read-only | workflow:read |
| Workflow Deploy | workflow:run, workflow:read |
| Webhook receiver | webhook:receive |
| Full deploy | workflow:run, workflow:read, workflow:write |
| Custom | Any subset capped by your tier ceiling |
Free tier cannot create usable API keys. The Free API key ceiling is empty by product design — Free users save and run workflows from the canvas (browser session). Pro+ unlocks key creation.
Send your key
Pass the key in the x-api-key request header:
Every authenticated API endpoint accepts this header. Requests without a valid key — or with a key whose capabilities don’t cover the endpoint — receive a 401 or 403 response.
Capabilities
Each key carries a SET of capabilities, granted at creation time. Capabilities are orthogonal — a key with model:run does not automatically get workflow:write. Mix and match by use case (read-only audit key, single-flow CI key, full deploy key).
| Capability | Plan tier | Reaches |
|---|
workflow:run | Pro | Run any of your deployed workflows |
workflow:read | Pro | List workflows, read schemas |
workflow:write | Pro | Create, update, delete (ownership-checked) |
workflow:<slug>:run | Pro | Specific flow only (least-privilege CI keys) |
model:run | Business | Run any registry model |
model:<id>:run | Business | Specific model only |
webhook:receive | Pro | Receive outbound webhooks for ?async=true runs |
execution:read | every tier | Poll your own async executions |
execution:cancel | every tier | Cancel your own in-flight executions |
{
"error": "Insufficient capability",
"code": "CAPABILITY_DENIED",
"required": "workflow:run"
}
required field tells you exactly which capability would have passed. Either regenerate the key with broader capabilities (capped by your tier) or upgrade your tier.
See API Reference → Authentication for the full capability vocabulary, match logic, and error responses.
Rotate or revoke a key
Keys never expire automatically. To rotate:
- Open the Developer Dashboard
- Click Revoke on the old key
- Click Create Key to generate a replacement
- Update your integration’s
x-api-key header
