Coding agents can wire an API into your app in minutes, but only as well as the context you give them. Left alone, an agent guesses field names from similar APIs, verifies webhooks against re-serialized JSON, or calls the API from the browser with your secret key. The fix is not to type more code yourself. Give the agent the exact contract up front, keep it in the repo, and review the few places where integrations usually break.
This post walks through that process for a video API, using PitchTwin with Claude Code or Cursor. The approach carries over to any async REST API.
What the agent needs to know
An avatar video integration has more moving parts than a typical CRUD API:
- Async jobs.
POST /generationsreturns202withstatus: "queued". The video arrives later. - Webhooks. Results are POSTed to your
webhook_urlwith aPitchTwin-Signature: t=…,v1=…header, wherev1is the hex HMAC-SHA256 of${t}.${raw_body}. Each webhook is delivered once, so pollingGET /generations/:idis the fallback. - Exactly one input. A generation takes exactly one of
text,script(an array of{ text, pause_after_ms }) oraudio({ url, alignment? }). - Expiring links.
video_urlandaudio_urlare signed and expire after 24 hours. - Server-side keys. The
pt_live_…key goes in anAuthorization: Bearerheader from your server only.
Each item is a place where a reasonable guess is wrong. Put them in front of the agent before it writes anything.
Step 1: start from the integration prompt
The PitchTwin dashboard has a Copy prompt button that copies a ready-made integration prompt for coding agents. It points the agent at the docs, names the base URL and auth header, and asks for four pieces:
- A server function that creates an avatar and stores its id.
- A server function that starts a generation with a
webhook_url. - A webhook route that verifies the
PitchTwin-Signatureheader and saves the result. - Error handling for the API's
{ error: { code, message } }shape, especially402 insufficient_tokensand409 avatar_not_ready.
It also tells the agent to follow your project's existing framework and folder structure, and to read the key from a PITCHTWIN_KEY environment variable. Paste it into Claude Code or Cursor as your first message. If you'd rather see raw requests first, the dashboard Playground generates a test video without code and shows the equivalent cURL and Node request.
Step 2: keep the contract in the repo
A prompt lasts one session. Rules files last as long as the repo, so the next change to the integration starts with the same facts.
Claude Code
Claude Code reads project instructions from CLAUDE.md (or .claude/CLAUDE.md) at the start of every session, as described in its memory documentation. Running /init generates a starting file from your codebase, and a CLAUDE.md can pull in other files with @path/to/file imports, so the integration notes can live in their own file:
# CLAUDE.md
@docs/integrations/pitchtwin.md
If your repository already uses AGENTS.md, Claude Code reads it when there is no CLAUDE.md; the same page explains how the two interact.
Cursor
Cursor project rules live in .cursor/rules as .mdc files with frontmatter, according to the Cursor rules docs. globs attaches a rule when matching files are in context, and alwaysApply: true includes it in every chat. Cursor also reads AGENTS.md in the project root and subdirectories.
---
description: PitchTwin avatar video API integration
globs: src/lib/pitchtwin/**,src/app/hooks/**
alwaysApply: false
---
See docs/integrations/pitchtwin.md before changing this code.
The shared notes file
Both tools can then point at one file. Keep it short and specific:
# PitchTwin integration
- Base URL: https://pitchtwin.ai/api/v1
- Auth: `Authorization: Bearer $PITCHTWIN_KEY`. Server only. Never import the
client module from browser code.
- POST /generations takes `avatar_id` and exactly one of `text`, `script`
([{ text, pause_after_ms }]) or `audio` ({ url, alignment? }).
Returns 202 { id, status: "queued" }.
- Results: signed webhook to `webhook_url` (once, no retries) plus a reconciler
that polls GET /generations/:id for jobs still pending.
- Webhook signature: header `PitchTwin-Signature: t=<unix>,v1=<hex>`.
v1 = hex HMAC-SHA256 of `${t}.${raw_body}` with PITCHTWIN_WEBHOOK_SECRET.
Verify on the raw bytes, constant-time compare, 5-minute timestamp window.
- `video_url` expires after 24 h. Copy the MP4 to our bucket; store the key,
not the URL.
- Errors are { error: { code, message } }. Handle 402 insufficient_tokens and
409 avatar_not_ready explicitly.
Step 3: ask for a plan, then small diffs
Before the agent edits files, ask it to describe the plan: which files it will add, where the webhook route goes in your router, how it gets the raw body in your framework, and where job state is stored. Fixing a wrong plan takes one message. Fixing a wrong 400-line diff takes much longer.
Then let it work in pieces you can review: the API client, the job table migration, the webhook route, the reconciler. Each piece is small enough to read in full.
Step 4: review the parts agents get wrong
Generated integration code usually looks right. These are the spots worth reading line by line:
| Area | What to check |
|---|---|
| Webhook body | Signature computed on the raw request bytes, not on JSON.stringify(req.body) |
| Compare | crypto.timingSafeEqual (Node) or hmac.compare_digest (Python), with a length check first in Node |
| Timestamp | t checked against the current time, so old requests are rejected |
| Secret | Webhook secret from Dashboard → API keys, not the API key |
| Key exposure | No NEXT_PUBLIC_/VITE_ prefix on PITCHTWIN_KEY; client module never imported into browser code |
| Request body | Exactly one of text, script, audio; voice.speed only between 0.7 and 1.2 |
| Idempotency | A second webhook or a reconciler run for the same generation changes nothing |
| Storage | MP4 copied to your storage; the 24-hour link is not saved as permanent |
| Fallback | Something polls generations that stayed pending |
If any row fails, tell the agent which rule in the notes file it broke. That fixes the code and checks that the notes are clear enough. How to verify HMAC webhook signatures has reference implementations to compare against, and Async video generation with webhooks covers the job table and reconciler.
Step 5: test end to end
Ask the agent to add two tests, then run them yourself:
- Signature test. Sign a sample body locally and POST it to the webhook route. Change one byte and expect a
400.
t=$(date +%s)
body='{"type":"generation.succeeded","data":{"id":"test"}}'
sig=$(printf '%s.%s' "$t" "$body" \
| openssl dgst -sha256 -hmac "$PITCHTWIN_WEBHOOK_SECRET" \
| sed 's/^.* //')
curl -i http://localhost:3000/hooks/pitchtwin \
-H "Content-Type: application/json" \
-H "PitchTwin-Signature: t=$t,v1=$sig" \
--data-raw "$body"
- Real generation. Create an avatar in the dashboard, then trigger a short generation through your new code with a tunnel URL as
webhook_url. Check the job row, the stored MP4 and the logs in Dashboard → Logs.
A short text keeps the test cheap: tokens are charged per second of video, and failed generations are refunded in full automatically.
Where agents help most after launch
Once the contract is in the repo, follow-up work goes faster: adding captions from the words array, switching a feature to audio mode with your own ElevenLabs audio, or adding a script editor with pauses. Each is a small change against a contract the agent can already read. The API surface is small (uploads, avatars, generations, balance), which keeps the notes file short. See the AI avatar API overview for what the API covers.
Try it
Sign up for 60 free tokens with no card, press Copy prompt in the dashboard, and paste it into Claude Code or Cursor. The quickstart shows the three calls the agent will build on.