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

# Run a deployed Knouds workflow via REST API

> Execute any deployed Knouds workflow by slug, pass inputs as JSON, and receive the pipeline's output along with credit cost and execution time.

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.

<Note>
  Your account must be approved and your API key must be active before you can call this endpoint. See [Authentication](/api/authentication) for key setup and capability details.
</Note>

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

<ParamField path="slug" type="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.
</ParamField>

## Request body

<ParamField body="inputs" type="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`](/api/workflow-schema) to discover the exact field names and types before scripting calls.
</ParamField>

```json theme={null}
{
  "inputs": {
    "<field-name>": "<value>"
  }
}
```

## Response (sync — 200)

A `200` response means the workflow ran to completion and all output nodes produced results.

<ResponseField name="success" type="boolean">
  Always `true` on a 200 response.
</ResponseField>

<ResponseField name="result" type="object">
  The workflow's output. The exact shape depends on the Response Output node type configured in the workflow. Common shapes include:

  <Expandable title="result properties">
    <ResponseField name="images" type="array">
      Array of image output objects. Each object includes a `url` field pointing to an S3-hosted image.
    </ResponseField>

    <ResponseField name="videos" type="array">
      Array of video output objects. Each object includes a `url` field.
    </ResponseField>

    <ResponseField name="text" type="string">
      Plain text or markdown output from an assistant or text-based node.
    </ResponseField>

    <ResponseField name="audios" type="array">
      Array of audio output objects. Each object includes a `url` field.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cost" type="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.
</ResponseField>

<ResponseField name="ms" type="number">
  Total execution time in milliseconds, measured from the moment the server received the request to the moment all nodes completed.
</ResponseField>

## 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`](/api/async-executions) or receive a webhook callback when the run completes.

```bash theme={null}
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](/api/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

<CodeGroup>
  ```bash cURL theme={null}
  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"}}'
  ```

  ```python Python theme={null}
  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()
  ```

  ```javascript Node.js theme={null}
  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();
  ```
</CodeGroup>

Example response:

```json theme={null}
{
  "success": true,
  "result": {
    "images": [
      { "url": "https://knouds-media.s3.amazonaws.com/media/abc123.png" }
    ]
  },
  "cost": 12,
  "ms": 8420
}
```

<Tip>
  Not sure what inputs your workflow expects? Call [`GET /api/workflows/:slug/schema`](/api/workflow-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.
</Tip>