The Rooms resource is the core of the Video API — this reference covers every endpoint for listing, creating, fetching, updating, and deleting rooms, along with the full set of request and response fields.

The Room object

Every Rooms endpoint returns a room in the same shape. The table below covers every field you'll see in a response.

Field Type Description
name string Name of the room, shown to participants on the join page.
token string The room's identifier, used in the URL path of the room endpoints (e.g. /api/rooms/{token}).
status string (enum) One of active, started, ended, closed. See Room lifecycle for what each status means and how a room moves between them.
access_token string Token that grants host access to the room. Treat it as sensitive.
guest_token string Token that grants guest access to the room.
host_join_url string (uri) URL for the host to join the call.
guest_join_url string (uri) URL for the guest to join the call. Both join URLs accept a name query parameter to pre-fill the participant's display name, e.g. ?name=John+Smith.
host_display_name string, nullable Pre-filled host display name, if one was set.
guest_display_name string, nullable Pre-filled guest display name, if one was set.
enable_chat boolean Whether in-call chat is enabled.
enable_screenshare boolean Whether screen sharing is enabled.
enable_invites boolean Whether inviting extra participants into the room is enabled.
enable_audio_indicator boolean Whether the audio level indicator (waveform) is shown inside the call.
current_participants array of strings Tokens of the participants currently in the call.
expected_guest_count number Number of guest participants expected for this room (the default guest plus any additional guests).
scheduled_at string (date-time) Informational scheduled start time. See Room lifecycle.
meeting_duration number Expected duration of the meeting, in minutes.
return_url string (uri) URL guests are redirected to after leaving the room.
host_return_url string (uri) URL the host is redirected to after leaving the room. Falls back to return_url if not set.
permanent boolean Whether the room is exempt from automatic cleanup. See Additional participants & permanent rooms.
additional_access_tokens array Extra guest access tokens, only present when the additional-participants feature is enabled. See Additional participants & permanent rooms.
created_at string (date-time) When the room was created.
updated_at string (date-time) When the room was last updated.
started_at string (date-time) Set once the room's status becomes started.
ended_at string (date-time) Set once the room's status becomes ended.
closed_at string (date-time) Set once the room's status becomes closed.

List rooms

GET /api/rooms

Fetch a paginated list of rooms. Both Instance and Organization API tokens can call this endpoint: an Instance API Token returns every room in your tenant, while an Organization API Token returns only rooms belonging to the organization or to its doctors. See Authentication & API tokens.

Query parameter Type Description
page integer Page number to fetch. Defaults to 1. 
curl "https://acme.meetone.io/api/rooms?page=1" \
  -H "Authorization: Bearer $MEETONE_API_TOKEN"

{
  "rooms": [
    {
      "name": "Follow-up consultation",
      "token": "f167d6f76f14991c",
      "status": "active",
      "access_token": "65a56167f28f6dec",
      "guest_token": "2367668999959557",
      "scheduled_at": "2024-08-23T15:19:36.378+02:00",
      "meeting_duration": 45,
      "return_url": "http://example.com/rooms/login",
      "host_join_url": "http://www.example.com/r/7bbb22b73d4e4732",
      "guest_join_url": "http://www.example.com/r/3d4e4722b7327bbb",
      "enable_chat": true,
      "enable_screenshare": true,
      "enable_invites": true,
      "enable_audio_indicator": true,
      "permanent": false,
      "created_at": "2024-08-23T15:19:36.378+02:00",
      "updated_at": "2024-08-23T15:19:36.378+02:00"
    }
  ]
}

The response also includes Current-Page, Page-Limit, Total-Pages, Total-Count, and Link headers, and requesting a page beyond the last one returns 200 OK with an empty rooms array rather than an error. See Errors & pagination for the full details.

Create a room

POST /api/rooms

Creates a room. Both token types are accepted, and the token decides who owns the result: an Organization API Token creates the room inside its own organization, so the same token can list, read, update, close, and delete it afterwards, while an Instance API Token creates a room that belongs to no organization. See Authentication & API tokens.

A room only needs name, meeting_duration, and scheduled_at to be created; every other field is optional.

Field Type Required Description
name string Yes Name of the room, shown to participants on the join page.
meeting_duration number Yes Expected duration of the meeting, in minutes.
scheduled_at string (date-time) Yes ISO 8601 timestamp. Purely informational — see Room lifecycle.
return_url string (uri) No URL guests are redirected to when leaving the room. Uses a tenant-wide default if omitted.
host_return_url string (uri) No URL the host is redirected to when leaving the room. Falls back to return_url if omitted.
host_display_name string No Pre-fills the host's display name. If omitted, the host enters a name on the join page.
guest_display_name string No Pre-fills the guest's display name. If omitted, the guest enters a name on the join page.
enable_chat boolean No Enables in-call chat. Defaults to true.
enable_screenshare boolean No Enables screen sharing. Defaults to true.
enable_invites boolean No Enables inviting extra participants. Defaults to true.
enable_audio_indicator boolean No Enables the audio level indicator (waveform) shown inside the call. The indicator on the join screen is always shown, regardless of this setting. Defaults to true.
additional_guest_count number No Number of extra anonymous guest tokens to create. Requires a feature toggle — see Additional participants & permanent rooms.
permanent boolean No Marks the room as permanent. Requires a feature toggle — see Additional participants & permanent rooms. Defaults to false. 
curl -X POST "https://acme.meetone.io/api/rooms" \
  -H "Authorization: Bearer $MEETONE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Follow-up consultation",
    "meeting_duration": 45,
    "scheduled_at": "2024-08-23T15:19:36.378+02:00",
    "host_display_name": "Dr. Smith",
    "guest_display_name": "John Doe"
  }'

A successful request returns 201 Created with the created room:

{
  "name": "Follow-up consultation",
  "token": "f167d6f76f14991c",
  "status": "active",
  "access_token": "65a56167f28f6dec",
  "guest_token": "2367668999959557",
  "scheduled_at": "2024-08-23T15:19:36.378+02:00",
  "meeting_duration": 45,
  "return_url": "http://example.com/rooms/login",
  "host_join_url": "http://www.example.com/r/7bbb22b73d4e4732",
  "guest_join_url": "http://www.example.com/r/3d4e4722b7327bbb",
  "host_display_name": "Dr. Smith",
  "guest_display_name": "John Doe",
  "enable_chat": true,
  "enable_screenshare": true,
  "enable_invites": true,
  "enable_audio_indicator": true,
  "permanent": false,
  "created_at": "2024-08-23T15:19:36.378+02:00",
  "updated_at": "2024-08-23T15:19:36.378+02:00"
}

400 Bad Request is returned with an array of validation errors if a required field is missing or invalid, and 422 Unprocessable Content is returned if permanent: true is submitted without the required feature enabled. See Errors & pagination.

Get a room

GET /api/rooms/{token}

Fetches a single room by its token.

curl "https://acme.meetone.io/api/rooms/f167d6f76f14991c" \
  -H "Authorization: Bearer $MEETONE_API_TOKEN"

{
  "name": "Follow-up consultation",
  "token": "f167d6f76f14991c",
  "status": "started",
  "access_token": "65a56167f28f6dec",
  "guest_token": "2367668999959557",
  "started_at": "2024-08-23T15:22:10.000+02:00",
  "created_at": "2024-08-23T15:19:36.378+02:00",
  "updated_at": "2024-08-23T15:22:10.000+02:00",
  "return_url": "http://example.com/rooms/login",
  "host_display_name": "Dr. Smith",
  "guest_display_name": "John Doe",
  "enable_chat": true,
  "enable_screenshare": true,
  "enable_invites": true,
  "enable_audio_indicator": true,
  "permanent": false,
  "scheduled_at": "2024-08-23T15:19:36.378+02:00",
  "meeting_duration": 45,
  "current_participants": ["2367668999959557"],
  "expected_guest_count": 1,
  "host_join_url": "http://www.example.com/r/7bbb22b73d4e4732",
  "guest_join_url": "http://www.example.com/r/3d4e4722b7327bbb"
}

Returns 404 Not Found if no room matches the given token — including a room that exists but belongs to another organization, when you are using an Organization API Token.

Update a room

PUT /api/rooms/{token}

Updates a room. The request body uses the same fields — including the same required fields, name, meeting_duration, and scheduled_at — as creating a room: send the current values for anything you don't want to change, alongside the fields you do.

curl -X PUT "https://acme.meetone.io/api/rooms/f167d6f76f14991c" \
  -H "Authorization: Bearer $MEETONE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Follow-up consultation (rescheduled)",
    "meeting_duration": 45,
    "scheduled_at": "2024-08-24T09:00:00.000+02:00"
  }'

A successful request returns 200 OK with the updated room, in the same shape as the create response. Returns 404 Not Found if no room matches the given token or the room is outside an Organization API Token's scope.

Delete a room

DELETE /api/rooms/{token}

Permanently deletes a room.

curl -X DELETE "https://acme.meetone.io/api/rooms/f167d6f76f14991c" \
  -H "Authorization: Bearer $MEETONE_API_TOKEN"

A successful request returns 204 No Content.

If you just want to prevent further access without deleting the room's data, close it instead of deleting it — see Room lifecycle.

Questions? Contact us at support@meetone.io.