LiqaOSDeveloper documentation العربية

LiqaOS API documentation

LiqaOS runs video rooms for your product. Your server creates a room and a join link for each person; your page shows the room in an iframe; LiqaOS tells your server what happened through webhooks. Base URL: https://liqaos.academito.online

Overview

LiqaOS knows four things: customers (you), rooms, participants and minutes. It knows nothing about your users or your data: you identify every person with an external_id of your own, and LiqaOS gives it back to you in every response and webhook.

Roles

RoleWhat the person can do
hostIs always admitted, whatever the waiting room or the capacity. Admits or denies people who are waiting, mutes someone’s microphone, ends the room for everyone, and shows your content on the stage. Can publish camera, microphone and screen.
participantPublishes camera, microphone and screen, and sends data. Enters through the waiting room when the room has one.
observerWatches and listens only; cannot publish anything. Passes through the waiting room like a participant.

The waiting room

When a room has waiting_room: true (the default), a participant or observer who opens their link asks to enter, becomes waiting, and a host admits or denies them from inside the room. Hosts get a sound and a card for each person waiting. When it is false, everyone is admitted on arrival, as long as the room is open and not full. A person who was admitted and dropped out returns without asking again; a person a host denied stays denied for that link.

Admitting and denying happen in the room, by a host. v1 has no API call for them; your server hears about them through the participant.waiting, participant.admitted and participant.denied webhooks.

What LiqaOS does not do

  • Media is never stored. There is no recording in v1.
  • It does not manage your users, accounts or permissions: you decide who gets a link and with which role.
  • It does not fetch or keep your content: a page you show on the stage is loaded by each person’s own browser, in a sandboxed frame (see Your content on the stage).

Quick start

1. Get an API key

Keys are issued by the LiqaOS operator; there is no self-service screen in v1. Ask the operator for a customer account and tell them:

  • the origins of the pages that will frame the room (embed_origins), for example https://app.example.com;
  • the origins of the pages you will show on the stage (content_origins), if any;
  • the URL that should receive webhooks (webhook_url), if any.

The operator creates the account in the operator panel and passes you the two secrets it shows:

API key:        lq_live_<40 random characters>
Webhook secret: whsec_<40 random characters>

The key and the webhook secret are shown once. LiqaOS stores only a SHA-256 hash of the key, and the secret in encrypted form that is not shown again. Store both in your server’s secret store straight away. LiqaOS cannot show them again: if you lose a key, ask the operator for a new one (see Keys).

Origins are written as scheme://host[:port] with nothing after it: https://app.example.com, not https://app.example.com/rooms.

2. Create a room

curl -X POST https://liqaos.academito.online/api/v1/rooms \
  -H "Authorization: Bearer $LIQAOS_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "external_id": "consult-2041",
    "title": "Follow-up consultation",
    "opens_at": "2026-12-01T08:50:00Z",
    "closes_at": "2026-12-01T10:00:00Z",
    "waiting_room": true,
    "max_participants": 4,
    "metadata": { "department": "cardiology" }
  }'

The answer is 201 with the room:

{
  "id": "01JD5Q8K3Z7M2V9X4B6N1C0HTA",
  "external_id": "consult-2041",
  "title": "Follow-up consultation",
  "opens_at": "2026-12-01T08:50:00Z",
  "closes_at": "2026-12-01T10:00:00Z",
  "waiting_room": true,
  "whiteboard": true,
  "features": { "whiteboard": true, "screen_share": true, "pip": true },
  "max_participants": 4,
  "metadata": { "department": "cardiology" },
  "embed_origins": [],
  "content_origins": [],
  "status": "scheduled",
  "started_at": null,
  "ended_at": null,
  "created_at": "2026-11-08T12:00:00Z"
}

3. Add a participant

curl -X POST https://liqaos.academito.online/api/v1/rooms/01JD5Q8K3Z7M2V9X4B6N1C0HTA/participants \
  -H "Authorization: Bearer $LIQAOS_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "external_id": "user-17",
    "name": "Dr. Salma Haddad",
    "role": "host"
  }'
{
  "participant_id": "01JD5QB2W4R8T6Y0E3F5G7H9JK",
  "join_url": "https://liqaos.academito.online/j/<64 random characters>",
  "expires_at": "2026-12-01T10:00:00Z"
}

Call it once per person. join_url belongs to that person only: it is their key into the room.

4. Open the link or embed it

Send the person to join_url, or put it in an iframe on a page whose origin is in embed_origins (see Embedding the room).

The same flow on your server (Node.js)

// Node.js 18 or later. Run it on your server, never in a browser: it holds the API key.
const BASE = 'https://liqaos.academito.online';
const KEY = process.env.LIQAOS_KEY; // lq_live_...

async function call(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${json.code}: ${json.message}`);
  return json;
}

// 1. The room. The same external_id always returns the same room.
const room = await call('POST', '/api/v1/rooms', {
  external_id: 'consult-2041',
  title: 'Follow-up consultation',
  closes_at: '2026-12-01T10:00:00Z',
});

// 2. One join link per person.
const host = await call('POST', `/api/v1/rooms/${room.id}/participants`, {
  external_id: 'user-17',
  name: 'Dr. Salma Haddad',
  role: 'host',
});
const guest = await call('POST', `/api/v1/rooms/${room.id}/participants`, {
  external_id: 'user-52',
  name: 'Omar Nasser',
  role: 'participant',
});

// 3. Give each person their own link (or put it in an iframe, see "Embedding").
console.log('host ', host.join_url);
console.log('guest', guest.join_url);

Authentication

Every call under /api/v1 carries your key as a bearer token:

Authorization: Bearer lq_live_<40 random characters>
  • The key starts with lq_live_ followed by 40 random characters.
  • A missing key, a key that does not start with lq_live_, an unknown key, a revoked key and a key of a customer whose account the operator blocked all get the same answer: 401 unauthenticated.
  • Keep the key on your server. Never put it in a page, an app or a repository.
{
  "code": "unauthenticated",
  "message": "A valid API key is required."
}

Keys

  • You may hold several keys at once, for example one per server or per environment, so that one can be replaced without stopping the others. Each key is checked on its own and acts as the same customer; the limit of 120 requests a minute is per customer.
  • The operator issues, rotates and revokes keys; you ask for it. A new key is shown once, to the operator, who passes it to you. Rotating gives you a new key in place of an old one, and the old one stops working at once. If you cannot afford a gap, ask for an additional key first, switch over, and then ask for the old key to be revoked. A revoked key answers 401.
  • The webhook secret can be rotated by the operator as well. It is shown once, and from then on you verify signatures with the new value, so change your verification code at the same time.
  • LiqaOS keeps only a hash of a key: it cannot be shown again. If a key is lost or leaked, ask for a new one and for the old one to be revoked.

Conventions

  • Requests and responses are JSON (Content-Type: application/json). Responses are bare objects and arrays, with no data wrapper.
  • Times are ISO-8601 instants. LiqaOS answers in UTC with a trailing Z (2026-12-01T10:00:00Z). Always send an explicit offset or Z yourself.
  • Ids (id, participant_id) are 26-character ULIDs. Treat them as opaque strings.
  • Every refusal has a machine-readable code and a message. Act on the code; the message is for humans and is in English.
  • A room of another customer does not exist for you: it answers 404 not_found, like a room that was never created.
  • Lists are not paginated.

API reference

All routes live under /api/v1 and need the Authorization header. Each key may make 120 requests a minute (see Errors and limits).

Create a room

POST/api/v1/rooms
FieldTypeRequiredRules
titlestringyesUp to 255 characters.
external_idstring or nullnoUp to 191 characters. Your own id for the room, unique per customer. See below.
opens_atISO-8601 or nullnoBefore this instant the room answers not_open. See Room window.
closes_atISO-8601 or nullnoMust be later than opens_at when both are set. After this instant the room answers closed, and join links stop at this instant.
waiting_roombooleannoDefault true.
whiteboardbooleannoWhether the room has a whiteboard (see The whiteboard). This is the room’s own switch and starts as true; the board is on only while your account also has the whiteboard feature on (the operator can turn it off for your whole account, rooms that exist included). The room returns features, what is on now.
max_participantsintegerno1 to 1000. Default 50.
metadataJSON object or nullnoAnything you want back later. LiqaOS does not read it.
embed_originsarray of originsnoUp to 10, each up to 255 characters, each scheme://host[:port]. Added to your account’s own list for this room only.
content_originsarray of originsnoSame rules. Added to your account’s own list for this room only.

Idempotent on external_id. If a room with that external_id already exists, the call returns it with 200 instead of 201, and the other fields you sent are ignored (use PATCH to change a room). The request is validated first, so a repeated call must still be valid. Two parallel calls with the same external_id end up with one room.

Per-room origins. If your pages live on many hosts (one per client, say), name the host that frames this room in embed_origins and the hosts whose pages may be shown in content_origins. They are added to your account’s lists for this room only. The response shows them normalised (lower case, no trailing slash); malformed ones are dropped from the output.

Response 201 (created) or 200 (existing): the room object.

FieldMeaning
idLiqaOS id of the room (ULID).
external_idYours, or null.
title, waiting_room, whiteboard, max_participants, metadataAs stored.
opens_at, closes_atUTC, or null.
embed_origins, content_originsThis room’s own lists only, not your account’s.
statusscheduled before opens_at; open from then on; live while at least one person is connected; ended once the room was ended or closes_at has passed.
started_atWhen the first person connected, or null.
ended_atWhen the room was ended through /end or by a host, or null. It stays null for a room that merely passed closes_at.
created_atUTC.

Errors: 401, 402 subscription_inactive (the subscription cannot start anything new), 402 quota_exceeded (a plan that stops at its allowance has used it up), 422 validation_failed, 429 rate_limited or 429 concurrent_rooms_limit (the plan’s limit on meetings at the same time is reached). A call with a known external_id returns the existing room and is not a new room: it is never refused for the allowance or the room limit, but the subscription must still be usable. See Plans and limits.

Get a room

GET/api/v1/rooms/{room}

{room} is the room’s id (not the external_id). Returns the room object above. Errors: 401, 404 not_found, 429.

Update a room

PATCH/api/v1/rooms/{room}

Takes the same fields as the creation call; every field is optional, and only the ones you send change. title, when sent, must not be null.

curl -X PATCH https://liqaos.academito.online/api/v1/rooms/01JD5Q8K3Z7M2V9X4B6N1C0HTA \
  -H "Authorization: Bearer $LIQAOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "closes_at": "2026-12-01T11:00:00Z" }'
  • Moving closes_at also moves the expiry of every participant’s join link to the new time. Setting it to null gives every link 24 hours from now.
  • closes_at is checked against opens_at as it will be after the change, including a value you did not send.
  • A room whose closes_at passed but that nobody ended can still be updated, which is how you extend it.
  • Changing external_id to one that another room of yours already uses fails with 422 external_id_taken.

Returns the room. Errors: 401, 404, 409 room_ended (the room was explicitly ended; it cannot be changed), 422 validation_failed or external_id_taken, 429.

End a room

POST/api/v1/rooms/{room}/end

No body. Ends the room for everyone: LiqaOS removes it from the media server, so everyone connected is dropped; later joins are refused with ended; waiting and admitted people are marked as left; open usage intervals are closed; and your server receives room.ended.

curl -X POST https://liqaos.academito.online/api/v1/rooms/01JD5Q8K3Z7M2V9X4B6N1C0HTA/end \
  -H "Authorization: Bearer $LIQAOS_KEY"

Returns the room with status: "ended". Calling it again on an ended room changes nothing and sends no second webhook. If the media server cannot be reached, the room is still ended on LiqaOS and new joins are refused, but people already connected may not be dropped at once.

Errors: 401, 404, 429.

Add a participant

POST/api/v1/rooms/{room}/participants
FieldTypeRequiredRules
external_idstringyesUp to 191 characters. Your id for this person. One person per external_id in a room.
namestringyesUp to 255 characters. Shown to the others in the room.
rolestringyeshost, participant or observer.
avatar_urlURL or nullnoA valid URL, up to 2048 characters.

Response: 201 the first time, 200 when this external_id already exists in the room.

FieldMeaning
participant_idLiqaOS id of the person in this room.
join_urlhttps://liqaos.academito.online/j/<token>. The token exists only in this response: LiqaOS stores a hash.
expires_atWhen the link stops working: the room’s closes_at, or 24 hours from now if the room has none.

Issuing again. Calling this again for the same external_id gives a new link and the old one stops working at once. Name, role and avatar are updated. The person’s admission state is kept, so it is safe to re-issue on every page load: someone a host denied does not become welcome again, and someone already admitted does not wait twice. Sessions opened with the old link end with it.

Errors: 401, 404, 409 room_ended (the room was ended), 409 room_closed (closes_at has passed), 402 subscription_inactive, 402 quota_exceeded (a new person, on a plan that stops at its allowance), 422 validation_failed, 429 rate_limited. A room that has not opened yet accepts participants. Re-issuing a link for an external_id that is already in the room is not a new person and is not metered against the allowance; it still needs a usable subscription. See Plans and limits.

List participants

GET/api/v1/rooms/{room}/participants

Returns an array of every person added to the room, oldest first.

[
  {
    "participant_id": "01JD5QB2W4R8T6Y0E3F5G7H9JK",
    "external_id": "user-17",
    "name": "Dr. Salma Haddad",
    "role": "host",
    "avatar_url": null,
    "state": "in_room",
    "joined_at": "2026-12-01T08:58:12Z",
    "left_at": null
  },
  {
    "participant_id": "01JD5QC7M1N3P5Q7R9S2T4V6WX",
    "external_id": "user-52",
    "name": "Omar Nasser",
    "role": "participant",
    "avatar_url": "https://app.example.com/avatars/52.png",
    "state": "waiting",
    "joined_at": null,
    "left_at": null
  }
]
StateMeaning
invitedHas a link; has not asked to enter.
waitingAsked to enter; a host has not answered.
admittedAllowed in (by a host, or automatically), not connected yet. An admitted person who never connects stops holding a seat after 10 minutes.
deniedRefused by a host. Final for that link.
in_roomConnected now. joined_at is set.
leftWas in the room and left, or the room ended. left_at is set.

joined_at and left_at are UTC or null. Errors: 401, 404, 429.

Usage

GET/api/v1/rooms/{room}/usage
{
  "participant_minutes": 47.5,
  "peak_participants": 3
}
  • participant_minutes: the total time all people spent connected, in minutes, rounded to two decimals. A person who is connected now counts up to this moment.
  • peak_participants: the most people connected at the same time. A hand-over at the same second (one leaves, one joins) does not count as two.

Usage is per room. Add up the rooms of the period for your own total. Errors: 401, 404, 429.

Room window and join links

opens_at and closes_at are both optional. A room with neither is open from the moment it is created until it is ended.

MomentWhat a person who opens their link sees
Before opens_atThe room is not open yet (state not_open). The page checks again by itself and lets the person in once the room opens. Hosts wait too. You can still add participants.
opens_at to closes_atNormal entry: waiting room, capacity and admission apply.
After closes_atThe room is closed (state closed). No one enters. status reads ended. New participants are refused with 409 room_closed.
After an explicit endState ended.
Room fullState full for participants and observers (hosts are never refused). A seat is held by someone connected, or admitted within the last 10 minutes.

People already inside when closes_at passes are shown the closed screen at their next check, which the room makes every 30 seconds. Call End a room when you need the room to stop at an exact moment.

Passing closes_at does not by itself send a room.ended webhook. That event is sent when the room is ended through /end or by a host.

Join link lifetime

  • A link is valid until the room’s closes_at. A room without one gives each link 24 hours from the moment it was issued.
  • Updating closes_at moves every link’s expiry with it.
  • An expired link (while the room is still running) answers 410 token_expired and the page shows an invalid-link screen. Issue a new link with Add a participant.
  • A link that is unknown, or was replaced by a newer one for the same person, looks the same as an invalid one: 404 invalid_token.
  • Once a person has opened the link, the page works with a session of 2 hours, bound to that link. The media ticket lasts 2 hours and is renewed by the page.

Embedding the room

The iframe

Put the participant’s join_url in an iframe with exactly these permissions:

<iframe
  id="room"
  src="https://liqaos.academito.online/j/JOIN_TOKEN"
  title="Video room"
  allow="camera; microphone; display-capture; fullscreen; autoplay; picture-in-picture"
  style="width:100%; height:600px; border:0">
</iframe>

Without allow, the browser refuses the camera, microphone and screen sharing inside the frame.

Your page must allow it

  • Your origin must be listed. LiqaOS lets only embed_origins (your account’s plus the room’s) frame the room. It sends frame-ancestors 'self' followed by those origins. A page whose origin (scheme, host and port, exactly) is not listed gets a blank frame.
  • Your Content-Security-Policy, if you send one with frame-src or default-src, must allow https://liqaos.academito.online.
  • Your Permissions-Policy, if you send one, must hand the devices to LiqaOS, or the browser blocks them before the iframe’s allow is looked at.
# Headers your own page may send. Add only what you already use.

# Content-Security-Policy: let the page frame LiqaOS.
Content-Security-Policy: frame-src https://liqaos.academito.online

# Permissions-Policy: if you send this header at all, delegate the devices to LiqaOS.
Permissions-Policy: camera=(self "https://liqaos.academito.online"), microphone=(self "https://liqaos.academito.online"), display-capture=(self "https://liqaos.academito.online"), fullscreen=(self "https://liqaos.academito.online"), picture-in-picture=(self "https://liqaos.academito.online"), autoplay=(self "https://liqaos.academito.online")

For reference, this is what LiqaOS sends with the room page (the origins in the first line are the room’s):

Content-Security-Policy: frame-ancestors 'self' https://app.example.com
Permissions-Policy: camera=(self), microphone=(self), display-capture=(self), fullscreen=(self), picture-in-picture=(self), autoplay=(self)
Referrer-Policy: no-referrer
Cache-Control: no-store
X-Content-Type-Options: nosniff

The page must be served over HTTPS (or localhost while developing): browsers give cameras and microphones to secure pages only.

The floating window

When a person leaves the meeting’s tab (another tab, another app, a minimised browser), the room can keep the meeting visible in a small floating window with microphone, camera and leave buttons and a way back to the meeting. Closing that window only returns to the browser: the call goes on. What the person gets depends on the browser, and nothing here needs a server call:

  • The room opened as its own page (Chrome, Edge on a computer): a window drawn by LiqaOS, with its own buttons.
  • The room inside your iframe, and Chrome on Android: the browser’s own picture-in-picture window showing the speaker or the shared screen, with the browser’s microphone, camera and hang-up buttons. A browser only lets a page open its own floating window from a top-level page, which is why an iframe gets this form.
  • Safari: the video alone, without buttons; Safari offers no way to add them.
  • Firefox and other browsers without the feature: the control is not shown.

For an embedded room to offer it, the iframe needs picture-in-picture in its allow attribute (it is in the snippet above), and your own Permissions-Policy must not block it. Where the policy blocks it the room simply does not show the control. Some browsers also enter the window by themselves when the person switches away; that is the browser’s decision and the room does not need anything from your page for it.

Messages: room to your page

The room talks to your page with window.postMessage. Every message is an object whose type starts with liqaos:.

MessageFieldsWhen
liqaos:readynoneThe room has loaded. Sent first, before the room knows your origin, so it is the one message whose target origin is *. It carries nothing private.
liqaos:statestatewaiting (asked to enter), admitted (let in, connecting), in_room (connected), left (the person left), ended (the room ended or closed).
liqaos:participantevent, name, role, external_idevent is joined or left when another person connects to or leaves the room while this person is in it; waiting when someone asks to enter (sent to a host’s page only, and the role is participant).
liqaos:contentkey, urlA host shared content (see Your content on the stage). You may answer with liqaos:content-url.
liqaos:content-stoppedkeyThe content with that key is no longer on the stage, whatever the reason: the host’s own stop control, your page’s liqaos:stop-content, other content replacing it, the person who shared it leaving, the room ending, or this person leaving. Follow the real state from it rather than from what your page last sent.
liqaos:boardopen (boolean)The whiteboard was opened or closed in this room (by a host, or by liqaos:board-open and liqaos:board-close). See The whiteboard.

Messages: your page to the room

MessageFieldsEffect
liqaos:share-contentkey, url, title, optional controls (boolean)Host only. Shows url on the stage for everyone. Ignored for anyone who is not a host. With controls: false your page says it manages the content itself (its own stop button), and the room does not draw its own “Stop sharing” control on the host’s stage; without it, the room draws that control.
liqaos:content-urlkey, urlAnswer to liqaos:content: this person’s own URL for the same content.
liqaos:stop-contentnoneHost only. Removes the content from the stage.
liqaos:leavenoneThe person leaves the room.
liqaos:compacton (boolean)Switches to the small floating layout (true) or back (false).
liqaos:board-opennoneHost only. Opens the whiteboard for everyone in the room. Ignored for anyone who is not a host, and in a room without a whiteboard.
liqaos:board-closenoneHost only. Closes the whiteboard for everyone. The drawing stays on the board.

Which origins are checked

  • In the room, a message is accepted only from the page that frames it (event.source is the parent window), and only when that page’s origin is the one the browser reports for the parent and, if the room has embed_origins, is one of them. Messages from other origins and other windows are dropped silently.
  • In the room, outgoing messages are sent to that one origin, never * (except liqaos:ready).
  • In your page, check event.origin === 'https://liqaos.academito.online' and event.source === iframe.contentWindow, and send with that exact origin as targetOrigin.
  • Browsers that do not expose the framing page’s origin to the frame (they lack location.ancestorOrigins) leave the room unable to name its parent until it hears from one of the listed embed_origins. Send a message when you receive liqaos:ready, as the example does. If the room has exactly one embed origin, it can answer immediately.

Example

const LIQAOS = 'https://liqaos.academito.online';
const frame = document.getElementById('room');

function send(message) {
  // Always an exact target origin, never '*'.
  frame.contentWindow.postMessage(message, LIQAOS);
}

window.addEventListener('message', (event) => {
  // Both checks, every time: the right origin, and our own iframe.
  if (event.origin !== LIQAOS || event.source !== frame.contentWindow) return;
  const m = event.data;
  if (!m || typeof m.type !== 'string') return;

  switch (m.type) {
    case 'liqaos:ready':
      // The room has loaded. Anything you send now is heard.
      send({ type: 'liqaos:compact', on: false });
      break;
    case 'liqaos:state':
      console.log('state:', m.state); // waiting, admitted, in_room, left, ended
      break;
    case 'liqaos:participant':
      console.log(m.event, m.name, m.role, m.external_id); // joined, left, waiting
      break;
    case 'liqaos:content':
      // A host shared content. Answer within 1.5 seconds with this viewer's own URL.
      send({ type: 'liqaos:content-url', key: m.key, url: m.url + '?viewer=' + encodeURIComponent(currentUserId) });
      break;
    case 'liqaos:content-stopped':
      // The content with this key is off the stage, whatever the reason: follow the real state.
      markContentStopped(m.key);
      break;
  }
});

// Host only: show a page of yours on the stage for everyone.
function shareContent() {
  send({
    type: 'liqaos:share-content',
    key: 'agenda-1',
    url: 'https://app.example.com/shared/agenda/1',
    title: 'Agenda',
    controls: false, // this page has its own stop button, so the room draws none
  });
}
function stopContent() { send({ type: 'liqaos:stop-content' }); }
function leaveRoom()   { send({ type: 'liqaos:leave' }); }

Your content on the stage

A host can show one of your pages on the stage for everyone, next to the people. The room never fetches it: each person’s own browser loads it in a frame.

  1. Your page (the one framing the room) sends liqaos:share-content with a key that identifies this content, the url and a title. Only a host’s room acts on it.
  2. The URL must be http or https and its origin must be one of your content_origins (your account’s plus the room’s). Anything else is refused and the person sees a notice.
  3. The host’s room sends the content to everyone else in the room over the media connection. People who arrive later receive it too.
  4. Before showing it, each person’s room sends liqaos:content to its own parent page. If your page answers with liqaos:content-url (same key) within 1.5 seconds, the room shows that URL instead. This is how every viewer gets a personal link, such as a URL with their own token. The answer must also be inside content_origins, or it is ignored and the shared URL is used.
  5. liqaos:stop-content removes it for everyone. Whenever content leaves the stage, for this or any other reason, each person’s room tells its own page with liqaos:content-stopped and the key. A person who is not embedded in a page of yours always sees the shared URL.

By default the host’s room draws a “Stop sharing” control. If your page has its own control, send controls: false with liqaos:share-content and send liqaos:stop-content yourself.

What the content page must allow

  • It is shown in an iframe with sandbox="allow-scripts allow-same-origin allow-forms allow-popups" and allow="fullscreen". Scripts, forms, popups and its own origin work; top-level navigation, downloads and the camera or microphone do not.
  • It must be framable by LiqaOS: do not send X-Frame-Options: DENY or SAMEORIGIN, and allow the LiqaOS origin in frame-ancestors:
Content-Security-Policy: frame-ancestors 'self' https://liqaos.academito.online
# And no X-Frame-Options: DENY or SAMEORIGIN on that page.

Browsers may treat cookies of a page shown inside another site as third-party cookies. Prefer a personal URL (the content-url answer) over a login cookie.

The whiteboard

Every room can have a whiteboard that everyone in it sees at the same moment. A host opens it from the room’s own toolbar, or your page does with liqaos:board-open. It is on by default; create a room with whiteboard: false (or ask the operator to turn the feature off for your whole account, existing rooms included) when you do not want it.

Who may draw

  • Hosts always draw, and are the only ones who open or close the board, add pages, pictures, PDF documents and text, move things, clear a page and choose who else may draw.
  • Participants watch until a host lets them draw, one person at a time, and a host can take it back at any moment. Someone who is allowed draws and takes back their own strokes only.
  • Observers only watch. They can never draw, and the server refuses it, whatever the page does.

Every one of these rules is enforced by LiqaOS on every request; the room only hides the controls a person may not use.

What is on it

  • Pages (up to 50), each with its own background, and drawings with a pen, shapes, an eraser and stickers.
  • Pictures, PDF documents (one page shown at a time, turned by the host) and text. A board holds up to 60 of these, a file may weigh up to 15 MB, and all the files of one room together up to 200 MB. A picture is re-encoded by LiqaOS, never kept as sent.
  • Files are private to the room. They are never at a public address; only a person who is in the room can read them.

Knowing about it in your page

The room sends your page liqaos:board with open: true or false whenever the board is opened or closed. Use it to make room for the board, for example by switching the room to the large layout while it is open (liqaos:compact with on: false). Your page may send liqaos:board-open and liqaos:board-close; they act only in a host’s room.

The board shares the stage with a shared screen and with shared content (liqaos:share-content): whichever arrived last is the one shown, and the earlier one comes back when it ends. Opening the board replaces shared content, and the room tells your page with liqaos:content-stopped.

How long it is kept

A room’s whiteboard (drawings and files) is kept for 30 days (the default) after the room ended or closed, then deleted for good. Nothing of it is sent to your server: webhooks do not carry drawings.

Errors you may meet

The room app handles these for you; they matter only if you read the API directly. All answer with code and a message in the language of the request (Accept-Language).

StatuscodeMeaning
403board_disabledThe room has no whiteboard.
409room_endedThe room ended or closed. Its board is closed too, for reading as well.
403not_admittedThe person has not been let into the room.
403host_onlyOnly a host may do this.
403board_read_onlyThe person may not draw.
422board_items_limit, board_pages_limit, board_file_too_big, board_room_full60 items, 50 pages, a file over 15 MB, or the room’s 200 MB of files is used up.

Webhooks

If your account has a webhook_url, LiqaOS sends a POST to it for each event below. Without a webhook_url nothing is sent. The URL is set by the operator when the account is created.

Payload

{
  "id": "01JD5R4P8A2C4E6G8J0L2N4Q6S",
  "type": "participant.admitted",
  "created_at": "2026-12-01T08:59:40Z",
  "room": {
    "id": "01JD5Q8K3Z7M2V9X4B6N1C0HTA",
    "external_id": "consult-2041"
  },
  "participant": {
    "participant_id": "01JD5QC7M1N3P5Q7R9S2T4V6WX",
    "external_id": "user-52",
    "name": "Omar Nasser",
    "role": "participant"
  }
}
FieldMeaning
idUnique id of this event. Use it to de-duplicate.
typeOne of the events below.
created_atWhen the event was created, UTC.
roomid and external_id (or null).
participantOnly for participant events: participant_id, external_id, name, role.

Events

TypeSent when
room.startedThe first person connects. The room goes back to open when it empties and can start again, so you may get it more than once for a room.
room.endedThe room is ended through /end or by a host (once per room).
participant.waitingA person asks to enter and starts waiting.
participant.admittedA host admits a waiting person. Not sent for people admitted automatically (hosts, or rooms without a waiting room).
participant.deniedA host refuses a waiting person.
participant.joinedA person connects to the room.
participant.leftA person disconnects.

participant.joined, participant.left and room.started are reported from the media server and can arrive a little after the fact. Order between different events is not guaranteed; use created_at.

Delivery and retries

  • The body is JSON; the header Content-Type is application/json.
  • Answer with any 2xx status within 10 seconds. Redirects are not followed, so a 3xx counts as a failure.
  • On any other answer, a timeout or a connection error, LiqaOS retries after 1 minute, then 5 minutes, then 30 minutes after the previous attempt. That is four attempts in all; after the last, the delivery is given up and logged on LiqaOS. There is no replay endpoint in v1.
  • A retry carries the same event id and body, with a fresh timestamp and signature.
  • Deliveries are at least once: you may receive the same event twice. Store the ids you have handled and ignore repeats.

Signature

Each request has a header:

LiqaOS-Signature: t=1796115580,v1=3f1c0b7e5a9d4c2e8b6a0f1d3c5e7a9b2d4f6081a3c5e7092b4d6f8a0c1e3a5b

Algorithm:

  1. Split the header on commas into t (Unix time in seconds) and v1 (64 hex characters).
  2. Build the string t + "." + body, where body is the raw request body exactly as received (not re-encoded JSON).
  3. Compute HMAC-SHA256 of that string with your webhook secret (whsec_…) as the key, as lower-case hex.
  4. Compare it with v1 in constant time.
  5. Reject the request when t is more than 5 minutes away from your clock. LiqaOS does not enforce a tolerance itself; 5 minutes is the recommendation, and it does not break retries because each attempt is signed with a new t.

PHP

<?php
// $secret is your webhook secret (whsec_...). Read the BODY EXACTLY as received, before any JSON decoding.
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_LIQAOS_SIGNATURE'] ?? '';

if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m)) {
    http_response_code(400); exit;
}
[, $timestamp, $signature] = $m;

if (abs(time() - (int) $timestamp) > 300) {          // replay protection: 5 minutes
    http_response_code(400); exit;
}
$expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $signature)) {            // constant-time comparison
    http_response_code(401); exit;
}

$event = json_decode($body, true);
// De-duplicate on $event['id'] here, then handle $event['type'].
http_response_code(200);

Node.js

// Express. The raw body is needed, so do not put express.json() in front of this route.
import crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.LIQAOS_WEBHOOK_SECRET; // whsec_...
const app = express();

app.post('/hooks/liqaos', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('LiqaOS-Signature') || '';
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header);
  if (!match) return res.sendStatus(400);
  const [, timestamp, signature] = match;

  // Replay protection: 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(400);

  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${timestamp}.`)
    .update(req.body)            // a Buffer: the bytes exactly as received
    .digest('hex');
  const ok =
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString('utf8'));
  // De-duplicate on event.id here, then handle event.type.
  res.sendStatus(200);
});

app.listen(3000);

Python

# Flask. request.get_data() returns the body exactly as received.
import hashlib, hmac, os, re, time
from flask import Flask, request, abort

SECRET = os.environ["LIQAOS_WEBHOOK_SECRET"]  # whsec_...
app = Flask(__name__)

@app.post("/hooks/liqaos")
def liqaos_webhook():
    body = request.get_data()
    match = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", request.headers.get("LiqaOS-Signature", ""))
    if not match:
        abort(400)
    timestamp, signature = match.groups()

    if abs(time.time() - int(timestamp)) > 300:      # replay protection: 5 minutes
        abort(400)

    expected = hmac.new(SECRET.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature):  # constant-time comparison
        abort(401)

    event = request.get_json(force=True)
    # De-duplicate on event["id"] here, then handle event["type"].
    return "", 200

Errors and limits

Every error has the shape {"code": "...", "message": "..."}; validation errors add errors.

{
  "code": "validation_failed",
  "message": "The title field is required.",
  "errors": {
    "title": ["The title field is required."]
  }
}
StatuscodeWhen
401unauthenticatedMissing, wrong or suspended API key.
404not_foundThe room does not exist or belongs to another customer; or the route does not exist.
405method_not_allowedThe route exists but not with this method.
402subscription_inactiveCreating a room or adding a participant while the subscription is suspended, cancelled, expired, absent, or past due beyond the grace period. The body carries status. See Plans and limits.
402quota_exceededCreating a room or adding a new participant after a plan that stops at its allowance has used up its participant-minutes for the month. The body carries included_minutes, used_minutes and resets_at.
409room_endedUpdating, or adding a participant to, a room that was ended.
409room_fullNot a call of yours: it is what a host’s own attempt, inside the room, gets when letting a waiting person in and no seat is left. The host’s lobby says why.
409room_closedAdding a participant after closes_at.
422validation_failedA field is missing or wrong; errors lists each field.
422external_id_takenAnother room of yours already uses that external_id (update only).
429rate_limitedToo many requests. See below.
429concurrent_rooms_limitCreating a room while as many rooms as the plan allows are live. The body carries limit. Do not confuse it with rate_limited: act on the code.

A server-side failure answers with a 5xx status; retry it with backoff. Creating a room or a participant is safe to retry, because both are keyed by external_id.

Rate limit

Each API key may make 120 requests per minute across all routes under /api/v1. Beyond that you get 429 with a Retry-After header (seconds) and the same number as retry_after in the body. Requests refused for a wrong key are not counted against anyone’s key.

{
  "code": "rate_limited",
  "message": "Too many requests.",
  "retry_after": 23
}

Plans and limits

Every account has a subscription to a plan chosen by the operator. Its terms are copied when it starts, so a later change to the plan does not change what was already sold to you. For prices, see the pricing section of the home page. Three limits can apply; any of them may be unlimited on your plan, and the operator may set a different value for your account.

LimitWhat it meansWhen it is reached
Participant-minutes a monthThe time all people spend connected, summed. A plan either stops at its allowance, or has an overage rate: then the extra minutes are billed and never refused.402 quota_exceeded on creating a room and on adding a new participant.
Meetings at the same timeRooms that have people in them right now. A scheduled or ended room is not counted.429 concurrent_rooms_limit on creating a room. The limit is checked again when the first person arrives in a room that is not live yet: if other live rooms already fill the plan, that person is refused with the same code and can try again once one has ended. A room that is already live is never refused.
People in one meetingA room admits at most the smaller of its own max_participants and the plan’s limit. Hosts are always admitted.A person arriving gets the state full, which the room page shows; a host who tries to let a waiting person in gets room_full inside the room.
HTTP 402
{ "code": "subscription_inactive", "message": "The subscription is not active.", "status": "past_due" }

HTTP 402
{ "code": "quota_exceeded", "message": "The monthly participant-minutes of the plan are used up.",
  "included_minutes": 1000, "used_minutes": 1000, "resets_at": "2026-12-01T00:00:00Z" }

HTTP 429
{ "code": "concurrent_rooms_limit", "message": "The plan allows only 2 rooms at the same time.", "limit": 2 }
  • The subscription. Creating a room or adding a participant needs a usable subscription: trialing or active, or past due within a grace period (7 days after the first unpaid due date). Otherwise the answer is 402 subscription_inactive with status set to suspended, cancelled, expired, past_due or none (no subscription at all).
  • Nothing in progress is cut. The checks apply only where something new begins: a room, a participant, a seat. A join link that was already issued still opens, and a person already inside stays inside, even after a limit is reached.
  • Re-issuing a link is not metered. Calling Add a participant again for an external_id already in the room is not a new person. Calling Create a room again with a known external_id returns the existing room and is not counted either. Both still need a usable subscription.
  • How participant-minutes are counted. Each connection of a person is one interval from joining to leaving (an open one runs up to now). The intervals of all your rooms inside the month are summed in seconds, and the total is rounded up to whole minutes once, so a person who joins four times is not charged four rounded-up minutes. The month is the calendar month counted from the day the subscription started. GET /rooms/{room}/usage shows one room’s minutes to two decimals.
  • An account block is different. If the operator blocks the account itself, your key gets 401, as for any unknown key.

Limits at a glance

ItemLimit
Requests per key120 a minute
People in a roommax_participants, 1 to 1000, default 50, and never more than the plan’s limit (hosts are always admitted)
Minutes, rooms live at onceBy plan: see Plans and limits
Per-room origins10 for embed_origins, 10 for content_origins
Join link lifetimeuntil closes_at, or 24 hours
Browser session / media ticket2 hours each, renewed by the room page
Webhook answer time10 seconds

Security checklist

  • The API key and the webhook secret stay on your server, in a secret store, out of repositories and logs. They are shown once.
  • Call the API only from your server. Never from a browser or an app.
  • A join_url is a credential for one person. Give it only to that person, do not log it, and do not put it in places others can read. It is a bearer link: whoever holds it can enter as that person while it is valid.
  • Issue links when the person is about to join, not weeks ahead. Re-issuing is cheap and kills the old link.
  • Use the least role needed: observer for people who only watch.
  • Keep embed_origins as short as you can: exact origins, https only. Never list an origin you do not control.
  • Verify the signature of every webhook, check the timestamp, de-duplicate on id, and use an HTTPS webhook_url. Answer fast and do the work afterwards.
  • In your postMessage code, check event.origin and event.source, and never send with *.
  • Make your content pages ready for being shown to many people: personal URLs, no secrets in the shared URL.
  • The join page is sent with Referrer-Policy: no-referrer and Cache-Control: no-store, because the link carries the token.

FAQ

The room shows a blank frame

The browser refused to show the page in the frame. Check, in this order: (1) the origin of the page that holds the iframe, exactly as in the address bar (scheme, host, port), is in the account’s embed_origins or in the room’s own embed_origins; (2) your own page’s Content-Security-Policy allows frame-src https://liqaos.academito.online; (3) the link is the full join_url. The browser’s console names the directive that blocked it. A link that LiqaOS does not know can only be framed by LiqaOS itself, so a mistyped token also looks blank.

The camera or microphone is refused

  • The iframe has the allow attribute from Embedding the room.
  • If your page sends a Permissions-Policy, it names https://liqaos.academito.online for camera and microphone.
  • Your page is on HTTPS.
  • The person did not block the camera for your site in the browser, and no other program is holding the device.
  • Observers have no camera or microphone by design.

The join link expired

The link is valid until the room’s closes_at (or 24 hours from issue if the room has none). Call Add a participant again with the same external_id for a new link. If the room itself has closed or ended, the person sees that instead, and you need a new room (or PATCH a later closes_at if the room was only past its time and not ended).

The person waits and nobody lets them in

With a waiting room, a host must admit them from inside the room, so a host has to be present. Add the host as host, or create the room with waiting_room: false.

The room says it is not open

The current time is before opens_at. The page waits and enters by itself when the room opens.

The room says it is full

The number of people connected, or admitted in the last 10 minutes, has reached the room’s max_participants or the plan’s limit on people in one meeting, whichever is smaller. Raise max_participants with PATCH, or ask the operator about the plan. Hosts are never refused. A host who tries to let a waiting person in when no seat is free is told the meeting is full.

I get 402 subscription_inactive

Your subscription cannot start anything new. Read status: past_due means an invoice is overdue beyond the grace period; suspended, cancelled and expired mean the subscription was stopped or ended; none means the account has no subscription. Contact the operator. Rooms and links you already have keep working.

I get 402 quota_exceeded

Your plan stops at its monthly participant-minutes and they are used up. The answer says how many were included and used, and resets_at is when the allowance starts over. Ask the operator for a plan with more minutes, or one that bills the extra. People already in rooms are not removed.

I get 429 concurrent_rooms_limit

As many rooms as your plan allows already have people in them. Create the room later, or ask the operator about the plan. A room that is already live is never refused.

I get 429 rate_limited

You are over 120 requests a minute for this key. Wait for Retry-After seconds. Do not poll GET /rooms/{room}/participants for presence; use the webhooks.

Webhooks do not arrive

Check that your account has a webhook_url (ask the operator), that it answers 2xx without redirecting and within 10 seconds, and that your firewall lets LiqaOS in. Failed deliveries are retried at 1, 5 and 30 minutes and then dropped. If they began failing right after the operator rotated your webhook secret, update the secret in your verification code.

I lost my API key or the webhook secret

They cannot be shown again. Ask the operator for a new key (and to revoke the lost one), or to rotate the webhook secret; the new value is shown once.

My signature check always fails

Almost always the body: sign the raw bytes as received, not the re-serialised JSON, and make sure no middleware has parsed or trimmed them. The signed string is t + "." + body.

My page does not receive the room’s messages

Compare the exact origin: event.origin must equal https://liqaos.academito.online. Listen before the iframe loads, and check event.source is the iframe’s window.

My liqaos:* messages to the room are ignored

Use the exact LiqaOS origin as targetOrigin, and make sure your page’s origin is one of the room’s embed_origins. share-content and stop-content act only in a host’s room, and the URL must be inside content_origins.

Not available in v1

  • Recording of any kind. Media is not stored.
  • Admitting, denying or muting people through the API; hosts do these inside the room.
  • Listing or deleting rooms, and listing your own rooms.
  • Issuing, rotating or revoking API keys, rotating the webhook secret, and changing the webhook URL, the account’s origins or the plan through the API; the operator does these on request.
  • Re-sending a webhook that was given up.
  • Pagination.