# LiveClass

Server-to-server HTTP API for **LiveClass by BrainCert**
([**liveclass.io**](https://www.liveclass.io/)) — multi-tenant live classrooms,
webinars, cloud recording, breakouts, polls, and social livestreaming.

This is the **customer / integrator API**. You work only with LiveClass
product concepts — sessions, participants, launch links, attendance,
recordings, livestreams — and never touch the underlying media
infrastructure. First-party account features (billing, branding, the
operations console) are **not** part of this API.

## Lifecycle at a glance

1. **Create** a session → get a `sessionId`.
2. **Launch** a participant (LMS) → get a `launchId` + `joinPath`, or
   generate a join for a custom client.
3. The session runs while participants are present; end it with **End**
   or let the plan time-limit close it.
4. After class: pull the **attendance** report, **recordings**, and
   **usage**.

Most LMS integrations only ever call **Create**, **Launch**, and the
reporting endpoints — they embed or redirect to the hosted LiveClass UI
and never handle raw media credentials.

## Authentication

| Audience | Scheme | Header |
|----------|--------|--------|
| LMS / product integration | API key | `X-API-Key: <tenant key>` |
| Customer integration (`/v1/integrations/*`, MCP) | Bearer | `Authorization: Bearer lc_<provider>_<prefix>.<secret>` |
| Guest join (share links) | Invite token | none (token in body) |
| Optional acting user identity | — | `X-Actor-External-User-Id` |

**The customer integration key identifies the account on its own.** The
tenant is resolved server-side from the key's unique prefix — there is no
separate tenant or account id to send, and none is accepted. Only the raw
key's SHA-256 hash is stored, so a leaked key is revoked from the
Integrations page, not recovered. Keys carry scopes (`read`, `write`,
`sessions`, `tags`, …) checked per endpoint.

All traffic must use **HTTPS**.

## Base URL

```
https://api.liveclass.io/v1
```

All paths in this document are relative to that base (e.g.
`POST https://api.liveclass.io/v1/sessions`). Development uses the same
paths under your local API host.

## Regions

Pass an optional `preferredRegionCode` when creating a session to place
the class in a specific datacenter. All participants for that session use
the same assigned region.


Version: 1.0.0

## Servers

Production
```
https://api.liveclass.io/v1
```

Relative (same host or reverse proxy)
```
/v1
```

## Security

### ApiKeyAuth

Product integration API key (LMS)

Type: apiKey
In: header
Name: X-API-Key

### BearerAuth

liveclass.io account session token

Type: http
Scheme: bearer
Bearer Format: opaque

### ParticipantTokenAuth

[object Object]

Type: apiKey
In: header
Name: X-Participant-Token

### IntegrationKeyAuth

[object Object]

Type: http
Scheme: bearer
Bearer Format: lc_<provider>_<prefix>.<secret>

## Download OpenAPI description

 - [LiveClass](https://developers.liveclass.io/_bundle/customer-api.openapi.yaml)

## Sessions

 - [GET /sessions](https://developers.liveclass.io/customer-api.openapi/sessions/listsessions.md)
 - [POST /sessions](https://developers.liveclass.io/customer-api.openapi/sessions/createsession.md)
 - [GET /sessions/{id}](https://developers.liveclass.io/customer-api.openapi/sessions/getsession.md)
 - [PATCH /sessions/{id}](https://developers.liveclass.io/customer-api.openapi/sessions/patchsession.md)
 - [DELETE /sessions/{id}](https://developers.liveclass.io/customer-api.openapi/sessions/deletesession.md)
 - [POST /sessions/{id}/join](https://developers.liveclass.io/customer-api.openapi/sessions/joinsession.md): Issues session access for a participant using `launchId`. **Preferred for LMS:** use `POST /launch` server-side and open the returned `joinPath` on the LiveClass app (hosted UI) — no custom media clie
 - [POST /sessions/{id}/open-join](https://developers.liveclass.io/customer-api.openapi/sessions/openjoinsession.md): Public join for share links (no API key). Role is resolved from the invite token: attendee tokens → attendee; host co-teacher tokens → host (with full media permissions).
 - [POST /sessions/{id}/go-live](https://developers.liveclass.io/customer-api.openapi/sessions/golivesession.md)
 - [POST /sessions/{id}/end](https://developers.liveclass.io/customer-api.openapi/sessions/endsession.md): Marks the session ended and deletes the media room, disconnecting everyone.
 - [GET /sessions/{id}/time-status](https://developers.liveclass.io/customer-api.openapi/sessions/sessiontimestatus.md): Countdown data for in-room warnings. Auth via participant token (X-Participant-Token) or tenant/account auth.
 - [POST /sessions/{id}/extend](https://developers.liveclass.io/customer-api.openapi/sessions/extendsession.md): Pushes the hard stop forward, clamped to the plan's max room duration.
## Launch

 - [POST /launch](https://developers.liveclass.io/customer-api.openapi/launch/postlaunch.md): Creates or attaches a session and returns a `launchId` for embed join. Requires product API key.
 - [GET /launch/{launchId}](https://developers.liveclass.io/customer-api.openapi/launch/getlaunch.md)
 - [POST /sessions/{id}/join](https://developers.liveclass.io/customer-api.openapi/launch/joinsession.md): Issues session access for a participant using `launchId`. **Preferred for LMS:** use `POST /launch` server-side and open the returned `joinPath` on the LiveClass app (hosted UI) — no custom media clie
 - [POST /sessions/{id}/embed-join](https://developers.liveclass.io/customer-api.openapi/launch/joinembeddedsession.md): Used by the hosted embed page after `GET /embed?token=...` serves its origin-bound document. The short-lived embed token is sent in the request body; the reusable invite token and account/API keys mus
 - [GET /sessions/{id}/join-info](https://developers.liveclass.io/customer-api.openapi/launch/getsessionjoininfo.md): Returns the session title and whether the join screen must collect an email or room password. This operation does not return an invite token.
## Participants

 - [GET /sessions/{id}/participants](https://developers.liveclass.io/customer-api.openapi/participants/listparticipants.md)
 - [DELETE /sessions/{id}/participants/{participantId}](https://developers.liveclass.io/customer-api.openapi/participants/removeparticipant.md)
 - [PATCH /sessions/{id}/participants/{participantId}/role](https://developers.liveclass.io/customer-api.openapi/participants/patchparticipantrole.md)
 - [GET /sessions/{id}/participants/{participantId}/permissions](https://developers.liveclass.io/customer-api.openapi/participants/getparticipantpermissions.md)
 - [PATCH /sessions/{id}/participants/{participantId}/permissions](https://developers.liveclass.io/customer-api.openapi/participants/patchparticipantpermissions.md)
 - [GET /sessions/{id}/hands](https://developers.liveclass.io/customer-api.openapi/participants/listraisedhands.md)
 - [POST /sessions/{id}/hands/raise](https://developers.liveclass.io/customer-api.openapi/participants/raisehand.md)
 - [POST /sessions/{id}/hands/lower](https://developers.liveclass.io/customer-api.openapi/participants/lowerhand.md)
## Attendance

 - [GET /sessions/{id}/attendance](https://developers.liveclass.io/customer-api.openapi/attendance/getsessionattendance.md): Per-participant join/leave intervals and totals for LMS gradebooks and post-class attendance reports. Available during or after the session.
 - [GET /sessions/{id}/usage](https://developers.liveclass.io/customer-api.openapi/attendance/getsessionusage.md)
## Attendance Verification

 - [GET /sessions/{id}/attendance/report](https://developers.liveclass.io/customer-api.openapi/attendance-verification/getattendanceverificationreport.md): Per-attendee seat time, presence-check tallies, and whether each attendee met the session's attendance policy. Returns the **frozen** record once the session has ended (`finalized: true`); before that
 - [GET /sessions/{id}/attendance/report.csv](https://developers.liveclass.io/customer-api.openapi/attendance-verification/getattendanceverificationreportcsv.md): The same report as a CSV download, for gradebooks and auditors. Cells beginning `=`, `+`, `-` or `@` are prefixed with an apostrophe so spreadsheet software cannot interpret an attendee's name as a fo
 - [GET /sessions/{id}/attendance/report.pdf](https://developers.liveclass.io/customer-api.openapi/attendance-verification/getattendanceverificationreportpdf.md): The audit document: session facts, the policy and its requirements, the per-attendee table, and an explicit statement of what the report does and does not assert.
 - [GET /sessions/{id}/attendance/checks](https://developers.liveclass.io/customer-api.openapi/attendance-verification/listpresencechecks.md): Every presence check issued for the session, with live response tallies. Host or moderator only.
 - [POST /sessions/{id}/attendance/checks](https://developers.liveclass.io/customer-api.openapi/attendance-verification/issuepresencecheck.md): Fires a presence check immediately, alongside the policy's randomized schedule. The code and deadline are generated server-side and pushed to connected attendees over the session data channel. The ses
 - [GET /sessions/{id}/attendance/checks/current](https://developers.liveclass.io/customer-api.openapi/attendance-verification/getcurrentpresencecheck.md): The presence check currently awaiting a response, for the calling participant. Lets a client that reloaded or joined mid-check recover a prompt it would otherwise have missed — the realtime broadcast
 - [POST /sessions/{id}/attendance/checks/{checkId}/respond](https://developers.liveclass.io/customer-api.openapi/attendance-verification/respondtopresencecheck.md): Records the calling participant's response. **All validation is server-side**: the submitted answer is compared to the stored one and anything arriving after the deadline is rejected, so a tampered cl
 - [GET /sessions/{id}/attendance/timeline/{participantId}](https://developers.liveclass.io/customer-api.openapi/attendance-verification/getverificationtimeline.md): Chronological joins, leaves, and presence-check outcomes for a single attendee — the per-person audit trail behind their seat time.
 - [GET /integrations/sessions/{sessionId}/attendance](https://developers.liveclass.io/customer-api.openapi/attendance-verification/getintegrationattendance.md): The integration-API handoff. Returns the attendance evidence — seat time, presence-check tallies, and whether each attendee met the configured policy — and leaves the certification decision to you. Ch
 - [GET /integrations/attendance/policies](https://developers.liveclass.io/customer-api.openapi/attendance-verification/listintegrationattendancepolicies.md): The reusable attendance policies configured for the account, so an external system can show or reconcile the rules a session was measured against. Requires the `read` scope.
## Polls

 - [GET /sessions/{id}/polls](https://developers.liveclass.io/customer-api.openapi/polls/listpolls.md)
 - [POST /sessions/{id}/polls](https://developers.liveclass.io/customer-api.openapi/polls/createpoll.md)
 - [POST /sessions/{id}/polls/{pollId}/publish](https://developers.liveclass.io/customer-api.openapi/polls/publishpoll.md)
 - [POST /sessions/{id}/polls/{pollId}/end](https://developers.liveclass.io/customer-api.openapi/polls/endpoll.md)
 - [POST /sessions/{id}/polls/{pollId}/vote](https://developers.liveclass.io/customer-api.openapi/polls/votepoll.md)
## Breakouts

 - [GET /sessions/{id}/breakouts](https://developers.liveclass.io/customer-api.openapi/breakouts/listbreakouts.md)
 - [POST /sessions/{id}/breakouts](https://developers.liveclass.io/customer-api.openapi/breakouts/createbreakout.md)
 - [POST /sessions/{id}/breakouts/open](https://developers.liveclass.io/customer-api.openapi/breakouts/openbreakouts.md)
 - [POST /sessions/{id}/breakouts/close](https://developers.liveclass.io/customer-api.openapi/breakouts/closebreakouts.md)
 - [POST /sessions/{id}/breakouts/{breakoutId}/assign](https://developers.liveclass.io/customer-api.openapi/breakouts/assignbreakout.md)
 - [POST /sessions/{id}/breakouts/{breakoutId}/join](https://developers.liveclass.io/customer-api.openapi/breakouts/joinbreakout.md)
## Recordings

 - [GET /sessions/{id}/recordings](https://developers.liveclass.io/customer-api.openapi/recordings/listrecordings.md)
 - [POST /sessions/{id}/recordings/start](https://developers.liveclass.io/customer-api.openapi/recordings/startrecording.md)
 - [POST /sessions/{id}/recordings/stop](https://developers.liveclass.io/customer-api.openapi/recordings/stoprecording.md)
 - [GET /sessions/{id}/recordings/current](https://developers.liveclass.io/customer-api.openapi/recordings/getcurrentrecording.md): Lightweight in-room reconciliation endpoint. Returns only whether an active recording exists for the session's current live run; it does not expose recording history or stored artifacts.
 - [GET /sessions/{id}/recordings/{recordingId}/download-url](https://developers.liveclass.io/customer-api.openapi/recordings/getrecordingdownloadurl.md)
## Livestream

 - [GET /sessions/{id}/livestream-destinations](https://developers.liveclass.io/customer-api.openapi/livestream/listlivestreamdestinations.md)
 - [POST /sessions/{id}/livestream-destinations](https://developers.liveclass.io/customer-api.openapi/livestream/createlivestreamdestination.md)
 - [POST /sessions/{id}/livestream/start](https://developers.liveclass.io/customer-api.openapi/livestream/startlivestream.md): Currently one active destination per session.
 - [POST /sessions/{id}/livestream/stop](https://developers.liveclass.io/customer-api.openapi/livestream/stoplivestream.md)
## Ingress

 - [GET /sessions/{id}/ingress](https://developers.liveclass.io/customer-api.openapi/ingress/listingress.md)
 - [POST /sessions/{id}/ingress](https://developers.liveclass.io/customer-api.openapi/ingress/createingress.md)
## Documents

 - [GET /sessions/{id}/documents](https://developers.liveclass.io/customer-api.openapi/documents/listdocuments.md)
 - [POST /sessions/{id}/documents/init-upload](https://developers.liveclass.io/customer-api.openapi/documents/initdocumentupload.md)
## Integrations

 - [GET /integrations/me](https://developers.liveclass.io/customer-api.openapi/integrations/getintegrationidentity.md): Resolves the tenant and scopes attached to the presented customer integration key.
 - [GET /integrations/sessions](https://developers.liveclass.io/customer-api.openapi/integrations/listintegrationsessions.md)
 - [POST /integrations/sessions](https://developers.liveclass.io/customer-api.openapi/integrations/createintegrationsession.md): Requires the `sessions` scope, or the `write` scope as a fallback.
 - [GET /integrations/events](https://developers.liveclass.io/customer-api.openapi/integrations/listintegrationevents.md): Requires the `read` scope. Use `since` to continue polling from a timestamp.
 - [GET /integrations/mcp](https://developers.liveclass.io/customer-api.openapi/integrations/getmcpeventstream.md): This stateless MCP endpoint only accepts POST. GET returns 405 with `Allow: POST` because it does not provide a standalone server-sent event stream.
 - [POST /integrations/mcp](https://developers.liveclass.io/customer-api.openapi/integrations/postmcpmessage.md): Streamable HTTP request/response endpoint authenticated with an integration key as a Bearer token. Supports `initialize`, `ping`, `tools/list`, and `tools/call`; tool scopes are checked per call. Noti