Run a deployed Knouds workflow via REST API

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):

Tier	Limit
Pro	100 req/min
Business	1,000 req/min
Enterprise	unlimited

Every successful response includes rate limit headers so you can pace requests without guessing:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix 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

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

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.

boolean

Always true on a 200 response.

object

The workflow’s output. The exact shape depends on the Response Output node type configured in the workflow. Common shapes include:

Show result properties

array

Array of image output objects. Each object includes a url field pointing to an S3-hosted image.

array

Array of video output objects. Each object includes a url field.

string

Plain text or markdown output from an assistant or text-based node.

array

Array of audio output objects. Each object includes a url field.

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.

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

Status	Code	Meaning
`400`	`INVALID_INPUTS`	The `inputs` field is missing, not an object, or contains values that fail validation.
`400`	`ASYNC_NOT_SUPPORTED`	`?async=true` on a provider that doesn’t support polling. Use sync mode.
`402`	`INSUFFICIENT_CREDITS`	Your account does not have enough credits to run the workflow.
`402`	`grant_exhausted`	Your trial grant for a model in this workflow has been used up. Upgrade your plan to continue.
`403`	`CAPABILITY_DENIED`	Your key lacks `workflow:run` (or the per-slug `workflow:<slug>:run`). Response includes `required`.
`403`	`MODEL_TIER_REQUIRED`	The 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.
`429`	`RATE_LIMIT_EXCEEDED`	You have exceeded the per-minute limit for your tier. Check the `Retry-After` header.
`500`	`EXECUTION_FAILED`	A 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"}}'

import os, requests

response = requests.post(
    'https://knouds.ai/api/workflows/my-thumbnail-pipeline/run',
    headers={
        'x-api-key': os.environ['KNOUDS_KEY'],
        'Content-Type': 'application/json',
    },
    json={'inputs': {'product_name': 'Knouds', 'tagline': 'AI pipelines'}},
)
data = response.json()

const response = await fetch(
  'https://knouds.ai/api/workflows/my-thumbnail-pipeline/run',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.KNOUDS_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      inputs: { product_name: 'Knouds', tagline: 'AI pipelines' },
    }),
  }
);
const data = await response.json();

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.

Overview

Identity & Usage

Endpoints

Async & Webhooks

Run a deployed Knouds workflow via REST API

Endpoint

Authentication

Rate limits

Path parameters

Request body

Response (sync — 200)

Async opt-in (`?async=true`)

Errors

Example

​Endpoint

​Authentication

​Rate limits

​Path parameters

​Request body

​Response (sync — 200)

​Async opt-in (?async=true)

​Errors

​Example

Endpoint

Authentication

Rate limits

Path parameters

Request body

Response (sync — 200)

Async opt-in (`?async=true`)

Errors

Example