API · Screen Browser

Create projects, record videos and fetch them over a REST API with a bearer token.

Create an API key under Settings → API keys. A key acts for the whole organisation. Send it as Authorization: Bearer sb_live_… to https://rec.screenbrowser.com/api/v1/…. Every answer is JSON, including errors, which carry a message you can show.

From nothing to a video

# 1. the project; login_gate is what only a signed-in user sees (url_contains, text or selector),
#    allow_hosts the other hosts the app's pages call, such as its API or CDN
curl -X POST https://rec.screenbrowser.com/api/v1/projects -H "Authorization: Bearer $SB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "target_url": "https://app.acme.com/login", "login_gate": {"url_contains": "/dashboard"},
       "allow_hosts": ["api.acme.com"]}'

# 2. confirm you may record this app (once per host)
curl -X POST https://rec.screenbrowser.com/api/v1/projects/$PROJECT/attest -H "Authorization: Bearer $SB_KEY" \
  -H "Content-Type: application/json" -d '{"attestation_type": "self_owned"}'

# 3. the demo user's credentials, encrypted at rest and never returned
curl -X PUT https://rec.screenbrowser.com/api/v1/projects/$PROJECT/vars \
  -H "Authorization: Bearer $SB_KEY" -H "Content-Type: application/json" \
  -d '{"vars": [{"name": "USERNAME", "value": "[email protected]"}, {"name": "PASSWORD", "value": "…"}]}'

# 4. the sign-in guide, then the walkthrough
curl -X PUT https://rec.screenbrowser.com/api/v1/projects/$PROJECT/guides/auth \
  -H "Authorization: Bearer $SB_KEY" -H "Content-Type: application/json" \
  -d '{"content": "Go to https://app.acme.com/login\nType {USERNAME} into the field labelled \"Email\"\nType {PASSWORD} into the field labelled \"Password\"\nClick the button named \"Sign in\""}'
curl -X PUT https://rec.screenbrowser.com/api/v1/projects/$PROJECT/guides/main \
  -H "Authorization: Bearer $SB_KEY" -H "Content-Type: application/json" \
  -d '{"content": "Go to https://app.acme.com\nClick the button named \"New project\"", "name": "Create a project"}'

# 5. record
curl -X POST https://rec.screenbrowser.com/api/v1/runs -H "Authorization: Bearer $SB_KEY" \
  -H "Content-Type: application/json" -d '{"project_id": "'$PROJECT'"}'

# 6. poll every 15–30 seconds until is_terminal, then fetch the video
curl https://rec.screenbrowser.com/api/v1/runs/$RUN -H "Authorization: Bearer $SB_KEY"
curl -L -o video.mp4 https://rec.screenbrowser.com/api/v1/runs/$RUN/artifacts/final_mp4 -H "Authorization: Bearer $SB_KEY"

A run's phase is Queued, Preparing, Recording or Finishing while it runs, then Completed, Failed, Canceled or Paused; is_terminal tells you when to stop polling. A failed run has an error with a message and hints. warnings lists what is worth checking in a finished video, such as a guide line the recorder matched to a differently worded button. Video links are signed and valid for fifteen minutes; fetch the artifact again for a fresh one.

A retry that must not start a second run sends the same X-Idempotency-Key header on POST /api/v1/runs.

Several videos on one project

PUT /api/v1/projects/{project}/guides/main with a name the project has not used yet starts a new guide; with guide_id it saves a new version of that guide. GET /api/v1/projects/{project}/guides lists them, and POST /api/v1/runs takes a guide_id; without one it records the newest. config_overrides on a run sets voice, language, device, frame and backdrop; GET /api/v1/voices lists the voices and what they cost. GET /api/v1/runs lists runs, newest first, with optional project_id and limit.

Also there

Every export next to the video as GET /api/v1/runs/{run}/artifacts/{kind} with gif, chapter_gifs, subtitles_vtt, subtitles_srt or chapters, and webhooks under /api/v1/webhooks (see Exports and webhooks). Cancel, clone and resume a run; a thumbnail per run; the credit balance and transactions; a one-click top-up link; the brand kit and overlay themes; checkout, plan changes and the billing portal; a data export or deletion of the organisation under /api/v1/privacy.

When it says no

Refusals come back as JSON with an error code and a message written for a person:

insufficient_credits: the balance is too low; the answer carries a top_up_url.
variables_missing: the guides use a {VARIABLE} the project does not have yet.
requires_attestation: confirm you may record this app first, with POST /api/v1/projects/{project}/attest.
guide_required: the project is missing its sign-in or main guide; kind says which.
guide_not_found: guide_id is not one of the project's main guides.
concurrent_run_limit: your plan's runs at a time are all busy; start again when one finishes.
free_minutes_used_for_app: this app already had free minutes on another account; recording it needs a plan.
plan_required: top-up packs add to a plan or trial; the answer links to the plans.

Brand, opening and ending

# upload a logo (logo | font | clip); it is processed in the background
curl -X POST https://rec.screenbrowser.com/api/v1/brand-assets -H "Authorization: Bearer $SB_KEY" \
  -F kind=logo -F [email protected]
curl https://rec.screenbrowser.com/api/v1/brand-assets/$ASSET -H "Authorization: Bearer $SB_KEY"   # status: processing | ready | rejected

# the brand kit; keys you leave out are kept
curl -X PUT https://rec.screenbrowser.com/api/v1/brand-kit -H "Authorization: Bearer $SB_KEY" -H "Content-Type: application/json" \
  -d '{"primary_color": "#1c1c0d", "accent_color": "#f9f506", "fg_color": "#1c1c0d", "bg_color": "#fcfcf8",
       "font_family": "Space Grotesk", "border_radius_px": 12, "tone": "light", "font": "space-grotesk",
       "logo_light_asset_id": "'$ASSET'", "cta_text": "Start your free trial", "website": "example.com",
       "bookends": {"opening": {"style": "clean", "seconds": 3}, "ending": {"style": "clean", "seconds": 4}}}'

# a project's own opening and ending (Pro and above)
curl -X PATCH https://rec.screenbrowser.com/api/v1/projects/$PROJECT -H "Authorization: Bearer $SB_KEY" -H "Content-Type: application/json" \
  -d '{"bookends": {"mode": "custom", "opening": {"style": "bold", "seconds": 5}, "ending": {"style": "none"}, "fade": true,
       "narrate_title": true, "title_line": "Here is how to {title}"}}'

A guide's opening title is video_title on PUT /api/v1/projects/{project}/guides/main. See Brand, opening and ending.

The MCP server offers the recording flow as tools for coding agents, plus guide validation and failure reports.