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

# Trigger Template

> Start a clipping workflow from a saved template using a long-form video URL

### Endpoint

```http theme={null}
POST https://api.joinoverlap.com/trigger-template
```

Use this endpoint to launch an Overlap clipping workflow from an existing template.

> [!NOTE]
>
> Find `workflowId` in the workflow URL: `https://portal.overlap.ai/workflows/{workflowId}/trigger`.

### Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Overlap-Workflow-Channel: stable
```

Generate an API key from the workflow trigger screen in the Overlap portal.
`Overlap-Workflow-Channel` is optional; omit it to use the current workflow runtime.

## Request Body

Required fields are `companyId`, `workflowId`, and `url`. Every other field is optional and overrides the saved template only for this run.

```json theme={null}
{
  "companyId": "your-company-id",
  "workflowId": "your-workflow-id",
  "url": "https://example.com/source-video.mp4",
  "broll": true,
  "subtitles": true,
  "promptAdjustment": "Prioritize clips about product announcements.",
  "pinnedTimestamps": [{ "start": 120, "end": 165 }],
  "pinnedTimestampsOnly": false,
  "pinnedTimestampMode": "search_within"
}
```

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `companyId` | string | Yes | Your Overlap company or organization identifier. |
| `workflowId` | string | Yes | The workflow/template identifier to launch. |
| `url` | string | Yes | Publicly accessible long-form video URL to process. |
| `orientation` | string | No | Override output orientation, such as `horizontal` or `vertical`. |
| `minLengthTarget` / `maxLengthTarget` | number | No | Override clip duration bounds in seconds. |
| `broll` | boolean | No | Enable or disable automatic b-roll for this run. |
| `subtitles` | boolean | No | Enable or disable subtitles for this run. |
| `subtitleConfig` | object | No | Override subtitle styling when the workflow includes a subtitle node. |
| `titleOverlay` | boolean | No | Enable or disable the title overlay when the workflow includes a title overlay node. |
| `titleConfig` | object | No | Override title overlay prompt and styling. To set fixed title text instead of an AI-generated title, include `generateTitle: false` along with `text` (see [Node Config](https://docs.overlap.ai/api-reference/node-config-overrides.md)). |
| `watermarkUrl` | string | No | Override the watermark asset URL. |
| `keywords` | string\[] | No | Transcription enrichment keywords. Maximum 150. |
| `promptAdjustment` | string | No | Text appended to the workflow's clipping prompt. Clips requested by time in this text (for example `2:15-3:40 pricing` or `around 12:30, hiring`) are added as timestamp ranges for Highlights runs. See [Find Clips](https://docs.overlap.ai/nodes/findclips.md#timestamps-in-the-prompt-adjustment). |
| `pinnedTimestamps` | object\[] | No | Source-video timestamp ranges in seconds, as `{ "start", "end" }`. Each item may also set `kind` (`exact` for a guaranteed clip, `zone` to search that area), `topic` (what the clip is about), and `snap` (`true` to align an exact clip to complete sentences). Items without `kind` follow `pinnedTimestampMode`. |
| `pinnedTimestampsOnly` | boolean | No | When `true`, return only the clips from `pinnedTimestamps`; defaults to also discovering clips. |
| `pinnedTimestampMode` | string | No | Use `search_within` to find individual clips only inside `pinnedTimestamps`; omit it for guaranteed timestamp clips. |
| `nodeConfigs` | object | No | Advanced node-level overrides keyed by workflow node type. |

### Selecting a styled title template

`titleConfig` accepts the same fields as the title node's `title_config`, so a
run can pick one of the [styled title templates](https://docs.overlap.ai/api-reference/node-config-overrides.md#styled-title-templates)
by id and, optionally, a palette. Selecting a template resets any template
customizations saved on the workflow's title node, so the request is the only
source of styling for that run. Combine it with `generateTitle: false` and
`text` to pin the headline, or omit those two fields to let the node's prompt
write it.

```json theme={null}
{
  "companyId": "your-company-id",
  "workflowId": "your-workflow-id",
  "url": "https://example.com/source-video.mp4",
  "orientation": "vertical",
  "titleOverlay": true,
  "titleConfig": {
    "titlePresetId": "cyan-block-title",
    "titlePaletteId": "breaking-news",
    "generateTitle": false,
    "text": "Storm hits coast, thousands flee"
  }
}
```

The template's own entrance and exit motion, duration, and placement are
applied automatically. The palettes each template accepts are listed with the
[styled title templates](https://docs.overlap.ai/api-reference/node-config-overrides.md#styled-title-templates).

## Workflow Runtime Channel

By default, requests run on the current workflow service. To use the pinned stable service for a run, add:

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

Only `current` and `stable` are accepted. Any other value returns `INVALID_WORKFLOW_CHANNEL` without storing or dispatching the run. The response echoes the applied channel in the same header. The channel is routing metadata and is not passed to workflow nodes as input.

> [card] [Workflow Runtime Channels](https://docs.overlap.ai/api-reference/workflow-runtime-channels.md)
>
> See channel behavior, complete request examples, responses, and errors

## Google Drive Source URLs

You can use a Google Drive video as the `url` value when triggering a workflow. Before sending the request, verify both of these requirements:

1. Use a direct Google Drive **file** link. The URL should include `/file/`, for example `https://drive.google.com/file/d/FILE_ID/view?usp=sharing`. Folder links, preview links, and other Drive URLs that do not include `/file/` are not supported source-file links.
2. Make the file accessible to Overlap. Either set the file to public access, or share it directly with the Overlap service account: `firebase-adminsdk-pnxcn@rizeo-40249.iam.gserviceaccount.com`.

If the Drive file is private and is not shared with that service account, the workflow may trigger successfully but fail when Overlap tries to download the source video.

## Override Behavior

Overrides only apply when the referenced workflow contains the matching node. For example, `subtitleConfig` is ignored if the workflow does not include a subtitles node.

For advanced integrations, use `nodeConfigs`, `nodeConfigOverrides`, or `actionConfigs` to update action node configuration directly. Supported node keys include `find_clips`, `convert_to_vertical`, `style_video`, `add_broll`, `add_music`, and other workflow action nodes.

If a workflow contains the target node but the override shape is invalid, the request returns an `INVALID_NODE_CONFIG` error.

> [card] [Node Config Overrides](https://docs.overlap.ai/api-reference/node-config-overrides.md)
>
> See frontend-configurable override fields and per-node examples

```javascript javascript theme={null}
// Node.js (using fetch)
const apiUrl = "https://api.joinoverlap.com/trigger-template";

const headers = {
  "Content-Type": "application/json",
  "Authorization": `Bearer ${process.env.OVERLAP_API_KEY}`,
  "Overlap-Workflow-Channel": "stable"
};

const payload = {
  companyId: process.env.OVERLAP_COMPANY_ID,
  workflowId: process.env.OVERLAP_WORKFLOW_ID,
  url: "https://example.com/source-video.mp4",
  broll: true
};

fetch(apiUrl, {
  method: "POST",
  headers,
  body: JSON.stringify(payload)
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));
```

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

api_url = "https://api.joinoverlap.com/trigger-template"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['OVERLAP_API_KEY']}",
    "Overlap-Workflow-Channel": "stable"
}

payload = {
    "companyId": os.environ["OVERLAP_COMPANY_ID"],
    "workflowId": os.environ["OVERLAP_WORKFLOW_ID"],
    "url": "https://example.com/source-video.mp4",
    "broll": True
}

response = requests.post(api_url, json=payload, headers=headers)
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",
           "broll": true
         }'
```

## Response

```json theme={null}
{
  "triggerId": "c1a27b63-91d9-45fb-9c89-5f418442fb6e",
  "status": "pending",
  "message": "Workflow trigger initiated successfully"
}
```

* `triggerId` - Save this value and poll `GET /workflow-results/{triggerId}`.
* `status` - Usually `pending` immediately after triggering.
* `message` - Human-readable confirmation or context.

The `Overlap-Workflow-Channel` response header reports `current` or `stable`, matching the runtime selected for the run.

## Processing Time

* Horizontal clips: about 3 minutes per hour of input video.
* Vertical clips: about 10 minutes per hour of input video.
* Actual runtime varies by workflow configuration, video length, and video complexity.

> [card] [Get workflow results](https://docs.overlap.ai/api-reference/results.md)
>
> Poll for status and retrieve generated clips with your triggerId


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.