> ## 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.
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
```
Generate an API key from the workflow trigger screen in the Overlap portal.
## 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](/api-reference/node-config-overrides)). |
| `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. |
| `pinnedTimestamps` | object\[] | No | Source-video timestamp ranges to include as clips for this run. |
| `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. |
## 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`, `add_subtitles`, `add_broll`, `add_music`, `add_watermark`, `apply_branding`, `add_title_overlay`, 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.
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}`
};
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']}"
}
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" \
-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 triggered successfully."
}
```
* `triggerId` - Save this value and poll `GET /workflow-results/{triggerId}`.
* `status` - Usually `pending` immediately after triggering.
* `message` - Human-readable confirmation or context.
## 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.
Poll for status and retrieve generated clips with your triggerId