How to record a narrated video walkthrough of your API docs

#video #api #documentation #devtools

How to Record a Narrated Video Walkthrough of Your API Docs

Written API docs explain the endpoints. A narrated video shows developers what a real request flow looks like — the auth header, the payload, the response shape — in 90 seconds instead of 15 minutes of reading.

The problem: recording that video manually means setting up a screen recorder, narrating live, re-recording when an endpoint changes. Here's how to generate it instead.

The approach

Record your API playground or a live request sequence. Narrate each step. Regenerate on every API version bump.

import fs from 'fs';

const res = await fetch('https://api.pagebolt.dev/v1/video', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAGEBOLT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    steps: [
      { action: 'navigate', url: 'https://yourapi.dev/docs', note: 'Open the API docs' },
      { action: 'click', selector: '#authentication', note: 'Authentication section' },
      { action: 'scroll', direction: 'down', amount: 200, note: 'See the API key header' },
      { action: 'click', selector: '#endpoint-screenshot', note: 'Screenshot endpoint' },
      { action: 'scroll', direction: 'down', amount: 300, note: 'See the request and response' }
    ],
    audioGuide: {
      enabled: true,
      voice: 'nova',
      script: "Here's how to get started with the API. {{1}} Authentication uses an x-api-key header — set it on every request. {{2}} {{3}} The screenshot endpoint takes a URL and returns a PNG. {{4}} {{5}} The response is binary — pipe it directly to a file."
    },
    frame: { enabled: true, style: 'macos' },
    pace: 'slow',
    cursor: { style: 'highlight', persist: true }
  })
});

fs.writeFileSync('docs/api-walkthrough.mp4', Buffer.from(await res.arrayBuffer()));

For API playground walkthroughs

If your docs have an interactive playground (Swagger UI, Redoc, custom), record a live request:

const steps = [
  { action: 'navigate', url: 'https://yourapi.dev/playground', note: 'Open the playground' },
  { action: 'fill', selector: '#api-key-input', value: 'demo_key_here', note: 'Enter your API key' },
  { action: 'fill', selector: '#url-param', value: 'https://example.com', note: 'Enter a URL to screenshot' },
  { action: 'click', selector: '#execute', note: 'Execute the request' },
  { action: 'wait_for', selector: '.response-image', note: 'See the PNG response' }
];

Regenerate on API changes

Add to your docs deployment pipeline:

// scripts/record-api-walkthrough.js
const version = process.env.API_VERSION || 'v1';
const docsUrl = process.env.DOCS_URL || 'https://yourapi.dev/docs';

const steps = JSON.parse(
  fs.readFileSync(`docs-videos/${version}/steps.json`, 'utf-8')
);
const narration = fs.readFileSync(`docs-videos/${version}/narration.txt`, 'utf-8');

const res = await fetch('https://api.pagebolt.dev/v1/video', {
  method: 'POST',
  headers: { 'x-api-key': process.env.PAGEBOLT_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    steps,
    variables: { docs_url: docsUrl },
    audioGuide: { enabled: true, voice: 'nova', script: narration },
    frame: { enabled: true, style: 'macos' },
    pace: 'slow'
  })
});

fs.writeFileSync(`docs/api-walkthrough-${version}.mp4`, Buffer.from(await res.arrayBuffer()));

Version the step sequences alongside your API versions. When you ship v2, add a docs-videos/v2/ folder. The v1 walkthrough stays accurate; the v2 walkthrough records against the new endpoints.

Embed in your docs

## Quick start video

<video src="./api-walkthrough.mp4" controls width="100%"></video>

Prefer reading? See the [written quick start guide](#quick-start).