Skip to Content
APIOverview

API

Create capture requests and recording sessions, get told when a recording lands, and download the original file with a record of how it was made.

The API is included with Studio and Platform. Keys are created at capturly.app/account/api-keys .

The thing to understand first

Capture is local, so it is asynchronous. When a session ends the media is still on someone’s laptop, and it may never arrive. That is the shape of the API, not an edge case to code around.

Three consequences:

  • Tracks arrive independently, over minutes to hours. A recording with two of four tracks present is a correct response, not a partial failure.
  • A take can strand when a client vanishes mid-upload. That is a real state with a recovery path, not an error.
  • Polling has no bounded answer. Subscribe to webhooks rather than asking repeatedly whether a recording is ready.

Authentication

A bearer token on every request:

curl https://capturly.app/api/v1/recordings \ -H "Authorization: Bearer cap_live_..."

Keys are organization-scoped and shown once at creation. They survive the member who created them leaving, because they belong to the organization rather than to a person.

Cookies are not accepted. A browser session here would make every endpoint reachable from any page a user has open.

Live and test keys

A cap_test_ key authenticates and reads, but is refused anything with an effect outside Capturly that cannot be taken back: minting a download URL, mailing a real person, or opening a session that draws on your allowance. Reads are unrestricted, so a test key exercises every response shape.

Test keys have no fixture data behind them. They read your organization, which for a new one is empty.

Scopes

A key grants exactly what you check, and nothing implies anything else — reading a recording is not permission to download it.

ScopeGrants
recordings:readList recordings and read capture manifests
recordings:downloadMint short-lived download URLs
usage:readRead capture usage
capture_requests:readList capture requests, rosters and submitted takes; with recordings:read, also who accepted the consent on a recording’s tracks
capture_requests:writeCreate, edit and close requests; add contacts
sessions:readList sessions and see who joined
sessions:writeCreate sessions, mint invites, end them

Errors

StatusMeaning
401 unauthorizedNo key, or one that does not authenticate. Identical for unknown, revoked and expired keys.
403 insufficient_scopeThe key is missing a scope. The response names it.
403 test_mode_scopeA test key attempted something live-only.
403 plan_inactiveThe organization’s plan no longer includes API access.
403 upgrade_requiredThe plan does not include this feature. The response names the plan that does.
402 capture_allowance_reachedThe capture allowance is spent. Recording continues; new capture requests wait.
409 organization_pausedThe organization’s plan has lapsed, so respondent links would not resolve.
409 capture_request_closedThe capture request is closed and takes no more contacts or takes.
429 contact_capThe roster is at its ceiling. The response carries the cap and the current count.
429 rate_limitedOver the per-key budget above. Worth retrying after a pause.
400 invalid_inputThe body failed validation. The response names the field.
400 invalid_cursorA pagination cursor that resolves to nothing.
404 not_foundNo such object, or one belonging to another organization.

The 401 is deliberately uniform. Distinguishing a revoked key from an unknown one would let a caller probe which keys exist.

Pagination

List endpoints are cursor-paginated, newest first. The one exception is a capture request’s contacts, which are listed oldest first, in the order you added them.

curl "https://capturly.app/api/v1/recordings?limit=25&cursor=cm4x2k9p50000a8b7c6d5e4f3" \ -H "Authorization: Bearer cap_live_..."

IDs are opaque strings with no type prefix. Store them as given and don’t parse them.

nextCursor is null on the last page, never absent, so you can branch on the field without distinguishing “missing” from “no more”.

A cursor that no longer resolves returns 400 invalid_cursor rather than an empty page. To a syncing client an empty page reads as “walk complete”, which would turn an aged-out cursor into silent data loss.

Rate limits

Per key, per minute:

RequestsBudget
Reads600
Writes — anything that creates, edits, closes or deletes60
Download-URL minting, which signs a URL each time60

Limits key on the credential rather than the caller’s address, so a leaked key stays bounded across every host running it. Over budget answers 429 rate_limited.

Last updated on