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}`,
  "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));

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

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

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}`,
  "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));

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

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

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

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

Workflow Runtime Channel

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

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.

Workflow Runtime Channels

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:

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}`,
  "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));

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

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

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

Get workflow results

Poll for status and retrieve generated clips with your triggerId

⌘I

Workflows

Clip

Analytics

Misc

Endpoint

Authentication

Request Body

Fields

Workflow Runtime Channel

Workflow Runtime Channels

Google Drive Source URLs

Override Behavior

Node Config Overrides

Response

Processing Time

Get workflow results

​Endpoint

​Authentication

​Request Body

​Fields

​Workflow Runtime Channel

Workflow Runtime Channels

​Google Drive Source URLs

​Override Behavior

Node Config Overrides

​Response

​Processing Time

Get workflow results

Endpoint

Authentication

Request Body

Fields

Workflow Runtime Channel

Google Drive Source URLs

Override Behavior

Response

Processing Time