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
| Role | What the person can do |
|---|---|
host | Is 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. |
participant | Publishes camera, microphone and screen, and sends data. Enters through the waiting room when the room has one. |
observer | Watches 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 examplehttps://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:401unauthenticated. - 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 nodatawrapper. - Times are ISO-8601 instants. LiqaOS answers in UTC with a trailing
Z(2026-12-01T10:00:00Z). Always send an explicit offset orZyourself. - Ids (
id,participant_id) are 26-character ULIDs. Treat them as opaque strings. - Every refusal has a machine-readable
codeand amessage. Act on thecode; 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| Field | Type | Required | Rules |
|---|---|---|---|
title | string | yes | Up to 255 characters. |
external_id | string or null | no | Up to 191 characters. Your own id for the room, unique per customer. See below. |
opens_at | ISO-8601 or null | no | Before this instant the room answers not_open. See Room window. |
closes_at | ISO-8601 or null | no | Must be later than opens_at when both are set. After this instant the room answers closed, and join links stop at this instant. |
waiting_room | boolean | no | Default true. |
whiteboard | boolean | no | Whether 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_participants | integer | no | 1 to 1000. Default 50. |
metadata | JSON object or null | no | Anything you want back later. LiqaOS does not read it. |
embed_origins | array of origins | no | Up to 10, each up to 255 characters, each scheme://host[:port]. Added to your account’s own list for this room only. |
content_origins | array of origins | no | Same 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.
| Field | Meaning |
|---|---|
id | LiqaOS id of the room (ULID). |
external_id | Yours, or null. |
title, waiting_room, whiteboard, max_participants, metadata | As stored. |
opens_at, closes_at | UTC, or null. |
embed_origins, content_origins | This room’s own lists only, not your account’s. |
status | scheduled 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_at | When the first person connected, or null. |
ended_at | When the room was ended through /end or by a host, or null. It stays null for a room that merely passed closes_at. |
created_at | UTC. |
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_atalso moves the expiry of every participant’s join link to the new time. Setting it tonullgives every link 24 hours from now. closes_atis checked againstopens_atas it will be after the change, including a value you did not send.- A room whose
closes_atpassed but that nobody ended can still be updated, which is how you extend it. - Changing
external_idto one that another room of yours already uses fails with422 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}/endNo 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| Field | Type | Required | Rules |
|---|---|---|---|
external_id | string | yes | Up to 191 characters. Your id for this person. One person per external_id in a room. |
name | string | yes | Up to 255 characters. Shown to the others in the room. |
role | string | yes | host, participant or observer. |
avatar_url | URL or null | no | A valid URL, up to 2048 characters. |
Response: 201 the first time, 200 when this external_id already exists in the room.
| Field | Meaning |
|---|---|
participant_id | LiqaOS id of the person in this room. |
join_url | https://liqaos.academito.online/j/<token>. The token exists only in this response: LiqaOS stores a hash. |
expires_at | When 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}/participantsReturns 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
}
]
| State | Meaning |
|---|---|
invited | Has a link; has not asked to enter. |
waiting | Asked to enter; a host has not answered. |
admitted | Allowed in (by a host, or automatically), not connected yet. An admitted person who never connects stops holding a seat after 10 minutes. |
denied | Refused by a host. Final for that link. |
in_room | Connected now. joined_at is set. |
left | Was 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.
| Moment | What a person who opens their link sees |
|---|---|
Before opens_at | The 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_at | Normal entry: waiting room, capacity and admission apply. |
After closes_at | The room is closed (state closed). No one enters. status reads ended. New participants are refused with 409 room_closed. |
| After an explicit end | State ended. |
| Room full | State 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_atmoves every link’s expiry with it. - An expired link (while the room is still running) answers
410 token_expiredand 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 sendsframe-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 withframe-srcordefault-src, must allowhttps://liqaos.academito.online. - Your
Permissions-Policy, if you send one, must hand the devices to LiqaOS, or the browser blocks them before the iframe’sallowis 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:.
| Message | Fields | When |
|---|---|---|
liqaos:ready | none | The 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:state | state | waiting (asked to enter), admitted (let in, connecting), in_room (connected), left (the person left), ended (the room ended or closed). |
liqaos:participant | event, name, role, external_id | event 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:content | key, url | A host shared content (see Your content on the stage). You may answer with liqaos:content-url. |
liqaos:content-stopped | key | The 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:board | open (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
| Message | Fields | Effect |
|---|---|---|
liqaos:share-content | key, 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-url | key, url | Answer to liqaos:content: this person’s own URL for the same content. |
liqaos:stop-content | none | Host only. Removes the content from the stage. |
liqaos:leave | none | The person leaves the room. |
liqaos:compact | on (boolean) | Switches to the small floating layout (true) or back (false). |
liqaos:board-open | none | Host 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-close | none | Host 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.sourceis the parent window), and only when that page’s origin is the one the browser reports for the parent and, if the room hasembed_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
*(exceptliqaos:ready). - In your page, check
event.origin === 'https://liqaos.academito.online'andevent.source === iframe.contentWindow, and send with that exact origin astargetOrigin. - 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 listedembed_origins. Send a message when you receiveliqaos: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.
- Your page (the one framing the room) sends
liqaos:share-contentwith akeythat identifies this content, theurland atitle. Only a host’s room acts on it. - The URL must be
httporhttpsand its origin must be one of yourcontent_origins(your account’s plus the room’s). Anything else is refused and the person sees a notice. - The host’s room sends the content to everyone else in the room over the media connection. People who arrive later receive it too.
- Before showing it, each person’s room sends
liqaos:contentto its own parent page. If your page answers withliqaos:content-url(samekey) 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 insidecontent_origins, or it is ignored and the shared URL is used. liqaos:stop-contentremoves it for everyone. Whenever content leaves the stage, for this or any other reason, each person’s room tells its own page withliqaos:content-stoppedand thekey. 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"andallow="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: DENYorSAMEORIGIN, and allow the LiqaOS origin inframe-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).
| Status | code | Meaning |
|---|---|---|
| 403 | board_disabled | The room has no whiteboard. |
| 409 | room_ended | The room ended or closed. Its board is closed too, for reading as well. |
| 403 | not_admitted | The person has not been let into the room. |
| 403 | host_only | Only a host may do this. |
| 403 | board_read_only | The person may not draw. |
| 422 | board_items_limit, board_pages_limit, board_file_too_big, board_room_full | 60 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"
}
}
| Field | Meaning |
|---|---|
id | Unique id of this event. Use it to de-duplicate. |
type | One of the events below. |
created_at | When the event was created, UTC. |
room | id and external_id (or null). |
participant | Only for participant events: participant_id, external_id, name, role. |
Events
| Type | Sent when |
|---|---|
room.started | The 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.ended | The room is ended through /end or by a host (once per room). |
participant.waiting | A person asks to enter and starts waiting. |
participant.admitted | A host admits a waiting person. Not sent for people admitted automatically (hosts, or rooms without a waiting room). |
participant.denied | A host refuses a waiting person. |
participant.joined | A person connects to the room. |
participant.left | A 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-Typeisapplication/json. - Answer with any 2xx status within 10 seconds. Redirects are not followed, so a
3xxcounts 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
idand 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:
- Split the header on commas into
t(Unix time in seconds) andv1(64 hex characters). - Build the string
t + "." + body, wherebodyis the raw request body exactly as received (not re-encoded JSON). - Compute HMAC-SHA256 of that string with your webhook secret (
whsec_…) as the key, as lower-case hex. - Compare it with
v1in constant time. - Reject the request when
tis 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 newt.
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."]
}
}
| Status | code | When |
|---|---|---|
| 401 | unauthenticated | Missing, wrong or suspended API key. |
| 404 | not_found | The room does not exist or belongs to another customer; or the route does not exist. |
| 405 | method_not_allowed | The route exists but not with this method. |
| 402 | subscription_inactive | Creating 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. |
| 402 | quota_exceeded | Creating 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. |
| 409 | room_ended | Updating, or adding a participant to, a room that was ended. |
| 409 | room_full | Not 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. |
| 409 | room_closed | Adding a participant after closes_at. |
| 422 | validation_failed | A field is missing or wrong; errors lists each field. |
| 422 | external_id_taken | Another room of yours already uses that external_id (update only). |
| 429 | rate_limited | Too many requests. See below. |
| 429 | concurrent_rooms_limit | Creating 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.
| Limit | What it means | When it is reached |
|---|---|---|
| Participant-minutes a month | The 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 time | Rooms 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 meeting | A 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_inactivewithstatusset tosuspended,cancelled,expired,past_dueornone(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_idalready in the room is not a new person. Calling Create a room again with a knownexternal_idreturns 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}/usageshows 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
| Item | Limit |
|---|---|
| Requests per key | 120 a minute |
| People in a room | max_participants, 1 to 1000, default 50, and never more than the plan’s limit (hosts are always admitted) |
| Minutes, rooms live at once | By plan: see Plans and limits |
| Per-room origins | 10 for embed_origins, 10 for content_origins |
| Join link lifetime | until closes_at, or 24 hours |
| Browser session / media ticket | 2 hours each, renewed by the room page |
| Webhook answer time | 10 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_urlis 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:
observerfor people who only watch. - Keep
embed_originsas short as you can: exact origins,httpsonly. Never list an origin you do not control. - Verify the signature of every webhook, check the timestamp, de-duplicate on
id, and use an HTTPSwebhook_url. Answer fast and do the work afterwards. - In your
postMessagecode, checkevent.originandevent.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-referrerandCache-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
allowattribute from Embedding the room. - If your page sends a
Permissions-Policy, it nameshttps://liqaos.academito.onlineforcameraandmicrophone. - 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.