HotTea Developer documentation
Public messaging API v1

Build with the
HotTea API.

Write programs that read and send messages through your HotTea account. Create groups, share media, or let a script set your status. Message content stays end-to-end encrypted.

BASE URL https://api.hottea.chat/v1 HTTPS · JSON · Bearer key

Start here

Your first request

  1. Create an API key.

    Open Settings in HotTea, find API keys, and give your new key a name. Copy the key while it is visible. HotTea shows it only once.

  2. Download its API file.

    Save the API file while the new key is still on screen. Your program needs this file and the key to encrypt or decrypt content. You can list conversations with just the key.

  3. List your conversations.

    Run the request shown here in your terminal. An account without chats returns an empty data array. You can start a direct chat in the app or create a group through the API.

Shell
export HOTTEA_API_URL='https://api.hottea.chat/v1'
export HOTTEA_API_KEY='hottea_REPLACE_WITH_YOUR_KEY'

curl "$HOTTEA_API_URL/conversations" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json'

The examples below use these environment variables. Replace CONVERSATION_ID, MESSAGE_ID and MEDIA_ID with IDs from your responses. Ciphertext placeholders illustrate the format; generate real envelopes before sending them.

Authentication

Send your API key in the Authorization header on every request. Use Accept: application/json and, for JSON bodies, Content-Type: application/json. Media uploads use multipart form data.

HTTP headers
Authorization: Bearer hottea_REPLACE_WITH_YOUR_KEY
Accept: application/json
Content-Type: application/json

Keys belong to your account and can access its conversations. Each account can have up to 10 keys, with names of 1 to 50 characters. Manage and revoke them in Settings. Revocation takes effect on the next request and clears live drafts written with that key. Deleting the account removes its keys.

API keys work only on the public API host at https://api.hottea.chat/v1. Device session tokens do not work here. The public API does not provide CORS access: run integrations in a server process, command-line tool, or another trusted program.

Keep the key and API file private. Together they let a program act as your account on this API and extract your identity key. Revoking the API key stops future API access, but cannot erase keys or content someone has already copied. Never embed these credentials in a public web page.

Encryption & API files

The server stores ciphertext. Your program encrypts message bodies before uploading them and decrypts received envelopes locally. An API key authorizes requests; the matching API file holds the identity key needed to work with the content.

Open your API file

The downloaded file is UTF-8 JSON with this structure. All binary values use base64url without padding.

API file
{
  "format": "hottea-api",
  "v": 1,
  "api_url": "https://api.hottea.chat/v1",
  "key_id": "API_KEY_UUID",
  "salt": "BASE64URL_32_BYTES",
  "iv": "BASE64URL_12_BYTES",
  "ct": "BASE64URL_CIPHERTEXT_AND_TAG"
}
  1. Check format and v. Derive a 32-byte key with HKDF-SHA256, using the UTF-8 bytes of the entire API key as input key material, the decoded salt, and UTF-8 HotTea API file v1 as the info.
  2. Decrypt ct with AES-256-GCM, the derived key, and the decoded 12-byte iv. The final 16 bytes of ct are the authentication tag. The additional authenticated data (AAD) is UTF-8 compact JSON: ["hottea-api-file",1,api_url,key_id], with the file's exact URL and key ID.
  3. Parse the decrypted JSON: {user_id, identity:{public_key, private_key}, pins}. The public key is a base64url, 65-byte uncompressed SEC1 P-256 point; the private key is a base64url, 32-byte scalar. Check each peer's public key against the file's trusted pins before using it.

An API file contains no recovery credential or device session token, and cannot sign in to the app. The key that created it is the only API key that can open it.

Seal an envelope

Use authenticated HPKE (mode 2), with P-256 KEM 0x0010, HKDF-SHA256 KDF 0x0001, and AES-256-GCM AEAD 0x0002. Use the sender's identity private key for authentication and the recipient's identity public key for encryption. Create a fresh HPKE context for each envelope, with UTF-8 HotTea HPKE v1 as the info.

Encrypted envelope
{
  "v": 1,
  "suite": "P256-SHA256-AES256GCM-AUTH",
  "enc": "BASE64URL_EPHEMERAL_PUBLIC_KEY",
  "ct": "BASE64URL_CIPHERTEXT_AND_TAG",
  "meta": {
    "sender": "SENDER_UUID",
    "recipient": "RECIPIENT_UUID",
    "conversation": "CONVERSATION_UUID",
    "type": "text",
    "ref": "MESSAGE_UUID"
  }
}

The envelope has exactly these five top-level fields. enc is a 65-byte uncompressed SEC1 point. The AAD is the UTF-8 encoding of this compact JSON array, in this order and without whitespace:

Envelope AAD
["hottea",1,"P256-SHA256-AES256GCM-AUTH",sender,recipient,conversation,type,ref]

All metadata values are strings and must match the intended routing exactly. For a message, use its type and client-generated UUID as ref. For a live draft, use type: "draft" and the decimal revision as ref. For a media key, use type: "media_key" and the media UUID. Verify this metadata before opening received envelopes.

Send two independently encrypted message envelopes, one for yourself and one for the peer, keyed by their user IDs. The decrypted message body is UTF-8 JSON:

Plaintext before encryption
{
  "text": "Tea in ten minutes?",
  "reply_to": "OPTIONAL_MESSAGE_UUID"
}

Omit reply_to for a new message. Text has a client limit of 5,000 Unicode graphemes. Voice messages use empty text and a voice object with duration in milliseconds (up to 300000) and levels (1 to 64 integers from 0 to 100).

Package and encrypt media

Build a binary package: a four-byte unsigned big-endian header length, the UTF-8 compact JSON header {"v":1,"parts":[{"mime":"image/jpeg","bytes":123}]}, then the concatenated part bytes. Each part's bytes is its byte length.

A photo has one JPEG, PNG or WebP image; a Live Photo has an image plus MP4, or MP4 only; a voice message has one MP4, WebM or Ogg audio part. A video has one MP4 part with H.264 and optional AAC audio, at most 180 seconds long.

Encrypt the package with AES-256-GCM using a fresh random 32-byte key, a fresh 12-byte IV, and a 16-byte authentication tag appended to the ciphertext. The AAD is UTF-8 compact JSON ["hottea-media",1,conversation,sender,mediaId,kind], with string routing values.

Seal the raw 32-byte AES key in two HPKE envelopes with type: "media_key" and ref equal to the media UUID. Upload the ciphertext and these key envelopes, then send a message referencing the returned media ID.

Older content can carry former numeric user IDs as decimal strings in envelope metadata. Preserve that metadata for authentication and media AAD, and accept it only when the sender/recipient relation and the remaining routing fields match.

Endpoint reference

Conversations

All paths below are relative to the base URL. Use the app to start direct chats and accept invitations.

List conversations

GET/conversations

Get up to 500 of your most recently updated conversations, including each peer's public key, unread count, and presence. Blocked or hidden chats are excluded.

200 · {data: ConversationSummary[], server_time, statistics, sugar}

Use the conversation's id for subsequent requests. Pin or verify peer.public_key before encrypting content for that peer.

Shell
curl "$HOTTEA_API_URL/conversations" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json'

The response also includes UTC server_time, account statistics (including lifetime sent_hot_messages and received_hot_messages totals), and your sugar wallet (balance and next_collection_at).

Get a conversation

GET/conversations/{conversation}

Get one conversation summary. Its draft_revision is your account's live-draft watermark for this chat.

200 · {data: ConversationSummary}

Unknown chats and chats you cannot access return 404. A blocked relationship returns 403.

Shell
curl "$HOTTEA_API_URL/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json'

Create a group

POST/conversations/groups

Create a group with your account as its creator. Groups can have up to 10 participants, including the creator.

id UUID
Generate a new UUID for the group. A used ID returns 409.
name_envelopes object
Seal the JSON {name} for yourself and each initial invitee. Key the object by recipient UUID. Use group_name for the envelope type and the group UUID for both conversation and ref.
member_ids UUID array · optional
Initial invitees. Each must meet the same eligibility rules as later invitees.

201 · {data: ConversationSummary}

Shell
curl "$HOTTEA_API_URL/conversations/groups" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @group.json

Put the group UUID and sealed name envelopes in group.json. Omit member_ids to create a group with just your account.

Invite group members

POST/conversations/{conversation}/members

Only the group creator can invite. To find eligible contacts, look for conversations with kind: "direct", accepted: true and peer_accepted: true. Use each contact's UUID and public key from peer.

user_ids UUID array
One or more distinct invitee UUIDs. An existing member returns 409. The entire request returns 403 if any invitee lacks a mutually accepted direct chat with the creator or either person has blocked the other.
name_envelopes object
Seal the group's current name for each invitee, using the same envelope metadata as when creating the group.
photo_keys object · required for groups with a photo
Seal the current group photo's key for each invitee with type media_key. Use the group UUID as conversation and the photo UUID as ref. Omit this field for groups without a photo.

201 · {data: ConversationSummary} with the pending invitees. They accept in the app and can see messages sent after they were invited.

Shell
curl "$HOTTEA_API_URL/conversations/$CONVERSATION_ID/members" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @invite.json

Put the invitee UUIDs, sealed name envelopes and any sealed photo keys in invite.json.

Rename a group

PUT/conversations/{conversation}/name

Only the group creator can rename it.

name_envelopes object
Seal the new name for every current participant, including yourself and any pending invitees. Key the object by recipient UUID and use the same envelope metadata as when creating the group. A mismatched set of envelopes returns 422.

200 · {data: ConversationSummary}

Shell
curl -X PUT "$HOTTEA_API_URL/conversations/$CONVERSATION_ID/name" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @name.json

Delete a group

DELETE/conversations/{conversation}

Only the group creator can delete it. This permanently removes the group, its messages, and its media for everyone.

200 · {deleted: true}. A participant other than the creator receives 403. Missing or inaccessible groups return 404. An accessible direct chat returns 422.

Shell
curl -X DELETE "$HOTTEA_API_URL/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $HOTTEA_API_KEY"

Count unread messages

GET/conversations/{conversation}/unread

Count the peer's unexpired, undeleted messages after your last read position. This is the same count shown in the chat list.

200 · {unread: integer}

Shell
curl "$HOTTEA_API_URL/conversations/$CONVERSATION_ID/unread" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json'
200 · response
{"unread": 2}

Mark messages as read

POST/conversations/{conversation}/read

Move your read position forward through the specified message, including earlier messages in the chat.

message_id UUID · optional
A message in this conversation. Omitting it records a visit and clears chat push notifications without moving the read position.
Shell
curl -X POST "$HOTTEA_API_URL/conversations/$CONVERSATION_ID/read" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d "{\"message_id\":\"$MESSAGE_ID\"}"
200 · response
{"read": true}

Messages

Read message history

GET/conversations/{conversation}/messages

Read the latest 100 unexpired messages. Each page arrives in ascending sequence order. Only your own envelope is returned.

before query · UUID · optional
For older history, pass the first message's id from the current page. The cursor itself is excluded. Stop when a page is empty.

200 · {data: Message[]}

Reading history does not mark messages as read. Call the read endpoint when appropriate. Deleted messages can appear as tombstones with deleted: true and no content.

Shell
curl --get "$HOTTEA_API_URL/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json' \
  --data-urlencode "before=$MESSAGE_ID"

Omit before for the first page. See message response fields below.

Send a message

POST/conversations/{conversation}/messages

Encrypt the body locally and send an envelope for each participant. Submit messages serially within a conversation, including retries, to preserve your intended order.

id UUID · required
Generate a new client message ID. Keep it for exact retries.
type string · required
text, hot, photo, live_photo, voice, video or present. A hot message costs 20 Sugar.
envelopes object · required
One encrypted envelope per participant, keyed by user ID: yours and your peer's, or in a group chat yours and every other member's (pending invitations included). Presents are not available in groups.
draft_revision integer · required
0 if no live draft needs clearing. Otherwise the draft revision being sent, at most 9007199254740991. Newer drafts stay intact.
media_id UUID · media and present messages
Required for photo, Live Photo, voice and video messages. Attach an upload of the matching kind within 15 minutes. Omit for text and hot messages. A present message may carry one non-view-once photo upload; that message is saved for both participants right away, free of charge.
present_id string · present messages only
Choose a present from GET /presents. The server charges its Sugar price and sends it in this chat atomically. Sold-out presents return 409, insufficient Sugar returns 402, and exact message retries never charge twice.
present_purchase_id UUID · legacy presents only
Send an existing owned present instead of buying one. Use either present_id or present_purchase_id, never both. Standalone purchases are no longer available.

201 · A bare Message object. An identical retry returns 200. A changed payload under the same ID returns 409; a retry after expiry returns 410.

message.json · replace encrypted values
{
  "id": "MESSAGE_UUID",
  "type": "text",
  "draft_revision": 0,
  "envelopes": {
    "SENDER_UUID": {
      "v": 1,
      "suite": "P256-SHA256-AES256GCM-AUTH",
      "enc": "BASE64URL_EPHEMERAL_KEY_1",
      "ct": "BASE64URL_CIPHERTEXT_1",
      "meta": {
        "sender": "SENDER_UUID",
        "recipient": "SENDER_UUID",
        "conversation": "CONVERSATION_UUID",
        "type": "text",
        "ref": "MESSAGE_UUID"
      }
    },
    "PEER_UUID": {
      "v": 1,
      "suite": "P256-SHA256-AES256GCM-AUTH",
      "enc": "BASE64URL_EPHEMERAL_KEY_2",
      "ct": "BASE64URL_CIPHERTEXT_2",
      "meta": {
        "sender": "SENDER_UUID",
        "recipient": "PEER_UUID",
        "conversation": "CONVERSATION_UUID",
        "type": "text",
        "ref": "MESSAGE_UUID"
      }
    }
  }
}
Shell
curl -X POST "$HOTTEA_API_URL/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-binary @message.json

Type a live draft

PUT/conversations/{conversation}/draft

Show encrypted text to your peer while your program writes it. Live drafts expire after 30 seconds; refresh an active draft with its identical envelope every 20 seconds.

revision integer · required
1 to 9007199254740991. Choose a value above the current conversation draft_revision for each edit or clear.
envelope object or null
Encrypt for the peer with type draft and the revision string as ref. Send null to clear the draft.
envelopes object or null · group chats
Instead of envelope in a group chat: one draft envelope for each other member, keyed by user ID.

200 · {accepted: boolean, revision: integer}. A stale or cleared revision returns accepted: false with the current watermark. Reusing an active revision with different ciphertext returns 409.

Clear the live preview when leaving or backgrounding. Budget updates against the API's shared 60 requests per minute.

JSON · clear revision 42
{"revision": 42, "envelope": null}
Shell
curl -X PUT "$HOTTEA_API_URL/conversations/$CONVERSATION_ID/draft" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"revision":42,"envelope":null}'
200 · accepted clear
{"accepted": true, "revision": 42}

React to a message

PUT/conversations/{conversation}/messages/{messageId}/reaction

Set your single reaction on an unexpired, undeleted message. Calling again replaces your previous reaction; an identical retry leaves it unchanged.

reaction string · required
One of 👍 👎 ❤️ 🔥 🙏 😂 😘 😞. The heart includes the U+FE0F variation selector.

200 · A bare Message object with updated reactions, reaction_times and reaction_version. Reactions are visible to the server.

Shell
curl -X PUT "$HOTTEA_API_URL/conversations/$CONVERSATION_ID/messages/$MESSAGE_ID/reaction" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"reaction":"👍"}'

Media & status

Upload encrypted media

POST/media

Upload an encrypted media package as multipart form data, then reference its ID in a message. Let your HTTP client set the multipart boundary.

id UUID · required
A new client-generated media ID.
conversation_id UUID · required for chat media
The chat receiving this upload.
kind string · required
photo, live_photo, voice or video for chat media.
view_once boolean · required
Use multipart value 1 or 0.
iv string · required
The 12-byte AES-GCM IV, encoded as 16 unpadded base64url characters.
keys JSON string · required
Two encrypted key envelopes keyed by participant user IDs. Their type is media_key and ref is the media ID.
blob file · required
The encrypted package, including its authentication tag.
very_high_quality boolean · optional
Video only. 1 raises the upload limit to 500 MiB and costs 3 Sugar on first upload.
thumbnail file · optional
Photo, Live Photo or video that is not view-once only. A small JPEG preview, at most 64 KiB plus its authentication tag, encrypted with the media's key, a fresh IV and the AAD ["hottea-media-thumbnail",1,conversation,sender,mediaId,kind]. Galleries show it instead of downloading the media.
thumbnail_iv string · with thumbnail
The thumbnail's 12-byte AES-GCM IV, encoded like iv.
sugar_price integer · optional
Only 0 is accepted. Media can no longer be sold for Sugar; the field remains for older clients.

201 · {id: UUID}. An exact retry returns 200. Paid high-quality video responses also include the current sugar wallet.

The route also accepts kind: "avatar" with no conversation, a single owner key envelope of type avatar_key, view_once: 0 and AAD conversation profile. Avatars encrypt a raw 512×512 JPEG. Applying an avatar is an app operation.

Shell
curl "$HOTTEA_API_URL/media" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json' \
  -F "id=$MEDIA_ID" \
  -F "conversation_id=$CONVERSATION_ID" \
  -F 'kind=photo' \
  -F 'view_once=0' \
  -F "iv=$MEDIA_IV" \
  -F 'keys=<keys.json' \
  -F 'blob=@encrypted.bin;type=application/octet-stream'

keys.json holds the two key envelopes. Set MEDIA_IV to your base64url IV. Upload retries must keep the ID, routing, quality, price, encrypted bytes, IV and key envelopes unchanged.

Download media

GET/media/{media}

Download the authorized ciphertext as application/octet-stream. Use the media descriptor's IV and your wrapped key to decrypt it locally.

200 · Encrypted binary data.

View-once media opens only in the HotTea app on iPhone, iPad and Android, where it is shown behind screen capture protection. API keys get 403 for view-once downloads, without receiving any data. An expired item returns 410.

Shell · ordinary media
curl "$HOTTEA_API_URL/media/$MEDIA_ID" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  --output encrypted.bin

Release decrypted media when your program no longer needs it.

Download a media thumbnail

GET/media/{media}/thumbnail

Download the sender's encrypted thumbnail, under the same access rules as the media. It is present when the media descriptor's thumbnail_iv is set; decrypt it with the media's key, that IV and the thumbnail AAD to get a JPEG.

200 · Encrypted binary data. 404 when the media has no thumbnail.

Shell
curl "$HOTTEA_API_URL/media/$MEDIA_ID/thumbnail" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  --output thumbnail.bin

View-once media

POST/media/{media}/consume

View-once media can't be opened through the public API. This route answers 403 to API keys for every item, view-once or ordinary, after checking that you may access it, and changes nothing: the media stays unopened for the recipient's app.

You can still send view-once media: upload it with view_once=1 and attach it to a message. Its descriptor's key is always null in public API responses, also for your own uploads.

Opened in the app only.The recipient opens view-once media in the HotTea app on iPhone, iPad or Android, which protects it against screenshots and screen recording. Browsers and the Mac can't open it either.
Shell
curl -X POST "$HOTTEA_API_URL/media/$MEDIA_ID/consume" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json'

Set your status

PUT/status

Set your account's presence choice. API use counts as account activity, but does not create an online device lease. Choosing online or away only shows that status while a device is online.

status string · required
online, away or invisible. The response echoes your choice.
Shell
curl -X PUT "$HOTTEA_API_URL/status" \
  -H "Authorization: Bearer $HOTTEA_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"status":"away"}'
200 · response
{"status": "away"}

Response fields

Current user, conversation, message and media IDs are UUID strings. sequence is a positive decimal string counted per conversation; compare it as an integer without losing precision, and only within one conversation. Timestamps use UTC ISO 8601. Responses include only the requesting user's encrypted envelopes.

Conversation summary

Conversation summary fields
FieldMeaning
idConversation UUID.
kinddirect or group.
peer{id, username, public_key}. The key is an uncompressed P-256 public point encoded as base64url. Null for a group chat.
groupNull for a direct chat. For a group: {creator_id, name_envelope, photo, limit, members}, where name_envelope is the group's name sealed by its creator for you (type group_name, JSON {name}) or null, and photo, the group photo as {id, iv, key} with its key sealed for you, or null. members lists every participant, you included, as {id, username, public_key, accepted}. Pin or verify each member's key before encrypting for them.
accepted, peer_acceptedWhether each side has accepted the chat.
unreadNumber of unread, unexpired, undeleted messages from the peer.
draft_revision, has_draftYour draft watermark and whether the peer has a live draft.
presence{status, expires_at, last_online_at}, respecting presence privacy.
share_last_online, push_mutedYour last-online sharing and push preferences for this chat.
archived, hiddenYour chat visibility flags.
request_expires_atExpiry of an unaccepted chat request, or null.
game, shared_avatar_idActive game metadata and the current avatar shared by you, or null.
message_updatesMessages with save, reaction or visibility changes in the last 24 hours, including removals and unhides. Each item contains {id, save_version, reaction_version, hidden, visibility_changed_at}. Refetch changed messages to recover notices beyond the newest history page; message contents are not included.

Message

Message response fields
FieldMeaning
id, sequenceYour client-generated UUID and the stable server insertion order within the conversation. It need not start at 1 or be contiguous. Acceptance timestamps can match, so sort by sequence.
conversation_id, sender_idThe chat and sender UUIDs.
type, envelopeMessage kind and your encrypted envelope. The envelope is null for a deleted message.
deletedTrue for a tombstone; discard any cached content.
accepted_at, expires_atServer acceptance and expiry. Ordinary messages expire after 24 hours; saved messages have null expiry.
edited_atLast edit time, or null.
saves, save_versionPer-user saved state and its revision.
saved_by_id, saved_atWho saved the message and when, or null.
save_unlocked_byUser IDs with a permanent media-save entitlement.
reactions, reaction_timesMaps from reacting user IDs to their emoji and latest reaction time.
reaction_versionIncreasing version for discarding stale reaction snapshots.
mediaYour authorized media descriptor, or null.
hot_viewed, presentExtra fields for hot and present messages respectively.

Media descriptor

{id, kind, view_once, consumed, bytes, iv, key}. bytes is the ciphertext length. key is your wrapped AES key. It is always null for view-once media, which opens only in the app.

Limits & retries

All of an account's API keys share a budget of 60 requests per minute. Creating another key does not increase it. Additional per-account limits apply to message sends (30/minute), uploads (10/minute), and draft updates (250/minute); the shared public API budget still applies to all of them.

On 429, wait for the number of seconds in Retry-After when present, then retry with backoff. Keep polling within the shared budget and leave room for outgoing messages.

Use of the API is governed by the Terms of Service. Automating your own account is welcome; unsolicited messages, bulk messaging and getting around limits or access controls are not.

Content limits
ContentLimit
Message text and draft envelopes384 KiB per envelope, including JSON. The client text limit is 5,000 graphemes.
Other ordinary envelopes16 KiB per envelope, including JSON.
Photo, voice20 MiB encrypted package plus a 16-byte tag.
Live Photo40 MiB encrypted package plus a 16-byte tag.
Standard video300 MiB package plus a 16-byte tag; at most 180 seconds.
Very high quality video500 MiB package plus a 16-byte tag; 3 Sugar per new upload.
Avatar1 MiB ciphertext plus a 16-byte tag.
Pending uploadsAt most 10 recent unattached uploads. Attach chat media within 15 minutes.
Live draftsExpire after 30 seconds; refresh an unchanged envelope every 20 seconds.

Retry message sends with the same ID and identical encrypted payload. Retries do not extend expiry or charge Sugar again. Upload retries must preserve the original encrypted bytes and metadata. A conflicting reuse returns 409.

Errors

Errors on the API host are JSON. Responses use Cache-Control: no-store, private. Check the HTTP status before decoding a successful resource, and avoid logging credentials or message bodies.

Error status codes
StatusWhat to do
401 UnauthorizedThe API key is missing, invalid or revoked. Device tokens are also rejected. Check the key and base URL.
402 Payment requiredThe account lacks Sugar for a paid action. Use the app to collect Sugar.
403 ForbiddenThe relationship is blocked or this operation is not allowed for the caller, such as downloading or opening view-once media.
404 Not foundThe resource is missing, expired, inaccessible to you, or outside your conversations. Check the ID and public route.
409 ConflictAn ID or draft revision was reused with different content. Retry the original payload or create a new ID/revision.
410 GoneThe item expired or view-once media was consumed. Do not retry expecting the content to return.
413 Too largeReduce the encrypted upload or request size.
422 Validation failedInspect errors for invalid fields, envelope metadata, encoding or size.
429 Too many requestsWait for Retry-After when present. Reduce polling or outstanding uploads.
422 · example validation error
{
  "message": "The selected status is invalid.",
  "errors": {
    "status": ["The selected status is invalid."]
  }
}