> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.aiplanet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Calling Workflows via API

> Trigger deployed workflows from your own applications.

Once a workflow is deployed, you can trigger it from your own applications through the API. This page covers the essentials: authentication, triggering a run, and getting results.

## Before you start

You need:

* A **deployed** workflow — see [Deploying a workflow](/building-workflows/deploying).
* An **API key** with permission to trigger workflows — see [API Keys](/integrations-api/api-keys).

<Note>
  Replace `https://<your-platform-host>` in the examples below with the API host for your platform. Your administrator can confirm it.
</Note>

## Authentication

Every API request includes your API key as a bearer token:

```
Authorization: Bearer <your-api-key>
```

The key identifies your organization and determines what the request is allowed to do.

## Triggering a workflow

Send a `POST` request to the trigger endpoint with the workflow's inputs:

```bash theme={null}
curl -X POST https://<your-platform-host>/api/v1/apps/workflow-execution/trigger \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_configuration_id": "<your-workflow-id>",
    "inputs": [
      { "name": "question", "type": "text", "value": "What is your refund policy?" }
    ]
  }'
```

The `inputs` array provides a value for each parameter defined on the workflow's **Input** node. The response identifies the **run** that was created, including its identifier and status.

### Inputs

Each entry in `inputs` corresponds to a parameter on the workflow's Input node. Each entry needs the parameter's `name`, its `type` (such as `text`, `file`, or `image` — matching the Input node), and the `value`. Provide every required parameter — the run won't start without them.

### Threads

To continue an existing conversation instead of starting fresh, include a `thread_id` in the request. Runs in the same thread share context, which matters for agents that use [memory](/knowledge-memory/memory-configurations). Omit `thread_id` to start a new thread automatically.

## Getting results

You have two options for retrieving a run's output:

<CardGroup cols={2}>
  <Card title="Stream as it runs" icon="bolt">
    Use the streaming trigger endpoint to receive output as a live stream of events while the run executes.
  </Card>

  <Card title="Fetch when complete" icon="clock">
    Trigger the run, then retrieve the run by its identifier once it has finished to read the final output.
  </Card>
</CardGroup>

Streaming is best for interactive experiences where you want to show output as it's produced. Fetching on completion is simpler for background jobs.

## Handling errors

The API uses standard HTTP status codes. Build handling for:

* **Authentication errors** — the key is missing, invalid, or lacks the required permission.
* **Not found** — the workflow identifier doesn't exist or isn't accessible to your key.
* **Invalid request** — required inputs are missing or malformed.
* **Rate limited** — you're sending requests too quickly; wait briefly and retry. See [Execution limits](/running-monitoring/execution-limits).

<Tip>
  Add retry-with-backoff for rate-limit errors in any integration that triggers workflows at volume.
</Tip>

## Next steps

<Card title="Environment variables" icon="gear" href="/integrations-api/environment-variables">
  Manage configuration values your workflows use at runtime.
</Card>