Plum / developers
REST APIShared recorders

Start a session

Start a session on an idle, online shared recorder, with you as host. The recorder adopts it within seconds and records to your account until the scheduled end. Recordings go to your one source for this recorder. A recorder with an open session returns 409 SESSION_ACTIVE; one that has not contacted Optima in the last 90 seconds returns 409 RECORDER_OFFLINE. See [Devices](/docs/devices#shared-recorders).

POST/shared-recorders/{id}/sessions

Authorization

bearerAuth
AuthorizationBearer <token>

Send Authorization: Bearer <token> with one of: an app session access token from /auth/verify-otp or /auth/refresh; an OAuth access token from /oauth/token issued for the API origin (its scopes are its permissions); or a personal access token starting with optima_pat_ (see /docs/personal-access-tokens). Personal access tokens cannot create or list tokens, revoke other tokens, sign out, or delete or restore the account. Content routes need the permission of their layer: audio:read/audio:write for recordings, turns:read/turns:write for turns, contacts, source signals, and events, and insights:read/insights:write for suggestions and session summaries; search and recall need turns:read and insights:read. A request without the permission, or for an account whose layer is turned off, returns 403 FORBIDDEN. See /docs/authentication#scopes.

In: header

Path Parameters

id*string

The recorder's ID, as on its NFC or QR tag.

Length1 <= length <= 200

Header Parameters

X-API-Version?"1"

Send 1 to pin the documented API contract. If omitted, the latest version is selected.

Default"1"

Value in

  • "1"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/shared-recorders/string/sessions" \  -H "X-API-Version: 1" \  -H "Content-Type: application/json" \  -d '{}'
{  "success": true,  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "device_id": "string",    "device_name": "string",    "status": "string",    "host": {      "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",      "display_name": "string"    },    "started_at": "2019-08-24T14:15:22Z",    "expires_at": "2019-08-24T14:15:22Z",    "ended_at": "2019-08-24T14:15:22Z",    "end_reason": "string",    "participants": [      {        "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",        "display_name": "string",        "role": "host",        "joined_at": "2019-08-24T14:15:22Z",        "left_at": "2019-08-24T14:15:22Z"      }    ]  }}

Get a shared recorder GET

Read a shared recorder from its tag: its label, whether it is online, and its open session (active or ending), so you can start a session or join the one in progress. Any signed-in account may read it. An unknown recorder or an account's own device returns 404. See [Devices](/docs/devices#shared-recorders).

List sources GET

Next Page