← All guides

Automation integrations

Written by the VidWords Team · · Updated · Report a correction

Transcripts are most useful inside a pipeline — summarize new uploads to Slack, archive a channel to Notion, or feed a vector database.

The 30-second version

  1. n8n — import the VidWords workflow template and set the Authorization: Basic <your-api-token> header on its HTTP Request node.
  2. Make.com — import the blueprint, paste your token into the HTTP module, and map results[].text to whatever comes next.
  3. Anything else — POST https://vidwords.com/api/transcripts with a JSON body of {"ids": […], "lang": "en"}. Zapier webhooks, GitHub Actions, and cron jobs all qualify.
  4. Limits to design around: up to 50 video ids per request, 5 requests every 10 seconds per token, and 1 credit per transcript actually delivered (failed lookups are free).
  5. Your API token is on your profile page and is included on every plan, Free included — but you must confirm your email before the first call will work.

Before you build: the token, and the one gotcha

Every integration on this page authenticates identically — an Authorization: Basic <your-api-token> header on each request, alongside Content-Type: application/json. There's no OAuth dance and no Google API key involved: the token on your profile page is the whole of it, and one is included on every plan, Free included.

The gotcha worth knowing before you spend an hour debugging a scenario: confirm your email first. Until you click the verification link, every API call returns 403 with {"error":"email_unverified"}. It's the most common first-call failure on a new account, and from inside n8n or Make it looks indistinguishable from a bad token.

n8n

  1. Download the VidWords n8n workflow template.
  2. In n8n: Workflows → Import from file.
  3. Open the HTTP Request node and set the Authorization: Basic <your-api-token> header (token on your profile page).
  4. Trigger it on a schedule, a webhook, or an RSS feed of a channel's uploads.

The template is deliberately minimal: a manual trigger, a Set node holding a videoIds array, and an HTTP Request node that POSTs them to /api/transcripts with lang set to en. Swap the manual trigger for whatever should actually start the run, and either edit the array or wire it to an upstream node — everything downstream reads from the same response.

Make.com

  1. Download the Make blueprint.
  2. In Make: Create a new scenario → ⋯ → Import blueprint.
  3. Fill in your API token in the HTTP module, then map the results[].text field to any downstream app — Google Docs, Notion, Slack, Airtable.

The blueprint is a single HTTP module pre-configured for a raw JSON POST to /api/transcripts, with response parsing already switched on so the result arrives as structured data rather than a string you'd have to decode. Replace YOUR_API_TOKEN, edit the ids array, then build your trigger and downstream modules around it.

Plain REST (everything else)

Anything that can issue an HTTP POST can use the API directly — Zapier webhooks, GitHub Actions, cron jobs:

curl -X POST https://vidwords.com/api/transcripts \
  -H "Authorization: Basic YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["jNQXAC9IVRw", "dQw4w9WgXcQ"], "lang": "en"}'

Up to 50 video ids per call, 5 requests / 10 seconds. Full reference with Node and Python examples in the API docs, machine-readable spec at /openapi.json.

What comes back

One entry per video, in the order you sent them, under a top-level results array. Direct API calls also get a creditsRemaining number, so a workflow can watch its own budget:

{
  "results": [
    {
      "id": "jNQXAC9IVRw",
      "title": "…",
      "author": "…",
      "language": "English",
      "languageCode": "en",
      "isGenerated": false,
      "text": "full transcript as one string…",
      "segments": [{ "text": "…", "start": 1.36, "duration": 1.68 }]
    }
  ],
  "creditsRemaining": 23
}

Two fields do most of the work. text is the whole transcript as one plain string — that's what you map into a document, a Slack message, or an LLM prompt. segments keeps every caption cue with its start and duration in seconds, which is what you want for generating subtitle files, jump-to-timestamp links, or a chunked search index. isGenerated tells you whether you're holding YouTube's automatic captions or a human-authored track — useful when a pipeline should flag or skip the lower-confidence text.

Handling failures without stopping the run

A bad video doesn't fail the request. It comes back as an ordinary entry carrying an error field instead of segments, so one dead link can't sink a batch of fifty. Branch on the code:

Request-level problems arrive as HTTP status codes rather than per-video entries: 400 bad_request for a malformed body or too many ids, 401 unauthorized for a missing or invalid token, 402 insufficient_credits, 403 plan_required when an endpoint needs a higher plan, and 429 rate_limited.

Rate limits, batching, and credits

Starting from a channel instead of a list of ids

Most real pipelines start from a creator, not a hand-maintained array. POST /api/channels (Starter and up — 5 channels per request on Starter, 50 on Pro and Advanced) accepts @handles, channel URLs, or UC… ids and returns the channelId, the channel title, and the upload list newest first, capped at 500 videos with truncated: true when that cap was hit. Listing is free; you only spend credits once you post those video ids to /api/transcripts. The browser-and-API walkthrough is in bulk transcripts for a whole channel or playlist.

Recipe ideas

Read the API docs →