Trigger Template - Overlap Docs

// 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));

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())

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
         }'

POST

trigger-template

// 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));

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())

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
         }'

Endpoint

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

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.

{
  "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).
`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:

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.
Make the file accessible to Overlap. Either set the file to public access, or share it directly with the Overlap service account: [email protected].

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.

Node Config Overrides

See frontend-configurable override fields and per-node examples

// 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));

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())

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

{
  "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.

Get workflow results

Poll for status and retrieve generated clips with your triggerId

Workflows Get Results

⌘I

​Endpoint

​Authentication

​Request Body

​Fields

​Google Drive Source URLs

​Override Behavior

Node Config Overrides

​Response

​Processing Time

Get workflow results

Endpoint

Authentication

Request Body

Fields

Google Drive Source URLs

Override Behavior

Response

Processing Time