Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knouds.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Knouds API accepts two forms of authentication: session cookies when you’re calling from a browser, and API keys when you’re calling from scripts, CI pipelines, or external integrations. For programmatic access, API keys are the right choice.

​
Generate an API key

The plaintext key is shown only once — immediately after creation. Copy it before closing the dialog. If you lose it, you must delete the key and generate a new one.
  1. Open Settings → API Keys in the Knouds app.
  2. Click New API key and give the key a name (e.g. production, ci-pipeline).
  3. Copy the key that appears. It will not be shown again.
Your key’s scope is automatically set based on your account tier at creation time. If you have a Business or Enterprise account, you can also choose a lower scope when creating a key (for example, issuing a deployment-scoped key to a third party without granting full admin access).

​
Pass the key in requests

Include your API key in the x-api-key request header. Do not use Authorization: Bearer. 
curl -X POST https://knouds.ai/api/workflows/my-pipeline/run \
  -H "x-api-key: knouds_live_abc..." \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"prompt": "a neon city at night"}}'
Every authenticated API endpoint accepts this header. Requests without a valid key — or with a key whose scope does not cover the endpoint — receive a 401 or 403 response.

​
Key scopes

Every API key carries a scope that controls which endpoints it can reach. Scopes are cumulative: a higher scope inherits all the permissions of lower scopes.
ScopeDefault tierCapabilitiesRate limit
adminBusiness / EnterpriseRun any model, create, update, and delete workflows1000 req/min
deploymentProRun deployed workflows, read schemas100 req/min
freeFreeRun your own deployed workflows10 req/min
Rate limits apply per key, per route, per minute. When you exceed the limit, the API returns 429 RATE_LIMIT_EXCEEDED along with Retry-After (seconds until the window resets) and X-RateLimit-Reset (Unix epoch of the reset moment) response headers.
Every successful response from POST /api/workflows/:slug/run includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can pace your requests proactively without hitting the limit.

​
Scope errors

If your key’s scope is too low for the endpoint you’re calling, the API returns: 
{
  "error": "Scope denied",
  "code": "SCOPE_DENIED",
  "required": "admin",
  "actual": "deployment"
}
The required and actual fields tell you exactly which scope the endpoint needs and which scope your key has. To resolve this, either use a key with the required scope or upgrade your account tier.

​
Lost or compromised keys

If a key is lost or you suspect it has been exposed, delete it immediately from Settings → API Keys and generate a replacement. There is no way to recover the plaintext of an existing key. Keys you delete stop working instantly. Any integrations using the old key will begin receiving 401 responses until you update them with the new key.