Skip to main content
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 capability details.

​
Endpoint

POST /api/workflows/:slug/run

​
Authentication

Requires a key with capability workflow:run (any of your workflows) OR workflow:<slug>:run (the specific slug only — useful for least-privilege CI keys). Pass your API key in the x-api-key header.

​
Rate limits

Limits depend on your tier (independent of capabilities):
TierLimit
Pro100 req/min
Business1,000 req/min
Enterpriseunlimited
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 (sync — 200)

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 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.

​
Async opt-in (?async=true)

For long-running pipelines you can append ?async=true to submit the workflow without blocking. The response returns in under 500ms with an executionId; poll GET /api/executions/:id or receive a webhook callback when the run completes. 
curl -X POST "https://knouds.ai/api/workflows/my-thumbnail-pipeline/run?async=true" \
  -H "x-api-key: $KNOUDS_KEY" -H "Content-Type: application/json" \
  -d '{"inputs":{"product_name":"Knouds"}}'
# → {"_async":true,"executionId":"<uuid>","requestId":"<provider-id>","status":"processing","pollUrl":"/api/executions/<uuid>"}
Async opt-in is supported only on workflows whose generators are HTTP+polling defs (Seedance, Suno, gpt-image-2 today). Other providers reject with 400 ASYNC_NOT_SUPPORTED. See Async executions for the full lifecycle.

​
Errors

StatusCodeMeaning
400INVALID_INPUTSThe inputs field is missing, not an object, or contains values that fail validation.
400ASYNC_NOT_SUPPORTED?async=true on a provider that doesn’t support polling. Use sync mode.
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.
403CAPABILITY_DENIEDYour key lacks workflow:run (or the per-slug workflow:<slug>:run). Response includes required.
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 tier. 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.