API Reference

Return the current month's API usage breakdown by service. Use for programmatic monitoring or billing alert automation.

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. 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'.

Returns the org's file transfer policy for open rooms. If no custom policy exists yet, platform defaults are returned. Use this in your app to enforce client-side upload rules.

UPSERT the org's open room file transfer policy. All fields are optional — omit a field to keep the current value. Changes take effect immediately for any client that fetches the policy.

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).

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.

Get messages for a room with cursor-based pagination. Pass before_id for older messages. The response also includes read_statuses for all members — use these to render delivery/read icons (✓ sent, ✓✓ read, N unread count for group rooms).

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.

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' | 'video' | 'audio' | 'file'. For file messages, set content to the file URL from the Storage API and include metadata.file.

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 (Redis SADD-deduped — 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.

Remove a block between two users.

Get the list of user IDs that userId has blocked.

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.

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. Pass `quality: 'fhd'` for FHD billing tier; omit (or send `'hd'`) for HD. The value is persisted on the session row and drives whether minutes count toward `hd_video_mins` or `fhd_video_mins` when the call ends. Returns `403 { error: { code: 'quota_exceeded' } }` when the org's free-tier monthly quota is exhausted, before any RTC tokens are issued. Sandbox / `hb_test_*` keys bypass the quota check entirely.

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 `hd_video_mins` or `fhd_video_mins` (per session.quality) and bumps `api_calls`. 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 `hd_video_mins` or `fhd_video_mins` (per session.quality) 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.

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. Pass `quality: 'fhd'` for FHD billing; omit (or send `'hd'`) for HD. The value is persisted on the session row and drives whether minutes count toward `hd_stream_mins` or `fhd_stream_mins` when the stream ends. Returns `403 { error: { code: 'quota_exceeded' } }` if the free-tier monthly limit is exhausted, before allocating broadcaster credentials. Sandbox / `hb_test_*` keys bypass this check. **`/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.

Pre-validate file type (allowlist), size (plan limit), and storage quota. On success, returns 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 bypass this check (test traffic is unbilled by policy).

After the client finishes uploading to storage, call this endpoint to verify the file exists (via HeadObject), record usage, and get back the final file metadata. If the actual file size exceeds the plan limit, the file is automatically deleted.

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.