Make one real request the main character: a single call, followed end to end, from the moment it is formed to the moment its response lands somewhere useful. An API has no screens to record, so the diagram becomes your product surface, and it has to obey the same honesty rules a screenshot would.
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. Suppose the API schedules meetings. A booking request arrives carrying two calendar IDs and a time window; the service checks both calendars for conflicts, books the open slot, and fires a webhook to confirm it. That one call carries every example below.
The request is the story
A request is formed, sent, processed through named steps, and answered, and then the response gets used for something the viewer cares about. That is a complete story with a protagonist, a journey, and a payoff.
Pick a single real call — real endpoint, real field names, a payload someone could actually send — and carry it through the entire video. For the scheduling API that is one POST to the bookings endpoint, and every value on screen, from the calendar IDs to the confirmed start time, should trace to a real artifact from your live API. Developers are the audience most likely to notice an invented field name, and the least forgiving when they do.
Viewers give the first end-to-end traversal full attention and each repeat much less, so a second request earns its place only when it differs in exactly the dimension you are teaching. The same booking against a slot that is already taken, coming back as a conflict with alternatives, teaches conflict handling. A third "look, it works again" run teaches nothing and costs attention you do not get back.
The diagram is a product surface, so treat it like one
We learned each of these rules from a rejected build.
One set piece, one layout. Build the whole system as a single fixed layout and let every scene be a camera position plus a state change on it. For the scheduling API: five blocks — client, API, availability checker, calendar store, webhook dispatcher — arranged once and never rearranged. Rejected takes in our history improvised geometry per scene and got content cropped; accepted takes defined named camera framings over one fixed layout (camera moves in product videos). A real architecture never rearranges itself, and a viewer who has learned where the calendar store sits should never have to find it again.
Nothing rides a wire except light. The most common API-video mistake is animating the payload itself down the arrow — a JSON pill gliding along a line and parking on a label. That move got scenes rejected twice in our reviews. Data in real systems lives in things: a pulse of light travels the wire, and the value resolves inside the destination, as a response body filling or a row landing in a table.
Labels name; they never explain. A box may say "Availability check." It may not say "Both calendars are queried to find conflicts," because that sentence belongs to the narration. If you can read the whole script off the muted 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, everything else stays neutral. Rainbow diagrams — one color per service, decorative glows — were rejected in our reviews because color that does not mean anything reads as decoration. If you cannot state what a color means, remove it.
Timing carries the causality. Viewers infer cause and effect from timing, not arrows. When the availability checker lights up and the calendar store answers a beat later, the viewer reads consequence without a label; the tuned offset is in what makes a good explainer video. When your API does parallel work, show the fan-out finishing in scrambled order at an even cadence, because that is what real concurrency looks like; uniform lockstep completion is what slideshows look like. The stagger constants are in animation timing and easing.
Code on screen: the rules
Code is the one UI an API actually has.
- Real code, sparingly. Show the request as it would actually be written — real method, real endpoint path, real header names — but only the six lines that matter: the POST line, the auth header, the two calendar IDs, the time window. A full screen of code is a text wall.
- One focal line at a time. When the narration discusses the time window, that line sits at full strength and everything else dims to a third. A full-strength highlighted screen gives no signal about where to look, so the viewer looks everywhere and reads nothing.
- The narration never reads code aloud. No backticks in speech, no "slash vee one slash bookings." The voice says what the line means — "the request names the two calendars to check" — while the picture shows the line itself.
- The response is the payoff, so let it land like one. The confirmed booking coming back is your climax. Push the camera in and let the fields resolve one by one, fast enough to read as a system and slow enough to read at all. A payoff too small to see did not happen.
- Something should accumulate. The best-graded builds in our history all had a surface that visibly fills: a bookings table gaining rows, webhook deliveries stacking in a log. A frame that remembers turns every request into evidence.
Where API videos live changes what they should be
| Placement | Register | The cut |
|---|---|---|
| Docs | Calm, one concept per video | 60–90s: what a webhook is, how conflict resolution works |
| Launch | Excited, end to end | The machine running as a real outcome, intercut with live capture |
| Talk / booth | Muted and looping | Fully legible from timing and state alone, under a minute, seamless loop |
Order docs videos as a curriculum: teach first the concept every other concept is defined in terms of, usually the core resource or the auth model — the full guide is documentation videos. At launch, intercut a real terminal recording for the "watch it go" beat: animate the concept, record the live product. For the booth cut, the muted test stops being a diagnostic and becomes the spec, and the last frame should match the first.
If your API ships alongside SDKs, CLIs, and libraries, the broader-audience version 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.
How much of the video should be code on screen? Show code in roughly two or three scenes of a 90-second video, at the moments the viewer needs the shape of a request or response. The mechanism between them is better shown as a diagram with state and timing.
How long should an API explainer be? Docs videos run 60 to 90 seconds with one concept each; launch videos can stretch to about two minutes if the worked example earns it. The tight shape in our produced work is six to eight scenes at 8 to 12 seconds each.
Can one video cover our whole API? No, because a tour of every endpoint leaves the viewer without a working model of any of them. Cover the core loop — auth, the central resource, one representative call — and let the docs series own the rest.
The fastest way to test any of this is on your own product. Send us the URL and choose from twenty short videos of it.