Developer docs

Everything the studio and the agent skill do goes through this HTTP API — so your scripts, CI, and agents can do it too.

Authentication

Base URL: https://api.pepperly.dev. Every request carries a personal API token in the Authorization header:

Authorization: Bearer pk_...

Create tokens in the studio under Settings → API tokens. The pk_ secret is shown once at creation — only its hash is stored. A token acts as the account that created it (videos, credits, plan), so treat it like a password. Revoking a token in the studio takes effect immediately. For URLs that can’t send headers (video tags, download links), the same credential can ride as a ?token= query parameter — see media.

Tokens deliberately cannot manage tokens: the /api/tokens endpoints require a signed-in studio session, so a leaked token can’t mint more of itself.

Quickstart

# 1. Ask Pepperly's AI to film a walkthrough
curl -X POST https://api.pepperly.dev/jobs \
  -H "Authorization: Bearer $PEPPERLY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "description": "Sign up and create a project"}'
# → 202 {"jobId": "abc123", "status": "queued"}

# 2. Poll until it's done
curl -H "Authorization: Bearer $PEPPERLY_API_TOKEN" https://api.pepperly.dev/jobs/abc123
# → {"state": "completed", "stage": "done", ...}

# 3. Open https://app.pepperly.dev/edit/abc123 to trim, caption, and share

Generate a walkthrough with AI

POST/jobs — returns 202 with a jobId to poll. Pepperly’s engine visits the URL in a real browser, plans the flow from your description, films it with a humanized cursor, and edits in captions. Costs AI credits, charged only on success — failed generations are free.

Field	Type	Notes
`url`	string	Required. Must be a publicly reachable URL (internal/reserved addresses are rejected with `blocked_url`).
`description`	string	What to show, in plain words. Up to 2000 chars. May include run-time credentials for a login step.
`cursorStyle`	string	`arrow` · `pointer` · `dot` · `ring`
`colorScheme`	string	Film the site in `light` or `dark` mode.
`captions`	boolean	Default `true`. Seeds the reel with caption effects (editable after).

One AI generation runs per account at a time — a second request returns 409 generation_in_progress.

POST/jobs/sample — same body (url, description): one free watermarked sample per account, ever. Returns 402 sample_used after that.

Upload a recording

POST/jobs/import — multipart upload of your own screen recording; it becomes an editable Pepperly video. Free and unmetered, but requires an active plan or trial (402 plan_required otherwise).

Form field: video — mp4, mov, or webm, up to 600 MB.
Query params: ?title=My%20demo, ?aiCaptions=0 to skip AI captions.

curl -X POST "https://api.pepperly.dev/jobs/import?title=Q3%20release%20demo" \
  -H "Authorization: Bearer $PEPPERLY_API_TOKEN" \
  -F "video=@demo.mp4"
# → 202 {"jobId": "...", "status": "queued"}

Poll a job

GET/jobs/:id — the processing status of any job:

{
  "jobId": "abc123",
  "state": "active",        // queue state; poll until "completed" or "failed"
  "stage": "filming",       // human-readable pipeline stage
  "kind": "walkthrough",    // "walkthrough" | "import" | "sample" | ...
  "pct": 42,                // progress 0–100 where the stage reports it
  "result": { ... },        // present when state = "completed"
  "error": "..."            // present when state = "failed"
}

Poll every few seconds. AI generations typically take a few minutes; imports less.

List & delete

GET/jobs — every video on the account, newest first: {"reels": [{id, title, url, durationSec, scenes, updatedAt, hasWalkthrough}]}

DELETE/jobs/:id — permanently removes the video, its storage artifacts, and its share analytics. Irreversible.

POST/jobs/:id/share — enable (or update) the public share link. Body options: gate (none · email for lead capture · password), password, ctaLabel / ctaUrl for a call-to-action. Returns the settings including the share token; the public page lives at https://app.pepperly.dev/s/<token>.

GET/jobs/:id/share — current share settings. DELETE/jobs/:id/share — disable the link (re-enabling mints a new URL).

GET/jobs/:id/analytics — viewer engagement for the share link: views, watch-through, drop-off buckets, CTA clicks, and captured leads (depth depends on plan).

Download media

GET/videos/:id/master.mp4 — streams the finished MP4 (HTTP Range supported, so it seeks). Because media URLs are often used where headers can’t be set, the token may ride as a query parameter:

curl -L -o walkthrough.mp4 \
  "https://api.pepperly.dev/videos/abc123/master.mp4?token=$PEPPERLY_API_TOKEN"

Errors

Errors are JSON: {"error": "<code>", "detail": "..."}.

HTTP	Code	Meaning
400	`invalid_request`	Body failed validation; `detail` says which field.
400	`blocked_url`	The target URL is internal/reserved — only public URLs are filmed.
401	`unauthorized`	Missing, invalid, or revoked token.
403	`forbidden`	The video belongs to another account.
402	`insufficient_credits`	AI generation needs more credits; response includes `needed` and `balance`.
402	`plan_required`	Uploads need an active plan or trial.
402	`sample_used`	The one free sample was already used.
409	`generation_in_progress`	Another AI generation is running on this account.
404	`not_found`	No such job/video.

Limits

One in-flight AI generation per account.
Uploads up to 600 MB (mp4 / mov / webm).
Up to 10 API tokens per account.
AI generations are metered by your plan’s monthly credits; uploads are unmetered.

Self-hosting

Pepperly is open source (AGPL-3.0) at github.com/yapepperly. Everything above works identically against a self-hosted stack — swap the base URL. The agent skill honors PEPPERLY_API_BASE / PEPPERLY_APP_BASE for the same purpose.