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 URLhttps://api.hottea.chat/v1HTTPS · JSON · Bearer key
Start here
Your first request
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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).
Create a group with your account as its creator. Groups can have up to 10 participants, including the creator.
idUUID
Generate a new UUID for the group. A used ID returns 409.
name_envelopesobject
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_idsUUID array · optional
Initial invitees. Each must meet the same eligibility rules as later invitees.
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_idsUUID 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_envelopesobject
Seal the group's current name for each invitee, using the same envelope metadata as when creating the group.
photo_keysobject · 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.
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.
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.
Read the latest 100 unexpired messages. Each page arrives in ascending sequence order. Only your own envelope is returned.
beforequery · 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.
Encrypt the body locally and send an envelope for each participant. Submit messages serially within a conversation, including retries, to preserve your intended order.
idUUID · required
Generate a new client message ID. Keep it for exact retries.
typestring · required
text, hot, photo, live_photo, voice, video or present. A hot message costs 20 Sugar.
envelopesobject · 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_revisioninteger · required
0 if no live draft needs clearing. Otherwise the draft revision being sent, at most 9007199254740991. Newer drafts stay intact.
media_idUUID · 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_idstring · 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_idUUID · 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.
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.
revisioninteger · required
1 to 9007199254740991. Choose a value above the current conversation draft_revision for each edit or clear.
envelopeobject or null
Encrypt for the peer with type draft and the revision string as ref. Send null to clear the draft.
envelopesobject 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.
Upload an encrypted media package as multipart form data, then reference its ID in a message. Let your HTTP client set the multipart boundary.
idUUID · required
A new client-generated media ID.
conversation_idUUID · required for chat media
The chat receiving this upload.
kindstring · required
photo, live_photo, voice or video for chat media.
view_onceboolean · required
Use multipart value 1 or 0.
ivstring · required
The 12-byte AES-GCM IV, encoded as 16 unpadded base64url characters.
keysJSON string · required
Two encrypted key envelopes keyed by participant user IDs. Their type is media_key and ref is the media ID.
blobfile · required
The encrypted package, including its authentication tag.
very_high_qualityboolean · optional
Video only. 1 raises the upload limit to 500 MiB and costs 3 Sugar on first upload.
thumbnailfile · 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_ivstring · with thumbnail
The thumbnail's 12-byte AES-GCM IV, encoded like iv.
sugar_priceinteger · 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.
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 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.
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.
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.
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.
statusstring · required
online, away or invisible. The response echoes your choice.
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
Field
Meaning
id
Conversation UUID.
kind
direct or group.
peer
{id, username, public_key}. The key is an uncompressed P-256 public point encoded as base64url. Null for a group chat.
group
Null 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_accepted
Whether each side has accepted the chat.
unread
Number of unread, unexpired, undeleted messages from the peer.
draft_revision, has_draft
Your draft watermark and whether the peer has a live draft.
Your last-online sharing and push preferences for this chat.
archived, hidden
Your chat visibility flags.
request_expires_at
Expiry of an unaccepted chat request, or null.
game, shared_avatar_id
Active game metadata and the current avatar shared by you, or null.
message_updates
Messages 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
Field
Meaning
id, sequence
Your 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_id
The chat and sender UUIDs.
type, envelope
Message kind and your encrypted envelope. The envelope is null for a deleted message.
deleted
True for a tombstone; discard any cached content.
accepted_at, expires_at
Server acceptance and expiry. Ordinary messages expire after 24 hours; saved messages have null expiry.
edited_at
Last edit time, or null.
saves, save_version
Per-user saved state and its revision.
saved_by_id, saved_at
Who saved the message and when, or null.
save_unlocked_by
User IDs with a permanent media-save entitlement.
reactions, reaction_times
Maps from reacting user IDs to their emoji and latest reaction time.
reaction_version
Increasing version for discarding stale reaction snapshots.
media
Your authorized media descriptor, or null.
hot_viewed, present
Extra 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
Content
Limit
Message text and draft envelopes
384 KiB per envelope, including JSON. The client text limit is 5,000 graphemes.
Other ordinary envelopes
16 KiB per envelope, including JSON.
Photo, voice
20 MiB encrypted package plus a 16-byte tag.
Live Photo
40 MiB encrypted package plus a 16-byte tag.
Standard video
300 MiB package plus a 16-byte tag; at most 180 seconds.
Very high quality video
500 MiB package plus a 16-byte tag; 3 Sugar per new upload.
Avatar
1 MiB ciphertext plus a 16-byte tag.
Pending uploads
At most 10 recent unattached uploads. Attach chat media within 15 minutes.
Live drafts
Expire 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
Status
What to do
401 Unauthorized
The API key is missing, invalid or revoked. Device tokens are also rejected. Check the key and base URL.
402 Payment required
The account lacks Sugar for a paid action. Use the app to collect Sugar.
403 Forbidden
The relationship is blocked or this operation is not allowed for the caller, such as downloading or opening view-once media.
404 Not found
The resource is missing, expired, inaccessible to you, or outside your conversations. Check the ID and public route.
409 Conflict
An ID or draft revision was reused with different content. Retry the original payload or create a new ID/revision.
410 Gone
The item expired or view-once media was consumed. Do not retry expecting the content to return.
413 Too large
Reduce the encrypted upload or request size.
422 Validation failed
Inspect errors for invalid fields, envelope metadata, encoding or size.
429 Too many requests
Wait 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."]
}
}