Skip to main content
Every Knouds API request must include a valid API key. Each key carries a set of capabilities that determine which endpoints you can call. Capabilities are orthogonal — a key holds an explicit subset (mix and match by use case) rather than a single rank.

​
Generating a key

Go to Settings → API Keys in your Knouds account (or the Developer Dashboard) and create a new key. The full key value is shown exactly once at creation time — copy it immediately. If you lose it, you must revoke the key and generate a new one. When you create a key, you pick a preset (or Custom for granular grants):
PresetCapabilities granted
Read-onlyworkflow:read
Workflow Deployworkflow:run, workflow:read
Webhook receiverwebhook:receive
Full deployworkflow:run, workflow:read, workflow:write
CustomAny subset capped by your tier ceiling (see below)
Free users cannot create usable API keys — Free tier has no external API access by product design. Pro+ unlocks key creation.

​
Passing your key

Include the key in the x-api-key header on every request: 
x-api-key: YOUR_KEY

curl -X POST https://knouds.ai/api/workflows/my-pipeline/run \
  -H "x-api-key: $KNOUDS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"prompt": "a serene lake at dusk"}}'

​
Capability vocabulary

CapabilityReachesTier minimum to grant
workflow:runPOST /api/workflows/:slug/run (any flow you own)Pro
workflow:readGET /api/workflows, :slug, :slug/schemaPro
workflow:writePOST/PUT/DELETE /api/workflows (ownership-checked)Pro
workflow:<slug>:runPOST /api/workflows/<slug>/run (specific flow only — useful for least-privilege CI keys)Pro
model:runPOST /api/models/:internalName/run (any registry model)Business
model:<internalName>:runPOST /api/models/<internalName>/run (specific model only)Business
webhook:receiveReceive outbound webhook deliveries (the ?async=true flow). Per-key URL + signing-secret config is session-only at /api/api-keys/:id/webhook.Pro
execution:readGET /api/executions/:id — poll your own async executionsevery tier
execution:cancelPOST /api/executions/:id/cancel — cancel your own in-flight executionsevery tier
agent:invokeReserved for SSE / streaming (not yet shipped)Business
Capabilities are orthogonal, not cumulative — a key with model:run does NOT automatically get workflow:write. Grant exactly what your integration needs.

​
Match logic

requireCapability(cap) resolves with a 4-step check:
  1. Key has * (admin override) → pass
  2. Key has cap exactly → pass
  3. Key has <resource>:* matching cap (resource-level wildcard) → pass
  4. Required cap is <resource>:<id>:<action> AND key has <resource>:<action> (general implies specific) OR <resource>:*:<action> (pattern admission) → pass
Otherwise → 403 CAPABILITY_DENIED. A key with workflow:run passes POST /api/workflows/anything/run (general implies specific). A key with workflow:my-flow:run only passes that specific slug.

​
Tier ceiling

A user can only grant capabilities up to their tier’s ceiling. The server rejects above-ceiling grants with 403 CAPABILITY_ABOVE_CEILING.
TierCan grant on API keys
Free(nothing — no external API access)
Proworkflow:run, workflow:read, workflow:write, workflow:<slug>:run, webhook:receive
Business+ model:run, model:<internalName>:run, agent:invoke
Enterprise(same as Business)

​
Error responses

​
Missing or invalid key — 401

{ "error": "Unauthorized" }
Check that the x-api-key header is present and that the key has not been deleted from the dashboard.

​
Pre-Phase-11 key retired — 401

{
  "error": "API key retired by Phase 11 migration. Regenerate at https://knouds.ai/app/api/keys",
  "code": "LEGACY_KEY_RETIRED"
}
Keys created before May 2026 (the Phase 11 capability cutover) were retired. Generate a new key from the Developer Dashboard. See Migration from scopes for the mapping.

​
Capability denied — 403 CAPABILITY_DENIED

If your key’s capability set does not cover the endpoint, you receive a 403: 
{
  "error": "Insufficient capability",
  "code": "CAPABILITY_DENIED",
  "required": "workflow:run"
}
Use the required field to know which capability would have passed. Either regenerate your key with broader capabilities (capped by your tier) or upgrade your tier.

​
Capability above ceiling — 403 CAPABILITY_ABOVE_CEILING

If you try to grant a capability above your tier’s ceiling at key creation time: 
{
  "error": "Capability above your tier ceiling",
  "code": "CAPABILITY_ABOVE_CEILING",
  "attempted": "model:run"
}
Upgrade your tier to Business+ or grant a lower-tier capability instead.

​
Free tier no API access — 403 API_KEY_ACCESS_DENIED

Free tier users attempting to create an API key receive: 
{
  "error": "API key access requires Pro or higher",
  "code": "API_KEY_ACCESS_DENIED"
}
Upgrade to Pro to unlock external API access.