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.

Use this endpoint to run a deployed workflow programmatically. You pass the workflow’s slug and the input values your pipeline expects, and Knouds executes the full node graph synchronously, returning the output when the run is complete.
Your account must be approved and your API key must be active before you can call this endpoint. See Authentication for key setup and scope details.

​
Endpoint

POST /api/workflows/:slug/run

​
Authentication

Any authenticated scope (free, deployment, or admin). Pass your API key in the x-api-key header.

​
Rate limits

Rate limits depend on your key’s scope:
ScopeLimit
free10 req/min
deployment100 req/min
admin1000 req/min
Every successful response includes rate limit headers so you can pace requests without guessing:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix epoch second when the window resets
On a 429 response, an additional Retry-After header tells you how many seconds to wait before retrying.

​
Path parameters

​
slug
string
required
The workflow’s URL slug — the identifier that appears in the editor URL when you open the workflow (for example, my-thumbnail-pipeline). Slugs are lowercase letters, digits, and hyphens. A workflow’s slug never changes after it is created.

​
Request body

​
inputs
object
required
Key/value pairs matching the workflow’s Request Input fields. The accepted keys and value types depend on how the workflow author configured the Request Input node. Use GET /api/workflows/:slug/schema to discover the exact field names and types before scripting calls.
{
  "inputs": {
    "<field-name>": "<value>"
  }
}

​
Response

A 200 response means the workflow ran to completion and all output nodes produced results.
​
success
boolean
Always true on a 200 response.
​
result
object
The workflow’s output. The exact shape depends on the Response Output node type configured in the workflow. Common shapes include:
​
cost
number
Credits consumed by this run. The amount reflects your account tier’s pricing and any markup applied. A value of 0 means the run consumed a trial grant rather than deducting from your credit balance.
​
ms
number
Total execution time in milliseconds, measured from the moment the server received the request to the moment all nodes completed.

​
Error responses

StatusCodeMeaning
400INVALID_INPUTSThe inputs field is missing, not an object, or contains values that fail validation.
402INSUFFICIENT_CREDITSYour account does not have enough credits to run the workflow.
402grant_exhaustedYour trial grant for a model in this workflow has been used up. Upgrade your plan to continue.
403MODEL_TIER_REQUIREDThe workflow contains a model that requires a higher plan tier than your account holds.
404—No workflow exists with the provided slug, or it does not belong to your account.
429RATE_LIMIT_EXCEEDEDYou have exceeded the per-minute limit for your key scope. Check the Retry-After header.
500EXECUTION_FAILEDA provider call inside the pipeline failed. The error field describes the cause.

​
Example

curl -X POST https://knouds.ai/api/workflows/my-thumbnail-pipeline/run \
  -H "x-api-key: $KNOUDS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"product_name": "Knouds", "tagline": "AI pipelines"}}'
Example response: 
{
  "success": true,
  "result": {
    "images": [
      { "url": "https://knouds-media.s3.amazonaws.com/media/abc123.png" }
    ]
  },
  "cost": 12,
  "ms": 8420
}
Not sure what inputs your workflow expects? Call GET /api/workflows/:slug/schema first to retrieve the field names and types defined in the Request Input node. This saves you from INVALID_INPUTS errors when scripting against a workflow you didn’t build yourself.