Lessonspace
Documentation
API Reference

Lessonspace API Reference

The Lessonspace API is RESTful with predictable, resource-oriented URLs. All the endpoints listed live under the /v2/ namespace, https://api.thelessonspace.com/v2/. Unless otherwise stated, expect POST data to be JSON, with the Content-Type set to application/json. All URLs end with a trailing slash.

Organisations

Get Organisation Session List

Fetch the sessions for an organisation. This endpoint is rate limited; too many requests in a small timeframe will be rejected.

GET /organisations/{organisation}/sessions/

Query Parameters
  • search string

    If a UUID, filters to sessions or spaces with a matching slug. Otherwise, filters to sessions or spaces with a partial, case-insensitive match on the name.

  • page integer

    A page number within the paginated result set.

  • include_single_user boolean

    Include sessions with only one user.

  • duration_min integer

    Minimum session duration, in seconds.

  • duration_max integer

    Maximum session duration, in seconds.

  • start_time_after string <date-time>

    Filter to sessions that started after the specified ISO8601 timestamp.

  • start_time_before string <date-time>

    Filter to sessions that started before the specified ISO8601 timestamp.

  • end_time_after string <date-time>

    Filter to sessions that ended after the specified ISO8601 timestamp.

  • end_time_before string <date-time>

    Filter to sessions that ended before the specified ISO8601 timestamp.

  • date_after string <date-time>

    Filter to sessions created after the specified ISO8601 timestamp. Using both `date_before` and `date_after` is the same as using `start_time_after` and `end_time_before`.

  • date_before string <date-time>

    Filter sessions created before the specified ISO8601 timestamp. Using both `date_before` and `date_after` is the same as using `start_time_after` and `end_time_before`.

  • user string

    Filter to sessions that the specified Lessonspace user IDs were present in. Accepts multiple values, delimited by `&`.

  • space string <uuid>

    Filter to sessions linked to the provided space UUID(s). Accepts multiple values, delimited by `&`.

  • launch_id string

    Filter to sessions linked to the space that was identified with the given value when it was created via the Launch endpoint. Performs a full-string, case-sensitive match.

  • in_progress_only boolean

    Filter to sessions that are in progress only.

  • tags string

    JSON object of tags that must match for the session. Leave the tag value blank to check if only the tag key exists. Must be URL-encoded. Performs a full-string, case-insensitive match.

  • user_external_id string

    Filters to sessions that include a user with a matching `user.id` value that was provided via the Launch endpoint. Performs a full-string, case-insensitive match.

  • user_name string

    Filters to sessions that include a user with a matching `user.name` value that was provided via the Launch endpoint. Performs a partial, case-insensitive match.

Responses
  • 200
  • 403

Get Organisation Session

Fetch a session with the given UUID. This endpoint is rate limited; too many requests in a small timeframe will be rejected.

GET /organisations/{organisation}/sessions/{session}/

Responses
  • 200
    id integer
    name string
    space required
    id string

    UUID of the Space

    alias string <slug>
    slug string <slug>required
    name string
    organisation integer required
    is_locked string
    tags string
    url string

    The fully qualified URL of the space. If the current user is authenticated the URL will include the encoded JWT 'user' parameter. If this space is locked and the current user is a student then this will be `None`

    created_at string <date-time>required
    locks array
    Array items:
    id integer
    organisation integer required

    The organisation that this lock belongs to. This is not necessarily always going to be the same organisation as the one that the space is locked to (i.e. in the case of Courses).

    allowed_users string
    allowed_groups array required
    Array items:
    id integer
    name string required
    active boolean
    lock_before string <date-time>

    The (optional) earliest time that the respective space can be opened.

    lock_after string <date-time>

    The (optional) latest time that the respective space can be opened.

    region string
    record_av boolean
    uuid string <uuid>
    playback_url string
    start_time string <date-time>
    end_time string <date-time>
    profiles array required
    Array items:
    user integer required
    name string
    profile_picture
    id integer
    uploaded_at string <date-time>
    admin_verified string
    Enum:"not-verified" | "verified"
    image string <uri>
    email string
    role string
    Enum:"teacher" | "student" | "admin"
    guests array required
    Array items:
    id integer
    uuid string <uuid>required
    session integer required
    billable_seconds integer
    tags string
    recording_access_policy object
  • 403

Update Organisation Session

Update a session's name or recording access policy for the given UUID. This endpoint is rate limited; too many requests in a small timeframe will be rejected.

PATCH /organisations/{organisation}/sessions/{session}/

Request Body Schema
  • name string required

    Name of the session

    recording_access_policy object

    An array that determines who can view the recordings, a combination of `participant`, `admin`, `teacher`, `student` and `public`. If the array is empty, the organisation policy will be used instead.

Responses
  • 200
    name string required

    Name of the session

    recording_access_policy object

    An array that determines who can view the recordings, a combination of `participant`, `admin`, `teacher`, `student` and `public`. If the array is empty, the organisation policy will be used instead.

  • 403

Get Organisation Session Transcript

Fetch the transcription for a given session. The transcription must have been scheduled on the session beforehand. This endpoint is rate limited; too many requests in a small timeframe will be rejected.

GET /organisations/{organisation}/sessions/{session}/transcript/

Path Parameters
  • organisation string required

    The ID identifying this organisation.

  • session string <uuid>required

    The UUID identifying this session.

Query Parameters
  • search string

    A search term.

  • page integer

    A page number within the paginated result set.

Responses
  • 200
  • 403

Get Organisation Space List

GET /organisations/{organisation}/spaces/

Query Parameters
  • session string <uuid>

    The ID(s) of sessions to filter by. Accepts multiple values.

  • date string

    Deprecated. Use `date_before` and `date_after`.

  • tag_key string

    A tag key to match on. Only works if `tag_value` is also set. Performs a full-string, case-insensitive match.

  • tag_value string

    A tag value to match on. Only works if `tag_key` is also set. Performs a full-string, case-insensitive match.

  • user integer

    The Lessonspace IDs of user profiles that have attended sessions which occurred in this space. Accepts multiple values.

  • assigned_to integer

    Filter to spaces which are assigned to these Lessonspace IDs.

  • search string

    A search term.

  • page integer

    A page number within the paginated result set.

  • date_after string <date-time>

    Filter to spaces with sessions that ended after the specified ISO8601 timestamp.

  • date_before string <date-time>

    Filter to spaces with sessions that started before the specified ISO8601 timestamp.

Responses
  • 200
  • 403

Get Organisation User List

GET /organisations/{organisation}/users/

Query Parameters
  • role string
    Enum: "teacher" | "student" | "admin"

    Role(s) to filter by.

  • space string <uuid>

    The ID(s) of Spaces(s) to filter by. Will filter out users who have not attended any sessions which occurred in the spaces listed. Accepts multiple values.

  • session string <uuid>

    The ID(s) of session(s) to filter by. Will filter out users who have not attended any sessions listed. Accepts multiple values.

  • search string

    A search term.

  • page integer

    A page number within the paginated result set.

Responses
  • 200
  • 403

Delete User from Organisation

Remove user from specified organisation.

DELETE /organisations/{organisation}/users/{user}/

Responses
  • 204

Sessions

Get Session Recording URL

GET /sessions/{session}/playback/

Query Parameters
  • search string

    A search term.

  • page integer

    A page number within the paginated result set.

Responses
  • 200
    recording_url string <uri>required
  • 403

Spaces

Create Unified Space

POST /spaces/launch/

Request Body Schema
  • id string required

    An ID identifying the space to join. Using the same ID here will give you the same space, using a different ID will give you a new space. A good candidate to use would be some sort of relationship identifier between the parties involved. This can be any arbitrary string, and is transparently passed through.

    name string

    The (optional) name to give to the Space. If this field is not provided then the `id` field will be used as the name of the Space instead. Note that if this field is null or blank it will still be used and the Space will have a null or blank name.

    allow_guests boolean

    Allow 'guests' to join. In this context being a guest still means you need to have the UUID of the room (likely, due to being invited) Do not set to False, unless you're aware of the side effects.

    Default:true
    record_av boolean

    Boolean value whether or not audio and video will be recorded in this session. This will override the organisation wide Record AV settings and is forced to false if the organisation does not have access to session recordings.

    record_content boolean

    Boolean value determining whether or not the space content will be recorded for this session. This will override the organisation wide record_content settings. Having both record_av and record_content set to `false` will ensure that there will be no recording.

    transcribe boolean

    Boolean value determining whether or not a transcription will be generated for this session.

    user
    name string

    Full name of the person joining this space. Unless an ID is specified, users with the same name are considered to be the same person for stats & analytics.

    Default:Guest
    id string

    Optional ID of the user joining this space. This can be used to differentiate between users with the same name.If not provided, the `name` will be used.

    Default:
    email string <email>

    Optional email address of the user.

    leader boolean

    Control leader mode. If a user has leader mode enabled, they can enable `leading` mode in the space. Leading mode forces the view of all other participants to track the leader.

    Default:false
    profile_picture string <uri>

    URL of a profile picture to use. Defaults to a generic avatar image.

    Default:
    camera_background_url string <uri>

    Sets the default virtual background URL that users can apply to their camera feed.

    single_use boolean

    A single use token can only be used exactly once. It gets redeemed on connection for a persistent token that's then stored in localStorage to allow for things like reconnecting or reloading.

    Default:false
    session_limit boolean

    Allow this link to only be used for the session_id returned by the Launch API. This means that once the session has ended, the link will no longer work.

    Default:false
    custom_jwt_parameters object

    Add in custom parameters to the JWT returned by the Launch API. You can use these for extracting data later in webhooks, or passing data to custom components within the lesson environment. While these are signed, they are just Base64 encoded in the URL, and not suitable for sensitive data like passwords or API keys. Anything under the meta subkey is changable by the user, whereas everything else is not.

    Default:{}
    record boolean

    Determine if this user's AV will be saved.

    ghost boolean

    Join the space in ghost mode (spectator-only), without camera or microphone. Ghost users are not visible to other participants.

    webhooks
    session
    start string <uri>

    URL to call when a session begins.

    idle string <uri>

    URL to call when a session becomes idle.

    end string <uri>

    URL to call when a session ends.

    user
    join string <uri>

    URL to call when a user joins.

    idle string <uri>

    URL to call when a user becomes idle.

    leave string <uri>

    URL to call when a user leaves.

    transcription
    finish string <uri>

    URL to call when a transcription finishes.

    cobrowser
    start string <uri>

    URL to call when a cobrowser session begins.

    stop string <uri>

    URL to call when a cobrowser session stops.

    chat
    message string <uri>

    URL to call when a chat message is sent.

    timeouts
    not_after string <date-time>

    An ISO8601 timestamp specifying the latest time that a user may join the space. This isn't a limit on duration but rather a limit on until when the generated link can be used to join.

    not_before string <date-time>

    An ISO8601 timestamp specifying the earliest time that a user may join the space.

    features object

    Enable or disable arbitrary features of the Space. These are controlled on a per user basis, not a per space basis - so it`s possible to have two users with chat, and one user without chat on the same space. Invalid values will be filtered out. See the features section of the documentation (https://www.thelessonspace.com/docs/guides/launch-features) for a full list of possible features and a description of each field.

    Default:{}
    theme object

    Control certain elements of the Space UI. These are controlled on a per user basis, not a per space basis. Invalid values will be filtered out. See the features section of the documentation (https://www.thelessonspace.com/docs/guides/launch-features#theming) for a full list of possible theming options and description of each field.

    Default:{}
    video_layout_mode string

    Controls the default video layout mode of the space. One of: [grid, sidebar, floating]

    locale string

    Controls the language of the board. Defaults to English. Currently supports `en` (English), `fr` (French), `it` (Italian) and `pl` (Polish)

    server string

    Specifies the region the space should reside in. This defaults to IP geolocation, which depending on your use case may or may not be useful (eg, your clients are connecting from a region very different to the server making the API call). You can work around this by passing the client's IP address in the X-Forwarded-For HTTP header, and it will be used for geolocation instead.

    session_tags object

    A dictionary of key-value tags to apply to the session.

    Default:{}
    space_tags object

    A dictionary of key-value tags to apply to the space.

    Default:{}
    invite_url string

    Custom invite URL to pass in for the 'Invite Others' button.

    resource_url string

    Custom resource library URL.

    holodeck_parameters object

    Any options to pass directly to the underlying Holodeck interface. For now, this is undocumented - set things here only if you've been advised to by the Lessonspace team.

    Default:{}
    auth_external
    method string required

    Currently only 'child' and 'redirect' are supported.

    url string required

    URL to load inside an iFrame / redirect to.

    token string required

    Expected token to be passed to the URL.

    ephemeral boolean

    Whether to only store the token in browser memory and not in local storage.

Responses
  • 200
    client_url string <uri>required

    The URL to which you can redirect the user, or put in an iframe. If you're using an iframe, it's important to ensure the `allow` attribute is set to `camera; microphone; display-capture` or not all features will work.

    api_base string <uri>required

    URL which is the starting point for the space's API.

    room_id string required

    The underlying room.sh identifier which is also the space slug.

    secret string required

    Secret key for accessing the space's API directly. This allows you to sign your own JWTs, as well as interact with the space API directly. This key _must_ be kept secret - having access to it grants unrestricted access to the space.

    session_id string required

    The session ID that will be used in webhooks for this launch.

    user_id integer required

    The internal Lessonspace user ID, returned in webhooks.

    room_settings object

    The settings that apply to the room after this call

    Default:{}
  • 201
    client_url string <uri>required

    The URL to which you can redirect the user, or put in an iframe. If you're using an iframe, it's important to ensure the `allow` attribute is set to `camera; microphone; display-capture` or not all features will work.

    api_base string <uri>required

    URL which is the starting point for the space's API.

    room_id string required

    The underlying room.sh identifier which is also the space slug.

    secret string required

    Secret key for accessing the space's API directly. This allows you to sign your own JWTs, as well as interact with the space API directly. This key _must_ be kept secret - having access to it grants unrestricted access to the space.

    session_id string required

    The session ID that will be used in webhooks for this launch.

    user_id integer required

    The internal Lessonspace user ID, returned in webhooks.

    room_settings object

    The settings that apply to the room after this call

    Default:{}
  • 403

Get Space Session List

Fetch the sessions for a specific space. This endpoint is rate limited; too many requests in a small timeframe will be rejected.

GET /spaces/{space}/sessions/

Query Parameters
  • search string

    If a UUID, filters to sessions or spaces with a matching slug. Otherwise, filters to sessions or spaces with a partial, case-insensitive match on the name.

  • page integer

    A page number within the paginated result set.

  • include_single_user boolean

    Include sessions with only one user.

  • duration_min integer

    Minimum session duration, in seconds.

  • duration_max integer

    Maximum session duration, in seconds.

  • start_time_after string <date-time>

    Filter to sessions that started after the specified ISO8601 timestamp.

  • start_time_before string <date-time>

    Filter to sessions that started before the specified ISO8601 timestamp.

  • end_time_after string <date-time>

    Filter to sessions that ended after the specified ISO8601 timestamp.

  • end_time_before string <date-time>

    Filter to sessions that ended before the specified ISO8601 timestamp.

  • date_after string <date-time>

    Filter to sessions created after the specified ISO8601 timestamp. Using both `date_before` and `date_after` is the same as using `start_time_after` and `end_time_before`.

  • date_before string <date-time>

    Filter sessions created before the specified ISO8601 timestamp. Using both `date_before` and `date_after` is the same as using `start_time_after` and `end_time_before`.

  • user string

    Filter to sessions that the specified Lessonspace user IDs were present in. Accepts multiple values, delimited by `&`.

  • launch_id string

    Filter to sessions linked to the space that was identified with the given value when it was created via the Launch endpoint. Performs a full-string, case-sensitive match.

  • in_progress_only boolean

    Filter to sessions that are in progress only.

  • tags string

    JSON object of tags that must match for the session. Leave the tag value blank to check if only the tag key exists. Must be URL-encoded. Performs a full-string, case-insensitive match.

  • user_external_id string

    Filters to sessions that include a user with a matching `user.id` value that was provided via the Launch endpoint. Performs a full-string, case-insensitive match.

  • user_name string

    Filters to sessions that include a user with a matching `user.name` value that was provided via the Launch endpoint. Performs a partial, case-insensitive match.

Responses
  • 200
    id integer
    uuid string <uuid>
    name string
    start_time string <date-time>
    end_time string <date-time>
    profiles array required
    Array items:
    user integer required
    name string
    profile_picture
    id integer
    uploaded_at string <date-time>
    admin_verified string
    Enum:"not-verified" | "verified"
    image string <uri>
    email string
    role string
    Enum:"teacher" | "student" | "admin"
    guests array required
    Array items:
    id integer
    uuid string <uuid>required
    session integer required
    billable_seconds integer
    logs array required
    Array items:
    id integer
    log_type string
    Enum:"user-left" | "user-joined" | "user-idled" | "session-idled" | "cobrowser-start" | "cobrowser-stop"
    date string <date-time>
    profile string
    guest_uuid string
    created_at string <date-time>
    user_socket_id string
    connected_users array
    recording_access_policy object
    playback_url string
    tags string
  • 403