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

# Workflow Runtime Channels

> Choose the current or pinned stable workflow runtime for an API-triggered run

Workflow runtime channels let an integration choose which deployed workflow service executes a triggered run. The channel is transport-level routing metadata, so it is supplied as an HTTP header rather than as part of the workflow input.

## Available Channels

| Channel   | Behavior                                                                           |
| --------- | ---------------------------------------------------------------------------------- |
| `current` | Uses the current workflow service. This is the default when the header is omitted. |
| `stable`  | Uses the most recent stable, major release service.                                |

To select the stable channel:

```http theme={null}
Overlap-Workflow-Channel: stable
```

Only the exact values `current` and `stable` are accepted.

## Trigger a Stable Run

Add the channel header to `POST /trigger-template`. The JSON request body does not change.

<RequestExample>
  ```javascript javascript theme={null}
  const response = await fetch("https://api.joinoverlap.com/trigger-template", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.OVERLAP_API_KEY}`,
      "Content-Type": "application/json",
      "Overlap-Workflow-Channel": "stable"
    },
    body: JSON.stringify({
      companyId: process.env.OVERLAP_COMPANY_ID,
      workflowId: process.env.OVERLAP_WORKFLOW_ID,
      url: "https://example.com/source-video.mp4"
    })
  });

  console.log(response.headers.get("Overlap-Workflow-Channel"));
  console.log(await response.json());
  ```

  ```python python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.joinoverlap.com/trigger-template",
      headers={
          "Authorization": f"Bearer {os.environ['OVERLAP_API_KEY']}",
          "Overlap-Workflow-Channel": "stable",
      },
      json={
          "companyId": os.environ["OVERLAP_COMPANY_ID"],
          "workflowId": os.environ["OVERLAP_WORKFLOW_ID"],
          "url": "https://example.com/source-video.mp4",
      },
  )

  print(response.headers["Overlap-Workflow-Channel"])
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.joinoverlap.com/trigger-template" \
    -H "Authorization: Bearer $OVERLAP_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Overlap-Workflow-Channel: stable" \
    -d '{
      "companyId": "'"$OVERLAP_COMPANY_ID"'",
      "workflowId": "'"$OVERLAP_WORKFLOW_ID"'",
      "url": "https://example.com/source-video.mp4"
    }'
  ```
</RequestExample>

## Response

The response body retains the normal trigger contract:

```json theme={null}
{
  "triggerId": "trigger_20260728123456_ab12cd34",
  "status": "pending",
  "message": "Workflow trigger initiated successfully"
}
```

The response header reports the channel applied to the run:

```http theme={null}
Overlap-Workflow-Channel: stable
```

The selected channel is stored with the trigger. You do not need to resend the channel header when polling `GET /workflow-results/{triggerId}`.

## Invalid Channels

An unsupported or empty channel returns `400 Bad Request`. The run is not stored or dispatched.

```json theme={null}
{
  "error": "Overlap-Workflow-Channel must be either 'current' or 'stable'",
  "status": "error",
  "code": "INVALID_WORKFLOW_CHANNEL"
}
```

Do not send `workflowChannel` in the JSON body. Body fields are reserved for workflow input and per-run configuration; use the `Overlap-Workflow-Channel` header for routing.