The Knouds REST API lets you run deployed workflows, invoke individual registry models, manage workflow definitions, and poll async executions programmatically. Every request and response uses JSON over HTTPS.
Base URL
All endpoints are served from:
There is no version prefix in the URL. The current stable surface is the v4.13+ contract (Phase 11 capabilities + Phase 12 dashboard + Phase 13 async/webhooks). Additive changes (new optional fields, new capabilities, new endpoints) roll out continuously without versioning. Breaking changes ship with a major-version entry in the changelog.
Set Content-Type: application/json on every request that includes a body. Endpoints that accept no body (GET requests) ignore the header.
Authentication
Every API endpoint requires a valid API key passed in the x-api-key request header. Keys are generated in the Developer Dashboard (or Settings → API Keys, which redirects there).
curl https://knouds.ai/api/whoami \
-H "x-api-key: YOUR_KEY"
401 and 403 responses.
All responses — including errors — are JSON objects. Successful responses vary by endpoint. Error responses always include at minimum:
{ "error": "<message>", "code": "<CODE>" }
Available endpoints
Capabilities below are the minimum required. A key with * (admin-only) passes everything.
Identity
| Method | Path | Capability | Description |
|---|
GET | /api/whoami | (any authenticated) | Identity + tier — pre-flight check that your key is valid |
Workflows
| Method | Path | Capability | Description |
|---|
POST | /api/workflows/:slug/run | workflow:run or workflow:<slug>:run | Run a deployed workflow synchronously |
POST | /api/workflows/:slug/run?async=true | same + optional webhook:receive | Submit async; returns executionId immediately |
GET | /api/workflows/:slug/schema | workflow:read | Get a workflow’s input schema |
GET | /api/workflows/:slug/public-schema | none | Public schema (only when publicPlayground: true) |
GET | /api/workflows | workflow:read | List your workflows |
GET | /api/workflows/:slug | workflow:read | Full workflow JSON |
POST | /api/workflows | workflow:write | Create a workflow (Free capped at 1) |
PUT | /api/workflows/:slug | workflow:write (+ ownership) | Update |
PUT | /api/workflows/:slug/move | workflow:write (+ ownership) | Change folder |
DELETE | /api/workflows/:slug | workflow:write (+ ownership) | Delete |
Models (Business+)
| Method | Path | Capability | Description |
|---|
POST | /api/models/:internalName/run | model:run or model:<internalName>:run | Run any registry model — including the formerly-native ones (nano-banana-2, seedream-v5, kling-v3-i2v, kling-o3-ref2v, kling-v3-motion, claude-sonnet) |
POST | /api/models/:internalName/run?async=true | same | Submit async on polling-supported defs (Seedance, Suno, gpt-image-2) |
Executions (every tier)
| Method | Path | Capability | Description |
|---|
GET | /api/executions/:id | execution:read | Poll an async execution |
POST | /api/executions/:id/cancel | execution:cancel | Cancel an in-flight execution (always-charge policy) |
Usage
| Method | Path | Capability | Description |
|---|
GET | /api/usage | (any authenticated) | Your own API usage rows (canvas runs filtered out) |
GET | /api/usage/models | (any authenticated) | Distinct model IDs in your usage history |
Public
| Method | Path | Capability | Description |
|---|
GET | /api/pricing/public | none | Public pricing and tier information |
GET | /api/health | none | Health check |
Account approval is required before any API access is granted. If your requests return 401 and your key is valid, check that your account is approved in addition to verifying the key.
Some session-only endpoints (/api/me, /api/credits/*, /api/api-keys/*, /api/business/admin/*) are not reachable with API keys by design (defense-in-depth on key + account management). Use the Developer Dashboard for those operations. 