← 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 Cloud Request 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 report cloudRequestsRemaining and aiUnitsRemaining, so a workflow can watch both balances. creditsRemaining remains in the response for compatibility with older clients:

{
  "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 }]
    }
  ],
  "cloudRequestsRemaining": 23,
  "aiUnitsRemaining": 200,
  "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 usage

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 accepts @handles, channel URLs, or UC… ids; the plan caps are 10 channels per request on Starter, 100 on Pro and 500 on Team. It returns the channelId, channel title and upload list. Listing each channel uses one Cloud Request; retrieving each video's transcript uses another Cloud Request. The browser-and-API walkthrough is in bulk transcripts for a whole channel or playlist.

Recipe ideas

Read the API docs →