Create a room
const url = 'https://collab.work.optidata.cloud/api/rooms/new';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"Weekly sync","description":"Product team weekly meeting.","room_slug":"weekly-sync","settings":{"max_users":20,"join_mode":"authenticated_only_must_request"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://collab.work.optidata.cloud/api/rooms/new \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "Weekly sync", "description": "Product team weekly meeting.", "room_slug": "weekly-sync", "settings": { "max_users": 20, "join_mode": "authenticated_only_must_request" } }'Creates a meeting room owned by the caller and returns it with its
settings. Share usage_url with the participants.
- Without a
name, the room is named after itsroom_slug, or after itshash. - With a
room_slug, the room also gets a permanent link (custom_hash) made of your company’s prefix and the slug. A slug already in use in your company answers409. settings.max_usersdefaults to your plan’s participant limit andsettings.join_modeto your company’s Call settings.
Authorizations
Section titled “Authorizations”Request Body
Section titled “Request Body”object
Room name. Defaults to room_slug, then to the room’s hash.
Address of the image shown as the room’s icon. Defaults to a camera icon.
Gives the room a permanent link. The custom_hash is your company’s
prefix followed by this slug; it must be unique in your company.
object
Maximum number of people in the room at once. Defaults to your plan’s limit.
Who may enter the room and whether they must ask first:
automatic— anyone with the link enters straight away; guests without an account appear as “Guest”.no_request— anyone with the link enters without asking; guests type their name first.unauthenticated_must_request— signed-in Optiwork users enter; guests type their name and ask to join.authenticated_only_no_request— only signed-in Optiwork users, without asking; guests are turned away.authenticated_only_must_request— only signed-in Optiwork users, and they ask to join; guests are turned away.any_must_request— everyone asks to join; guests type their name first.
Examples
Room with a permanent link
{ "name": "Weekly sync", "description": "Product team weekly meeting.", "room_slug": "weekly-sync", "settings": { "max_users": 20, "join_mode": "authenticated_only_must_request" }}Ad-hoc room with defaults
{}Responses
Section titled “ Responses ”The new room.
object
Internal id. Address the room by hash or custom_hash, never by this id.
Your company’s id.
The room’s identifier and link.
The permanent-link identifier, when the room has one.
The user who created the room.
on_site for rooms holding an uploaded in-person meeting; null or virtual for video meetings.
Whether AI meeting notes are on for this room.
Whether participants are prevented from turning AI notes off.
The room’s link, to share with participants.
object
Maximum number of people in the room at once.
Whether people without an Optiwork account may join.
Who may enter the room and whether they must ask first:
automatic— anyone with the link enters straight away; guests without an account appear as “Guest”.no_request— anyone with the link enters without asking; guests type their name first.unauthenticated_must_request— signed-in Optiwork users enter; guests type their name and ask to join.authenticated_only_no_request— only signed-in Optiwork users, without asking; guests are turned away.authenticated_only_must_request— only signed-in Optiwork users, and they ask to join; guests are turned away.any_must_request— everyone asks to join; guests type their name first.
Present on getRoom and listRooms.
One person’s presence in a room.
object
null for guests without an Optiwork account.
admin for the room owner, moderator for co-hosts, guest for everyone else.
Details a guest gave when joining.
object
Where the guest gets the meeting summary. Shown only on your own participation, or to the room’s owner, its moderators and company super-administrators.
State of the person’s request to join, in rooms where joining must be requested.
object
The user’s display preferences (language, theme, time zone).
object
The person who made the recording.
creating,started— being recorded.stopped_locally,pending,processing— recorded; being saved and processed.stopped— done; the transcript follows when ready.failed— interrupted; seestartRecordingRecovery.
manual when a participant pressed record; automatic for the audio
recorded to produce AI meeting notes; audio_only_sibling for the
audio track kept next to a manual recording.
Whether a copy was saved to Optiwork Drive.
The public link, when the recording has one.
Address of the recording page in Optiwork.
Technical details of the recording. Its content may change; do not rely on it.
object
The user’s display preferences (language, theme, time zone).
Who was in the meeting while it was recorded.
One person’s presence in a room.
object
null for guests without an Optiwork account.
admin for the room owner, moderator for co-hosts, guest for everyone else.
Details a guest gave when joining.
object
Where the guest gets the meeting summary. Shown only on your own participation, or to the room’s owner, its moderators and company super-administrators.
State of the person’s request to join, in rooms where joining must be requested.
object
The user’s display preferences (language, theme, time zone).
People and groups the recording is shared with.
object
The public-link setting, when the recording has a public link.
object
AI summary of the meeting.
AI key points, as a JSON-encoded string: an array of
{ "title", "items": [string] } sections.
The full transcript as produced by the speech-to-text engine (utterances, words, speakers, timings). Its exact shape depends on the engine and may change.
Examples
{ "id": 12226, "room_settings_id": 12220, "cuid": "7f3c2a10-5b8e-4d21-9c6a-0e4f1b2d3c4a", "name": "Weekly sync", "description": "Product team weekly meeting.", "icon_url": "https://collab.work.optidata.cloud/images/pages/bs-icon-camera-video.svg", "hash": "a3050cd3-5921-4153-b90a-owt42-e94de63c7b15", "custom_hash": "owt42-acme-weekly-sync", "owner_uuid": "2d9e8f70-1a3b-4c5d-8e9f-a0b1c2d3e4f5", "conference_type": null, "created_at": "2026-10-19T14:40:53.000000Z", "updated_at": "2026-10-19T14:40:53.000000Z", "usage_url": "https://collab.work.optidata.cloud/rooms/a3050cd3-5921-4153-b90a-owt42-e94de63c7b15", "settings": { "id": 12220, "room_id": 12226, "max_users": 20, "is_guests_allowed": true, "join_mode": "authenticated_only_must_request", "created_at": "2026-10-19T14:40:53.000000Z", "updated_at": "2026-10-19T14:40:53.000000Z" }}No authentication key was sent, or it is malformed.
Authentication failures use an error key rather than message.
object
Examples
No bearer token sent
{ "error": "JWT passport exception: Missing bearer token in request"}The permanent link (room_slug) is already used by another room of your company.
An error raised by the application’s own rules.
object
What went wrong.
The HTTP status, repeated.
What to do about it, when there is a hint.
Examples
{ "error": "Link already exists", "status": 409, "help": "This link has already been taken. Please, try another name"}The authentication key is expired or not recognised. Get a fresh one and retry.
Authentication failures use an error key rather than message.
object
Examples
{ "error": "JWT passport expired: Passport expired"}The body failed validation.
object
The first validation message.
Validation messages keyed by field name.
object
Examples
{ "message": "The selected join mode is invalid.", "errors": { "settings.join_mode": [ "The selected join mode is invalid." ] }}