Start a session for an embed

POST /v1/embed-sessions

Your server calls this when an embed on your page asks for a token, and returns the id, token and expiresAt to the page. Embeds ask for one only when they search, listen to a voice, or open a private playlist; public playlists and readings need none.

Take site from your own configuration, and pass on the instance, scopes and playlists the embed sent once you have checked them. To renew a session, pass the previous session's ID as renew; the new one shares its allowance. The token is shown once. Keep it in memory and never put it in a URL.

Authentication

Send Authorization: Bearer $KEY from your server. Create or rotate keys.

Example request

bash
curl https://play.fellowverse.app/v1/embed-sessions \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"site":"site_FOPKeo5fT6p3","surface":"hosted","instance":"cmp_6f1e0c2a9b","origin":"https://www.example.org","scopes":["search","voice"]}'

Example IDs are placeholders. Use the IDs from your own requests.

Request body

Accepted content types: application/json.

Field Type Required Description and constraints
site string Yes Your site's ID from the developer console.
surface string Yes Always hosted.
instance string Yes The embed's own ID, as it sent it.
origin string Yes Your page's origin, one of the site's allowed origins.
scopes string[] Yes What the embed may do, as it asked. Minimum items: 1.
playlists string[] No Private playlists the embed may open. Each owner must have allowed your site. Maximum items: 50.
subject string No Your own reference for the person, if you want one. It is stored only as a hash. Maximum length: 100.
limits object No Lower ceilings for this session than your site's daily ones.
limits.requests integer No Minimum: 1. Maximum: 50.
limits.audioSeconds integer No Minimum: 0. Maximum: 120.
ttlSeconds integer No How long the token lasts. Minimum: 60. Maximum: 900.
renew string No The previous session's ID, to renew it.

Unknown request fields are not accepted.

Responses

Status Meaning
201 The session.
400 The request could not be used. invalid_request when a field is missing or has the wrong type; bad_request when the audio or a value could not be read.
401 The key is missing, wrong, revoked, or past the end of its grace period after a roll. The code is api_unauthorized, and the reason says which.
403 The account is suspended (api_suspended), or a live key was used on an account that has test keys only (api_live_locked).
404 The upload, job or clip does not exist, or belongs to another account. The codes are api_upload_missing, api_job_missing and api_file_missing. api_off means the request went to an address that does not serve the API; use https://play.fellowverse.app.
429 A per-key limit for the minute was reached (api_rate_limited; the reason names the limit), or a test key used up its account's daily allowance (api_test_quota; the fix says when it resets).
500 Something went wrong on our side. The code is internal.

201: application/json

Field Type Required Description and constraints
id string Yes
token string Yes Shown once. Return it to the embed and keep it nowhere else.
expiresAt string Yes Format: date-time.
budgetId string Yes The allowance this session draws on, shared with its renewals.
site string Yes
surface string Yes Always hosted.
instance string Yes
origin string Yes
scopes string[] Yes

“Required” is relative to the containing object. Optional success results and failure errors depend on the job state.

Errors and limits

JSON errors contain error.code, error.problem, error.reason and error.fix. Handle errors and retries and check test and live limits.

Need the contract? Download OpenAPI. Manage keys and account access in the developer console.

Start here · Guides · API reference