How do you make an explainer video for an API?

Make one real request the main character: a single call, followed end to end, from the moment it's formed to the moment its response lands somewhere useful. An API has no screens to record, so the diagram becomes your product surface — which means it has to obey the same honesty rules a screenshot would.

That second sentence is the whole difficulty. Most product videos can fall back on the UI when the explanation gets hard. An API video is diagrams and code all the way down, and diagrams are where explainer videos most often go wrong: floating boxes, arrows that mean nothing, payloads gliding around like decorations. Across sixty-odd produced explainers and the review notes behind them, we've accumulated specific rules for exactly this situation.

The request is the story

An API explainer has a natural narrative that most of them ignore: the request/response cycle. A request is formed, sent, processed through named steps, and answered — and the response gets used for something the viewer cares about. That's a complete story with a protagonist, a journey, and a payoff, and it maps directly onto the causal-chain structure every good explainer needs: orient from what the viewer knows, zoom from macro to micro, then work one example through mechanistically.

The discipline is one example. Pick a single real call — real endpoint, real field names, a payload someone could actually send — and carry it through the entire video. Every value on screen should trace to a real artifact from your live API; in our production process the rule is absolute: no source, no value. Developers are the audience most likely to notice an invented field name, and the least forgiving when they do.

One worked example also enforces run economy. Viewers give the first end-to-end traversal their full attention and each repeat much less, so use the minimum number of runs that proves the point. A second request earns its place only when it differs in exactly the dimension you're teaching — the same call with an expired key returning a 401 teaches auth; a third and fourth "look, it works again" run teaches nothing and costs attention you don't get back.

The diagram is a product surface — treat it like one

When there's no UI, the diagram carries the burden of looking like your product rather than like clip art. The rules below each trace to a real rejection in our graded corpus.

One set piece, one layout. Build the whole system — client, gateway, services, store, whatever your architecture is — as a single fixed layout, and let every scene be a camera position plus a state change on that layout. When the same topics were built twice in our corpus, the rejected takes improvised geometry per scene and got content cropped or cut in half; the accepted takes defined 35–59 named camera framings over one fixed layout and moved a single continuous camera between them. For an API video this also carries meaning: the architecture never rearranges itself, so the viewer's mental map survives every cut.

Nothing rides a wire except light. The most common API-video mistake is animating the payload itself down the arrow — a little JSON pill gliding along a line and parking on a label. That exact move killed scenes twice in our review history. Data in real systems lives in things: a pulse of light travels the wire, and the value resolves inside the destination — a response body filling, a row landing in a table, a field updating. If the wire is shorter than the payload, the payload doesn't belong on it.

Labels name; they never explain. A box may say "Rate limiter." It may not say "Requests are throttled to protect downstream services" — that sentence belongs to the narration. If you can watch the video muted and read the whole script off the screen, the screen and the voice are competing for the same job and both lose.

One accent color, used semantically. In-flight is your accent, success is green, failure is red, and everything else stays neutral. Rainbow diagrams — one color per service, decorative glows — were rejected in our corpus with the note that color which doesn't mean anything reads as decoration. A color you can't define is a color you should delete.

Timing carries the causality. Viewers infer cause and effect from timing, not from arrows. Our tuned constant: effect follows cause by 0.7 seconds — simultaneous reads as coincidence, a beat apart reads as consequence. And when your API does parallel work, show the fan-out finishing in scrambled order at an even cadence; that's what real concurrency looks like, and uniform lockstep completion is what slideshows look like. The full timing vocabulary is in animation timing and easing.

Code on screen: the rules

Code is the one UI an API actually has, so it deserves the same discipline as any product surface.

1. Real code, sparingly. Show the request as it would actually be written — real method, real endpoint path, real header names. But a full screen of code is a text wall, and the text-wall video is the most common cheap-video failure mode there is. Show the 4–8 lines that matter for this scene, and cut the boilerplate.
2. One focal line at a time. When the narration discusses the auth header, that line is at full strength and everything else dims to about a third. Attention is a budget; a syntax-highlighted wall spends it randomly.
3. The narration never reads code aloud. No backticks in speech, no "slash vee one slash users." The voice says what the line means — "the request carries your key in a header" — while the picture shows the line itself. Counting works the same way: the picture shows the three retries; the voice says why there are retries at all.
4. The response is the payoff — let it land like one. The moment the JSON comes back is your climax, so stage it at frame scale: push the camera in and let the fields resolve one by one at a machine cadence (in our timing constants, about 0.14 seconds per item — fast enough to read as a system, slow enough to read at all). A rule from our graded work applies directly: a payoff smaller than about 1/40 of the frame didn't happen.
5. Something should accumulate. The best-graded builds in our corpus all had a surface that visibly fills as the video progresses — for an API, that's an event log growing entry by entry, webhook deliveries stacking up, a table populating from responses. A video that resets after every beat teaches nothing cumulative; a frame that remembers turns every request into evidence.

Where API videos live changes what they should be

An API video rarely lives on a landing page alone. The three real homes ask for different videos, and mixing their jobs is how a video ends up doing none of them.

In the docs. Calm, diagrammatic, one concept per video, 60–90 seconds: what a webhook is, how pagination works, what the rate limiter does. Order them as a curriculum — teach the gravity-center concept first, the one every other concept is defined in terms of (usually the core resource or the auth model), and let each video own exactly one idea and defer its neighbors. Each video should hold to one idea per scene internally too. There's a full guide on documentation videos.

At launch. Here the video excites: the machine running end to end, framed as a real outcome — one request fanning into parallel work, results landing, totals climbing. Same honesty rules, higher energy, and it's fine to intercut a real terminal recording of the actual call for the "watch it go" beat. Our routing rule: animate the concept, record the live product.

Behind a conference talk or on a booth screen. This video plays muted, looping, while someone talks over it or nobody talks at all. The muted test stops being a diagnostic and becomes the spec: the request/response story must be fully legible from timing, motion, and state alone. Loop it seamlessly — last frame matching first — and keep it under a minute.

If your API ships alongside SDKs, CLIs, and libraries, the broader-audience version of this guide is devtools explainer videos.

FAQ

Should we show real code or pseudocode? Real code, from your real docs, in one language. Pseudocode signals that the details are negotiable, and details are exactly what a developer audience is evaluating. If you support many languages, pick the one most of your audience writes and say the others exist; nobody needs a montage of six syntaxes making the same call.

How much of the video should be code on screen? Less than feels natural — in our experience, code should appear at the moments the viewer needs to see the shape of a request or response, roughly two or three scenes of a 90-second video. The mechanism between request and response is better shown as a diagram with state and timing than as more code.

How long should an API explainer be? Docs videos: 60–90 seconds, one concept each. Launch videos: up to about two minutes if the worked example earns it. In our corpus the tight shape is 6–8 scenes at 8–12 seconds each, one idea per scene, and length past that point trades viewers for thoroughness at a bad rate.

Can one video cover our whole API? No, and it shouldn't try. A video that tours every endpoint teaches none of them. Cover the core loop — auth, the central resource, one representative call — and let the docs series own the rest, one concept at a time.

When you're ready to see it done with your actual API, send us the docs URL and pick from twenty rendered directions.