Lessonspace
Documentation
API Reference

Lessonspace API Reference

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

This page documents the preferred URL format, with no organisation ID present in the URI for organisation-based endpoints. We still support the previous format (eg. /organisations/123/...), and will do so indefinitely. However that ID, if present, is no longer used for anything.

Authentication

API Key

Provide your organisation API Key in the Authorization header with the "Organisation" prefix, for example Authorization: Organisation [your API Key here]. Please refer to our documentation for more information.

Organisations

Get Organisation Session List

Fetch the sessions for an organisation.

GET /organisations/sessions/

Requires API Key authentication
Rate limit: 10 requests per second.
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 ISO 8601 date-time

    Filter to sessions that started after the specified ISO8601 timestamp.

  • start_time_before ISO 8601 date-time

    Filter to sessions that started before the specified ISO8601 timestamp.

  • end_time_after ISO 8601 date-time

    Filter to sessions that ended after the specified ISO8601 timestamp.

  • end_time_before ISO 8601 date-time

    Filter to sessions that ended before the specified ISO8601 timestamp.

  • date_after ISO 8601 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 ISO 8601 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
  • 200Paginated sessions for the organisation.
    {
    count integerrequired
    next string <uri>required
    previous string <uri>required
    results array of objectsrequired
    [
    {
    id integer
    name string
    space objectrequired
    {
    id string

    UUID of the Space

    alias string <slug>
    slug string <slug>required
    name string
    organisation integerrequired
    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 ISO 8601 date-timerequired
    locks array of objects
    [
    {
    id integer
    organisation integerrequired

    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).

    lock_before ISO 8601 date-time

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

    lock_after ISO 8601 date-time

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

    }
    ]
    region string
    record_av boolean
    transcribe boolean
    summarise boolean
    recording_access_policy object
    }
    uuid string <uuid>
    start_time ISO 8601 date-time
    end_time ISO 8601 date-time
    profiles array of objectsrequired
    [
    {
    user integerrequired
    name string
    profile_picture object
    {
    id integer
    uploaded_at ISO 8601 date-time
    admin_verified string
    Enum:"not-verified" | "verified"
    image string <uri>
    }
    email string
    role string
    Enum:"teacher" | "student" | "admin"
    }
    ]
    guests array of objectsrequired
    [
    {
    id integer
    uuid string <uuid>required
    session integerrequired
    }
    ]
    billable_seconds integer
    tags string
    recording_access_policy object
    summary string
    playback_url string
    recording_deleted boolean
    recording_available boolean
    playback_password string
    is_password_set boolean
    }
    ]
    }
  • 403Authentication provided, but the API key does not have permission to perform this action.
    {
    detail stringrequired

    Describes the nature of the error.

    Default:You do not have permission to perform this action.
    type stringrequired

    Describes the type of permission error will be one of `blocked`, `not_in_organisation`, `deactivated_account`, `not_organisation_admin`, `not_organisation_admin_or_teacher`, `did_not_attend_space`, `invalid_subscription`, `whiteboard_access_denied`, `resource_access_denied`, `invalid_token_tw` or `permission_denied`.

    url string

    Only valid when type is `blocked`

    }
  • 429Too many requests were made in the rate-limit window. Wait before retrying.
    {
    non_field_errors array of string
    Default:[ "Request has been rate limited. Please try again later." ]
    }

Get Organisation Session

Fetch a session with the given UUID.

GET /organisations/sessions/{session}/

Requires API Key authentication
Rate limit: 10 requests per second.
Responses
  • 200Session details for the requested UUID.
    {
    id integer
    name string
    space objectrequired
    {
    id string

    UUID of the Space

    alias string <slug>
    slug string <slug>required
    name string
    organisation integerrequired
    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 ISO 8601 date-timerequired
    locks array of objects
    [
    {
    id integer
    organisation integerrequired

    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).

    lock_before ISO 8601 date-time

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

    lock_after ISO 8601 date-time

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

    }
    ]
    region string
    record_av boolean
    transcribe boolean
    summarise boolean
    recording_access_policy object
    }
    uuid string <uuid>
    start_time ISO 8601 date-time
    end_time ISO 8601 date-time
    profiles array of objectsrequired
    [
    {
    user integerrequired
    name string
    profile_picture object
    {
    id integer
    uploaded_at ISO 8601 date-time
    admin_verified string
    Enum:"not-verified" | "verified"
    image string <uri>
    }
    email string
    role string
    Enum:"teacher" | "student" | "admin"
    }
    ]
    guests array of objectsrequired
    [
    {
    id integer
    uuid string <uuid>required
    session integerrequired
    }
    ]
    billable_seconds integer
    tags string
    recording_access_policy object
    summary string
    playback_url string
    recording_deleted boolean
    recording_available boolean
    playback_password string
    is_password_set boolean
    }
  • 403Authentication provided, but the API key does not have permission to perform this action.
    {
    detail stringrequired

    Describes the nature of the error.

    Default:You do not have permission to perform this action.
    type stringrequired

    Describes the type of permission error will be one of `blocked`, `not_in_organisation`, `deactivated_account`, `not_organisation_admin`, `not_organisation_admin_or_teacher`, `did_not_attend_space`, `invalid_subscription`, `whiteboard_access_denied`, `resource_access_denied`, `invalid_token_tw` or `permission_denied`.

    url string

    Only valid when type is `blocked`

    }
  • 429Too many requests were made in the rate-limit window. Wait before retrying.
    {
    non_field_errors array of string
    Default:[ "Request has been rate limited. Please try again later." ]
    }

Update Organisation Session

Update a session's name or recording access policy for the given UUID.

PATCH /organisations/sessions/{session}/

Requires API Key authentication
Rate limit: 10 requests per second.
Request Body Schema
  • name stringrequired

    Name of the session

    recording_access_policy object

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

Responses
  • 200Request succeeded.
    {
    name stringrequired

    Name of the session

    recording_access_policy object

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

    }
  • 403Authentication provided, but the API key does not have permission to perform this action.
    {
    detail stringrequired

    Describes the nature of the error.

    Default:You do not have permission to perform this action.
    type stringrequired

    Describes the type of permission error will be one of `blocked`, `not_in_organisation`, `deactivated_account`, `not_organisation_admin`, `not_organisation_admin_or_teacher`, `did_not_attend_space`, `invalid_subscription`, `whiteboard_access_denied`, `resource_access_denied`, `invalid_token_tw` or `permission_denied`.

    url string

    Only valid when type is `blocked`

    }
  • 429Too many requests were made in the rate-limit window. Wait before retrying.
    {
    non_field_errors array of string
    Default:[ "Request has been rate limited. Please try again later." ]
    }

Get Session Recording URL

GET /organisations/sessions/{session}/playback/

Requires API Key authentication
Rate limit: 10 requests per second.
Responses
  • 200Recording is ready. The returned URL can be used immediately.
    {
    recording_url string <uri>required
    }
  • 202Recording URL was created, but the recording is still being prepared.
    {
    recording_url string <uri>required
    }
  • 403Authentication provided, but the API key does not have permission to perform this action.
    {
    detail stringrequired

    Describes the nature of the error.

    Default:You do not have permission to perform this action.
    type stringrequired

    Describes the type of permission error will be one of `blocked`, `not_in_organisation`, `deactivated_account`, `not_organisation_admin`, `not_organisation_admin_or_teacher`, `did_not_attend_space`, `invalid_subscription`, `whiteboard_access_denied`, `resource_access_denied`, `invalid_token_tw` or `permission_denied`.

    url string

    Only valid when type is `blocked`

    }
  • 404Session was not found in the authenticated organisation.
    {
    detail string
    }
  • 429Too many requests were made in the rate-limit window. Wait before retrying.
    {
    non_field_errors array of string
    Default:[ "Request has been rate limited. Please try again later." ]
    }

Get Organisation Session Transcript

Fetch the transcription for a given session. The transcription must have been scheduled on the session beforehand.

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

Requires API Key authentication
Rate limit: 10 requests per second.
Responses
  • 200Transcription is available. A signed download URL is returned.
    {
    transcriptionUrl string <uri>
    }
  • 403Authentication provided, but the API key does not have permission to perform this action.
    {
    detail stringrequired

    Describes the nature of the error.

    Default:You do not have permission to perform this action.
    type stringrequired

    Describes the type of permission error will be one of `blocked`, `not_in_organisation`, `deactivated_account`, `not_organisation_admin`, `not_organisation_admin_or_teacher`, `did_not_attend_space`, `invalid_subscription`, `whiteboard_access_denied`, `resource_access_denied`, `invalid_token_tw` or `permission_denied`.

    url string

    Only valid when type is `blocked`

    }
  • 404Session was not found or transcription is unavailable.
    {
    detail string
    }
  • 429Too many requests were made in the rate-limit window. Wait before retrying.
    {
    non_field_errors array of string
    Default:[ "Request has been rate limited. Please try again later." ]
    }

Get Organisation Space List

GET /organisations/spaces/

Requires API Key authentication
Rate limit: 10 requests per second.
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 ISO 8601 date-time

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

  • date_before ISO 8601 date-time

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

Responses
  • 200Paginated spaces in the organisation.
    {
    count integerrequired
    next string <uri>required
    previous string <uri>required
    results array of objectsrequired
    [
    {
    id string

    UUID of the Space

    alias string <slug>
    slug string <slug>required
    name string
    organisation integerrequired
    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 ISO 8601 date-timerequired
    locks array of objects
    [
    {
    id integer
    organisation integerrequired

    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).

    lock_before ISO 8601 date-time

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

    lock_after ISO 8601 date-time

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

    }
    ]
    region string
    record_av boolean
    transcribe boolean
    summarise boolean
    recording_access_policy object
    }
    ]
    }
  • 403Authentication provided, but the API key does not have permission to perform this action.
    {
    detail stringrequired

    Describes the nature of the error.

    Default:You do not have permission to perform this action.
    type stringrequired

    Describes the type of permission error will be one of `blocked`, `not_in_organisation`, `deactivated_account`, `not_organisation_admin`, `not_organisation_admin_or_teacher`, `did_not_attend_space`, `invalid_subscription`, `whiteboard_access_denied`, `resource_access_denied`, `invalid_token_tw` or `permission_denied`.

    url string

    Only valid when type is `blocked`

    }
  • 429Too many requests were made in the rate-limit window. Wait before retrying.
    {
    non_field_errors array of string
    Default:[ "Request has been rate limited. Please try again later." ]
    }

Get Organisation User List

GET /organisations/users/

Requires API Key authentication
Rate limit: 10 requests per second.
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
  • 200Paginated users in the organisation.
    {
    count integerrequired
    next string <uri>required
    previous string <uri>required
    results array of objectsrequired
    [
    {
    user object
    {
    id integer
    email string
    }
    role string
    Enum:"teacher" | "student" | "admin"
    active boolean
    profile_picture object
    {
    id integer
    uploaded_at ISO 8601 date-time
    admin_verified string
    Enum:"not-verified" | "verified"
    image string <uri>
    }
    name string
    external_id string
    url string
    }
    ]
    }
  • 403Authentication provided, but the API key does not have permission to perform this action.
    {
    detail stringrequired

    Describes the nature of the error.

    Default:You do not have permission to perform this action.
    type stringrequired

    Describes the type of permission error will be one of `blocked`, `not_in_organisation`, `deactivated_account`, `not_organisation_admin`, `not_organisation_admin_or_teacher`, `did_not_attend_space`, `invalid_subscription`, `whiteboard_access_denied`, `resource_access_denied`, `invalid_token_tw` or `permission_denied`.

    url string

    Only valid when type is `blocked`

    }
  • 429Too many requests were made in the rate-limit window. Wait before retrying.
    {
    non_field_errors array of string
    Default:[ "Request has been rate limited. Please try again later." ]
    }

Delete User from Organisation

DELETE /organisations/users/{user}/

Requires API Key authentication
Rate limit: 10 requests per second.
Responses
  • 204User was removed from the organisation.
  • 400The user cannot be removed, for example because they own the organisation.
  • 429Request was rate limited.
    {
    non_field_errors array of string
    Default:[ "Request has been rate limited. Please try again later." ]
    }

Spaces

Create Unified Space

POST /spaces/launch/

Requires API Key authentication
Request Body Schema
  • id stringrequired

    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

    record_content boolean

    Boolean value determining whether or not the space content will be recorded for this session. By default, this is set to be the same as `record_av`. If both this and `record_av` are true, a recording will be available after the session with video. If `record_av` is false and this is true, a recording will be available after the session without video. If `record_av` is true and this is false, no recording will be available after the session, but transcriptions and summaries will still be generated if requested.

    transcribe boolean

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

    summarise boolean

    Boolean value determining whether or not a summary should be generated for this session.

    user object
    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
    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 object
    session object
    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 object
    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 object
    finish string <uri>

    URL to call when a transcription finishes.

    summary object
    finish string <uri>

    URL to call when a summary finishes.

    cobrowser object
    start string <uri>

    URL to call when a cobrowser session begins.

    stop string <uri>

    URL to call when a cobrowser session stops.

    chat object
    message string <uri>

    URL to call when a chat message is sent.

    knock object
    request string <uri>

    URL to call when a user knocks on the waiting room. This is issued once when the user performs the first knock. It will be re-issued if the user manually stops and restarts the knock, or refreshes the browser.

    admit string <uri>

    URL to call when a leader admits a user from the waiting room.

    deny string <uri>

    URL to call when a leader denies a user from the waiting room.

    timeouts object
    not_after ISO 8601 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 ISO 8601 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/guide/space-config#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/guide/space-config#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 object
    method stringrequired

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

    url stringrequired

    URL to load inside an iFrame / redirect to.

    token stringrequired

    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
  • 200Existing space reused.
    {
    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 stringrequired

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

    secret stringrequired

    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 stringrequired

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

    user_id integerrequired

    The internal Lessonspace user ID, returned in webhooks.

    room_settings object

    The settings that apply to the room after this call

    Default:{}
    }
  • 201New space created.
    {
    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 stringrequired

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

    secret stringrequired

    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 stringrequired

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

    user_id integerrequired

    The internal Lessonspace user ID, returned in webhooks.

    room_settings object

    The settings that apply to the room after this call

    Default:{}
    }
  • 400Invalid launch request or unsupported requested configuration.
    {
    non_field_errors array of string
    }
  • 403Authentication provided, but the API key does not have permission to perform this action.
    {
    detail stringrequired

    Describes the nature of the error.

    Default:You do not have permission to perform this action.
    type stringrequired

    Describes the type of permission error will be one of `blocked`, `not_in_organisation`, `deactivated_account`, `not_organisation_admin`, `not_organisation_admin_or_teacher`, `did_not_attend_space`, `invalid_subscription`, `whiteboard_access_denied`, `resource_access_denied`, `invalid_token_tw` or `permission_denied`.

    url string

    Only valid when type is `blocked`

    }
  • 503Room service could not create the space. Retry later or contact support.
    {
    non_field_errors array of string
    }

Get Space Session List

Fetch the sessions for a specific space.

GET /spaces/{space}/sessions/

Requires API Key authentication
Rate limit: 10 requests per second.
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 ISO 8601 date-time

    Filter to sessions that started after the specified ISO8601 timestamp.

  • start_time_before ISO 8601 date-time

    Filter to sessions that started before the specified ISO8601 timestamp.

  • end_time_after ISO 8601 date-time

    Filter to sessions that ended after the specified ISO8601 timestamp.

  • end_time_before ISO 8601 date-time

    Filter to sessions that ended before the specified ISO8601 timestamp.

  • date_after ISO 8601 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 ISO 8601 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
  • 200Paginated sessions for the requested space.
    {
    count integerrequired
    next string <uri>required
    previous string <uri>required
    results array of objectsrequired
    [
    {
    id integer
    uuid string <uuid>
    name string
    start_time ISO 8601 date-time
    end_time ISO 8601 date-time
    profiles array of objectsrequired
    [
    {
    user integerrequired
    name string
    profile_picture object
    {
    id integer
    uploaded_at ISO 8601 date-time
    admin_verified string
    Enum:"not-verified" | "verified"
    image string <uri>
    }
    email string
    role string
    Enum:"teacher" | "student" | "admin"
    }
    ]
    guests array of objectsrequired
    [
    {
    id integer
    uuid string <uuid>required
    session integerrequired
    }
    ]
    billable_seconds integer
    logs array of objectsrequired
    [
    {
    id integer
    log_type string
    Enum:"user-left" | "user-joined" | "user-idled" | "session-idled" | "cobrowser-start" | "cobrowser-stop"
    date ISO 8601 date-time
    profile string
    guest_uuid string
    created_at ISO 8601 date-time
    user_socket_id string
    }
    ]
    connected_users array of objects
    recording_access_policy object
    tags string
    summary string
    playback_url string
    }
    ]
    }
  • 403Authentication provided, but the API key does not have permission to perform this action.
    {
    detail stringrequired

    Describes the nature of the error.

    Default:You do not have permission to perform this action.
    type stringrequired

    Describes the type of permission error will be one of `blocked`, `not_in_organisation`, `deactivated_account`, `not_organisation_admin`, `not_organisation_admin_or_teacher`, `did_not_attend_space`, `invalid_subscription`, `whiteboard_access_denied`, `resource_access_denied`, `invalid_token_tw` or `permission_denied`.

    url string

    Only valid when type is `blocked`

    }
  • 429Too many requests were made in the rate-limit window. Wait before retrying.
    {
    non_field_errors array of string
    Default:[ "Request has been rate limited. Please try again later." ]
    }