API Reference

Return the current month's usage counters together with your plan's monthly limits as one flat object. Use for programmatic monitoring or billing alert automation. Compare each counter against its matching monthly_* limit (-1 means unlimited). Note: large counters are returned as JSON strings (BIGINT-backed) — parse with Number() before comparing.

For apps already using Firebase Auth. The client sends its short-lived Firebase ID token in the Authorization header — HyperBabel verifies it against Google's JWKS and mints a customer JWT for the same end-user. Register your Firebase project ID in the Console (Dashboard → Customer Auth → Firebase Projects) before calling. external_user_id, display_name, and email are auto-extracted from the verified token.

Mint a (access_token, refresh_token) pair scoped to one of your end-users. Server-to-server only — never call from a mobile or browser app. external_user_id is your stable opaque identifier (UUID recommended).

preferred_lang_cd is used to seed the user's preferred language on their first token issuance only. On subsequent calls for an existing user, the value stored in HyperBabel is preserved — sending a different code does not overwrite the user's chosen language. To update it explicitly, use PATCH /api/v1/customer/users/me from the client app.

Rotate a JWT pair using its refresh token. Safe to call directly from the client app — the refresh token in the body authenticates the request, no Authorization header needed. Old refresh token is revoked atomically; new pair has a fresh session_id.

Invalidate every active session for one external_user_id. Global propagation under 60 seconds. Use on log-out-everywhere, password-changed, or abuse signals.

Verifies the customer JWT and returns the identity it represents, plus the user's directory profile fields. Useful for client-side debugging and 'who am I' UX.

Create a chat room. room_type: '1to1' | 'group' | 'open'. For 1:1, pass members with 1 user_id. For group, pass members array. Returns already_exists:true if a 1:1 between those users already exists.

Get all rooms the user is a member of, plus joinable open rooms. Pass user_id as a query param. Pass lang (e.g. 'ko', 'ja') to enable automatic description translation — translations are cached in the DB on first request so subsequent calls cost nothing extra. The response includes description_translated alongside the original description when a translation is available. Each entry in rooms also embeds last_message — the most recent message in that channel (or null if empty) — so a chat-list UI can render previews without a follow-up call per room. Deleted messages are returned with deleted_at set so the client can render a 'Message deleted' placeholder.

Get room details including full member list with roles.

Set a custom display name for the room (per-user). Each member can have their own name for the room.

Set or update the description for an open room (owner only). The description is visible in the open room list, helping users understand the room's purpose before joining. Pass null to clear.

Join an open room using its 8-character invite code — no room ID required. How to get the code: open the chat room → click 🛡️ Members in the header → copy the Invite Code, or click 📋 Copy Link which generates a shareable URL like /join?code=a1b2c3d4 — extract the code param. ⚠️ user_id does NOT need to be pre-registered in HyperBabel — pass your own app's user identifier directly. Idempotent (safe to call multiple times). Banned users get 403. Full rooms get 403 room_full. On first join, broadcasts 'Yujin joined the room' system message to all members in real time.

Join an open (public) room by room ID. Banned users cannot rejoin. Idempotent — safe to call on re-entry. Broadcasts a system message 'X joined the room' to all current members on a genuine first join, plus a structured `room.member_changed` realtime event with action='joined' so SDK clients can patch their member list without re-fetching.

Remove a user from a room. Removes membership and custom name. For open rooms, the user can rejoin later using the room ID or invite code. Broadcasts a system message 'X left the room' to all remaining members, plus a structured `room.member_changed` realtime event with action='left'. Customer-JWT callers may only leave as themselves — passing another user's user_id returns 403 forbidden.

Mark all messages in the room as read for a user. Resets the unread_count to 0 for that user. Also broadcasts a real-time read_receipt event to the room channel so the sender's client can instantly update the message status icon from ✓ (sent) to ✓✓ (read). Customer-JWT callers may only mark read as themselves — passing another user's user_id returns 403 forbidden.

Send a message to a room. message_type: 'text' | 'image' | 'video' | 'audio' | 'file' | 'location' | 'contact'. Supports reply threading via reply_to. Returns 403 with code 'blocked_by_recipient' if a recipient has blocked the sender — handle this by informing the user they cannot send messages to this room. Other 403s: 'forbidden' (the sender is not a member of the room, or a customer-JWT caller passed a sender_id that is not their own user id), 'room_frozen' (the room is frozen and the sender is not owner/sub_admin), and 'banned' (the sender is banned from the open room). Sandbox traffic (test hb_test_* keys or the Console Sandbox) skips the membership and frozen checks, so demo flows can send without formal membership.

Get messages for a room with cursor-based pagination (newest first). Pass cursor — the next_cursor from the previous response — to load older messages. Results default to the last 3 months; use created_at_gte / created_at_lte to change the time range. The response also includes read_statuses for all members — use these to render delivery/read icons (✓ sent, ✓✓ read, N unread count for group rooms). Customer-JWT callers must be a member of the room — non-members get 403 forbidden (org API keys are unrestricted within the org).

Ban a user from a room. Only room owner or sub_admin can ban. Banned users are removed from membership and cannot rejoin. Publishes a `room.member_changed` realtime event with action='banned' so the banned user's client can navigate them out and other members can update their member list instantly.

Lift a ban for a user. Only owner or sub_admin can unban. Publishes a `room.member_changed` realtime event with action='unbanned'. Note: the unbanned user must call POST /join to rejoin — unban only removes the bar.

List all ban records for a room, most recent first. Includes both active bans and lifted (unbanned) records — check is_active to distinguish. Useful for rendering a moderation history or a 'banned users' admin panel.

Promote a member to sub_admin role. Only the room owner can promote. Maximum 10 sub_admins per room. Publishes a `room.member_changed` realtime event with action='promoted' and new_role='sub_admin' so client UIs can refresh role badges live.

Demote a sub_admin back to member. Only the room owner can demote (owner_id is required and validated). Publishes a `room.member_changed` realtime event with action='demoted' and new_role='member' so client UIs refresh role badges live. No-op if the target is not currently a sub_admin.

Add one or more users to a group room. Only the room owner or a sub_admin can add members (actor_id is validated) — group rooms only (1:1 and open rooms are rejected). Idempotent per user: users who are banned, already members, or over the room's member capacity (set from your plan's group member limit at creation) are not added — they are reported in skipped with a reason instead of failing the whole call. Each successful add broadcasts a `room.member_changed` realtime event with action='joined' and writes an 'X was added to the room' system message.

Get paginated member list for a room, ordered by role (owner → sub_admin → member). Supports page/limit pagination and partial name search.

Soft-delete a message. Sets deleted_at — the message is excluded from getMessages responses. Only the original sender, room owner, or sub_admin can delete.

Edit a text message. Only the original sender can edit. Only text type messages are editable. The original content is preserved in original_content for audit trail. edited_at is set automatically.

Mute push notifications for a room. Omit duration_minutes for indefinite mute.

Remove mute from a room for a user.

Check whether a user has muted a room and until when.

Freeze a room so that only the owner and sub_admins can send messages. Only owner or sub_admin can freeze. Publishes a `room.updated` realtime event so all connected clients flip the room into frozen mode (input becomes read-only) without a re-fetch.

Unfreeze a room to restore normal messaging for all members. Publishes a `room.updated` realtime event so connected clients re-enable the message input immediately.

Pin a message to the top of the room. Only 1 pinned message per room at a time — pinning a new message automatically replaces the existing pin. Supports all message types (text, image, file, video, audio, location, contact) except system and video_call messages. Permission: 1:1 rooms — any member; group / open rooms — owner or sub_admin only.

Remove the currently pinned message from the room. Permission: 1:1 rooms — any member; group / open rooms — owner or sub_admin only.

Search messages in a room using high-performance full-text search. Always provide created_at_gte + created_at_lte to enable indexing optimizations — max range 6 months, defaults to last 6 months. Results include a highlight field with matched terms wrapped in <mark> tags. Query syntax: spaces = AND, quotes = phrase match.

Broadcast a typing event to eligible room members via the real-time channel. HyperBabel applies per-user send/receive preferences (configurable via the Typing Prefs API) and only publishes when at least one member has receive enabled. Supported for: 1:1 rooms, and group rooms with ≤ 4 members. Self-chat rooms are automatically skipped. Recommended: call when the user starts typing, throttled to once every 2 seconds. Recipients should auto-clear the indicator after 3 seconds of no new events.

Returns each member's per-room typing indicator preferences (send and receive). If a member has not yet configured their preferences, both fields default to true (fail-open policy — typing indicators are ON by default unless explicitly disabled).

Save or update the calling user's per-room typing indicator preferences. Uses UPSERT semantics — safe to call on every room entry. send_enabled controls whether this user's typing events are published. recv_enabled controls whether this user receives others' typing events. Defaults are true (fail-open) — both indicators are ON unless the user explicitly disables them.

Create a new chat channel. channel_type: 'public' | 'private' | 'group'. max_members defaults to 100.

List all channels belonging to your organization. Optionally filter by channel_type.

Send a message to a channel. message_type: 'text' | 'image' | 'file' | 'system' | 'location' | 'contact' | 'video'. For file messages, set content to the file URL from the Storage API and include metadata.file. Note: sender_id must match ^[a-zA-Z0-9_-]+$ (letters, digits, underscore, hyphen).

Retrieve paginated message history using cursor-based pagination. Use cursor from the previous response to load the next page. Results are ordered newest-first.

Translate one or many messages to a target language in a single request. Pass message_ids: [single_id] to translate one message; the same endpoint covers both single and batch use cases. Up to 100 messages per call. Cached translations (per-message JSONB) are returned without re-billing; only cache misses incur translate_chars usage.

Add an emoji reaction to a message. Each user can react once per emoji per message.

Remove a previously added reaction from a message.

Mark all messages in a channel as read up to the current time for a given user. Updates the unread count to 0.

Soft-delete a message. Sets deleted_at — the message is excluded from all subsequent getMessages responses. Only the sender, or an admin who has permission, can delete.

Edit a text message. Only the original sender can edit. Only text type messages are editable. The original content is saved in original_content for audit. edited_at is set automatically.

Search messages using high-performance full-text search. Always provide created_at_gte + created_at_lte to enable indexing optimizations — max range 6 months, defaults to last 6 months. Results include a highlight field with matched terms wrapped in <mark> tags.

Broadcast a typing event via the real-time channel. No DB storage — fully stateless. Call with is_typing: true when the user starts typing, and is_typing: false when they stop or send a message.

Get all reply messages for a parent message (reply_to = messageId). Ordered oldest-first. Supports cursor pagination. created_at_gte defaults to the parent message's created_at automatically.

Call every 30 seconds to stay marked as online. If no heartbeat is received for 90 seconds, the user is automatically considered offline. **Billing.** Each unique (org_id, current_minute, user_id) triggers +1 `connection_min` in the monthly rollup (server-side per-minute dedup — heartbeats more frequent than 1/min are absorbed without double-counting). Heartbeats slower than 1/min may miss minute buckets. Mobile demos auto-pause the heartbeat when the app backgrounds (JS runtime suspension / Swift Task suspension / Compose lifecycle cancellation).

Explicitly set a user's status. Useful for manual away/dnd modes.

Get presence status for up to 100 users at once. Users not found in presence table are returned as offline.

Block a user globally within the org. Once blocked, any message the blocked user sends to a shared room is rejected server-side with 403 blocked_by_recipient. Sandbox requests skip this check. Errors: 400 invalid_request (blocker_id/blocked_id missing, or attempting to block yourself); 403 forbidden (customer-JWT callers may only block as themselves — blocker_id must be their own user id).

Remove a block between two users. Errors: 400 invalid_request (blocker_id/blocked_id missing); 403 forbidden (customer-JWT callers may only remove their own block rows).

Get the list of user IDs that userId has blocked. Block lists are private: customer-JWT callers may only read their own list — requesting another user's returns 403 forbidden (org API keys keep full access for support/moderation tooling).

Register a device token. If the same token already exists for this user, updated_at is refreshed.

Remove a device token. Call this on logout or when the token is refreshed.

Get all registered device tokens for a user.

Allocate a media channel and issue an RTC token per participant. The response is the only place tokens are returned — they are not retrievable later (use /renew-token to refresh). **Declared quality.** `quality` is `'hd'` (default) | `'fhd'` | `'2k'` | `'2k_plus'` and decides which bucket the session's user-minutes are billed into (`hd_video_mins` / `fhd_video_mins` / `k2_video_mins` / `k2plus_video_mins`). It is fixed at creation — to change tiers, end the session and create a new one. Media flows directly between your app and our infrastructure, so we cannot observe the real resolution: declaring it accurately is a contractual obligation, and group calls are metered on AGGREGATE received resolution (a 4-party call at 720p per stream already sits above the 1:1 HD ceiling).\n\n**Optional self-check — `publish_resolution`.** Send it as `{ width: 1280, height: 720 }` — the resolution this session will actually publish **at this participant count** (not your camera's maximum) and we will check your declaration for you. Each participant receives every other stream, so we multiply by `participants` − 1. We add that up and compare it with `quality`; if the sum lands in a higher tier the response carries a `quality_warning` string. The call still succeeds and billing still follows `quality` — the field exists because the most common billing surprise is an honest 720p declaration on a group call, not a false one. If your app lowers the resolution as people join, send the value for the size you are joining at. **Participant cap.** `participants` may hold up to 4 entries on plans that include group video (once a dedicated realtime project is provisioned); otherwise the cap is 2 (1:1). Sandbox (`hb_test_*`) keys always get the full cap — sandbox traffic is not billed. **Billing.** Minutes are counted per participant from their join time to session end, so a 10-minute call between two people records 20 user-minutes. Sandbox sessions are audit-logged but excluded from the monthly rollup, and they auto-end after 10 minutes.

Initiate a 1:1 or group video call linked to a chat room. Generates RTC tokens, sends CALL_INVITE signals, records a call_started system message. Declare the billing resolution tier with `quality`: `'hd'` (default) | `'fhd'` | `'2k'` | `'2k_plus'`. The value is persisted on the session row and decides which bucket the call's user-minutes land in (`hd_video_mins` / `fhd_video_mins` / `k2_video_mins` / `k2plus_video_mins`). It cannot be changed mid-session — end the session and create a new one to switch tiers. Declaring the tier your app actually transmits and receives is a contractual obligation; on group calls providers meter by AGGREGATE received resolution, so a multi-party call can sit a tier above the same per-stream resolution in 1:1.\n\n**Optional self-check — `publish_resolution`.** Send it as `{ width: 1280, height: 720 }` — the resolution this session will actually publish **at this participant count** (not your camera's maximum) and we will check your declaration for you. Each participant receives every other stream, so we multiply by the participant count − 1. We add that up and compare it with `quality`; if the sum lands in a higher tier the response carries a `quality_warning` string. The call still succeeds and billing still follows `quality` — the field exists because the most common billing surprise is an honest 720p declaration on a group call, not a false one. If your app lowers the resolution as people join, send the value for the size you are joining at.

Record call acceptance. Marks participant status as active. The accepting user joins the RTC media channel using their rtc_token.

Record a call rejection. Reason: "declined" | "busy" | "missed". A CALL_REJECT or CALL_BUSY signal is sent to the caller via HyperBabel Realtime.

Either participant calls /leave when they're done. When active participants drop to 1 or below, the backend automatically marks the session ended, broadcasts call.ended, and records the call_ended chat message with duration. This is the recommended ending pattern for room-scoped 1:1 calls — it works for both caller and callee without requiring host-only permission. **Billing.** When this call ends the session (last active participant left), it writes the call's user-minutes into the bucket for `session.quality` (`hd_video_mins` / `fhd_video_mins` / `k2_video_mins` / `k2plus_video_mins`) and bumps `api_calls`. Minutes are user-minutes — a 10-minute call between two people records 20. Sandbox-environment sessions skip the monthly rollup. Customer-JWT-authenticated callers (Firebase Direct Exchange mobile apps) are metered identically to API-key callers — this route was the critical fix path for ensuring customer-JWT video calls get billed.

Forcefully terminate the session for ALL participants. Permission gate: only the original caller, the room owner, or a sub_admin can call this. Regular participants should use /leave instead — calling /end returns 403 forbidden. Useful for moderators dismissing a runaway group call. **Billing.** Same metering as /leave — records user-minutes into the bucket for `session.quality` (`hd_video_mins` / `fhd_video_mins` / `k2_video_mins` / `k2plus_video_mins`) plus an `api_calls` bump. Sandbox skipped from monthly. Customer-JWT and API-key callers metered identically.

Leave a group video call without ending the session for others. If active participants drop to 1 or below, the session auto-ends and call.ended is published.

Check if a chat room has an ongoing video call. Show a 'Join ongoing call' banner instead of 'Start call' when active=true.

Join an in-progress group call. Generates a new RTC token. If the user previously left, their status is restored to 'active'. Returns 400 if session is already ended. **Billing tier is not set here.** The session's `quality` was fixed when it was created and cannot be changed by joining — to bill at a different tier, end the session and create a new one. Joining a call whose plan does not allow more participants returns `409 call_full`.

Mint a fresh RTC token for the current user's participant slot in the room's active session. Pair this with the media SDK's 'token will expire' callback — the issued RTC tokens last 1 hour, so calls that exceed that (or that get re-joined after a long pause) will otherwise silently drop. The endpoint does not write to the session — only the token is regenerated, with the same uid + channel + publisher role. Returns 403 forbidden if the caller is not a participant of the session, 404 if no active session exists.

Create a new live stream session and generate an RTC publisher token for the host. Optionally provide host display info (name, profile image, preferred language) for rich stream UI. Declare the billing resolution tier with `quality`: `'hd'` (default) | `'fhd'` | `'2k'` | `'2k_plus'`. The value is persisted on the session row and decides which bucket the stream's user-minutes land in (`hd_stream_mins` / `fhd_stream_mins` / `k2_stream_mins` / `k2plus_stream_mins`). It cannot be changed mid-session.\n\n**Optional self-check — `publish_resolution`.** Send it as `{ width: 1280, height: 720 }` — the resolution this session will actually publish **at this participant count** (not your camera's maximum) and we will check your declaration for you. A viewer subscribes to the host stream only, so for a broadcast the aggregate is simply the host resolution itself — no multiplication. We add that up and compare it with `quality`; if the sum lands in a higher tier the response carries a `quality_warning` string. The call still succeeds and billing still follows `quality` — the field exists because the most common billing surprise is an honest 720p declaration on a group call, not a false one. If your app lowers the resolution as people join, send the value for the size you are joining at. Pre-checks run before any broadcaster credential is allocated: `403 { code: 'plan_upgrade_required' }` when the plan does not include live streaming, `409 { code: 'provisioning_in_progress' }` while a dedicated realtime project is still being set up, `402 { code: 'spend_cap_reached' }` when the organisation hit its monthly spend limit, and `403 { code: 'quota_exceeded' }` when a free-tier monthly limit is exhausted. Sandbox (`hb_test_*`) keys skip the quota pre-check but not the plan entitlement. **`/start` response note:** the response of `POST /api/v1/stream/sessions/:sessionId/start` includes `sandbox_time_limit_seconds: 900` ONLY for sandbox keys. Live/production keys never receive this field — their streams have no time cap.

Generate an RTC subscriber token for a viewer. Call this whenever a viewer joins the stream. Optionally provide viewer info to identify them in the stream chat.

Transition the stream session from 'created' to 'live' status. Call this when the host taps 'Go Live'. Fires a stream.session.started webhook.

Hosts MUST POST to this endpoint every ~30 seconds while broadcasting. The server uses the most recent heartbeat to detect a crashed or abandoned host within minutes and end the session automatically — billing then reflects the actual stream duration (last heartbeat → started_at) rather than the 8-hour wall-clock fallback. Fire-and-forget: a single failed heartbeat is non-fatal; stop sending once you call /end.

Mark the stream as ended, calculate duration, and record usage. Fires a stream.session.ended webhook. Production streams are billed per minute.

Translate a single text string to a target language. source_language defaults to 'auto' (auto-detect). Returns the detected source language and the input character count for usage transparency.

Translate a single text string to multiple target languages in one request. Ideal for broadcasting a message to a multilingual audience. successful_languages lists the codes that returned a translation (failures, e.g. unsupported pairs, are silently skipped).

Detect the language of a given text string. Returns the detected language code (BCP-47) and a confidence score (0.0–1.0).

Get the list of all supported translation language codes. Use the returned codes as source_language or target_language values. count is the total number of languages in the languages array.

Mobile/web SDKs using a customer JWT should call /api/v1/customer/translate/languages instead — same response, customer-JWT auth so the org API key never ships in the binary.

The full list of spoken-language codes accepted by the lang parameter. Accepts either an org API key or a customer JWT, so client apps can populate a language picker directly. The set is small and changes rarely — cache it client-side (the response sends Cache-Control accordingly). Use the same codes (base part) for the translate target.

Pre-validate file size (per-file limit) and storage quota, derive the file's category from its extension, and return a presigned PUT URL for direct-to-storage upload. The URL is valid for 15 minutes. Free-tier orgs that have exhausted their `monthly_storage_mb` allocation get `403 { error: { code: 'quota_exceeded' } }` BEFORE any bytes hit storage — the upload won't even start. Sandbox (`hb_test_*`) keys skip this pre-check. Organisations that reached their monthly spend limit get `402 { error: { code: 'spend_cap_reached' } }` at the same point. When channelId points at an open room, your organization's open-room policy (configured in the Console) also applies — file transfers can be disabled entirely, or restricted to specific types.

After the client finishes uploading to storage, call this endpoint to verify the file exists, record usage, and get back the final file metadata. Idempotent — repeat confirms of the same key do not double-count usage.

Generate a temporary signed URL for a private file. The original filename is automatically set in the Content-Disposition header. Valid for 15 minutes. :key is the full path returned from the upload response.