HTTP API¶

The viewer's web app uses a JSON API, and scripts can call the same routes. This page covers how to log in, which login each route needs, and each route's parameters and responses.

Basics¶

• The viewer listens on port 8000. Every path on this page is relative to that address, or to the address of your reverse proxy.
• Chats are addressed by an opaque ref, never by the Telegram chat id. Get refs from GET /api/chats.
• Request bodies are JSON. Send Content-Type: application/json.
• Dates are ISO 8601. A timestamp without an offset is read as UTC.

The viewer serves its own generated OpenAPI document at /openapi.json, and it needs no login. The /docs and /redoc pages also exist, but they render blank, because the viewer's content security policy allows no scripts from other hosts. The document lists paths and query parameters, but it has no request bodies, no response shapes and no permission rules. Use this page for those.

Authentication¶

There are no API keys for the /api routes. A script logs in, keeps the session cookie and sends it back on every request.

The viewer supports three login modes. Logins, viewer accounts and share links explains how to turn each one on.

With no mode configured, every protected route answers 503 Viewer authentication is not configured.

Log in with a password¶

POST /api/login takes {"username": "...", "password": "..."}. It checks viewer accounts first, then the master credentials from the environment. On success it sets the viewer_auth cookie and answers:

{"success": true, "role": "master", "username": "admin"}

role is master or viewer.

curl -s -c jar.txt -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"your-password"}' \
  http://localhost:8000/api/login

curl -s -b jar.txt http://localhost:8000/api/chats

import requests

s = requests.Session()
r = s.post(
    "http://localhost:8000/api/login",
    json={"username": "admin", "password": "your-password"},
)
r.raise_for_status()
chats = s.get("http://localhost:8000/api/chats").json()

Login errors:

When password login is off but anonymous mode is on, the route answers {"success": true, "message": ...} and sets no cookie.

The session cookie¶

The cookie viewer_auth holds an opaque random session key. It is HttpOnly and SameSite=Lax, and lasts AUTH_SESSION_DAYS days, default 30. The viewer marks it Secure when SECURE_COOKIES=true. When SECURE_COOKIES is unset, it marks it Secure only if the login request came over https or carried X-Forwarded-Proto: https. A client does not send a Secure cookie over plain http. If the cookie is Secure, call the viewer over https.

Sessions are stored in the database and survive a viewer restart. Each user holds at most 10 sessions. The 11th login ends the oldest one, so a script that logs in on every run can push a browser session out. Log out at the end of each run, or reuse one cookie jar.

Log in with a share token¶

A share token is a 64-character hex string created by the master. POST /auth/token takes {"token": "..."} and sets the viewer_auth cookie:

curl -s -c jar.txt -H 'Content-Type: application/json' \
  -d '{"token":"<64 hex characters>"}' \
  http://localhost:8000/auth/token

{"success": true, "role": "token", "username": "token:family", "no_download": false}

username is token: followed by the token's label. A token with no label gets token:token:<id>, so give every token a label. The session sees only the token's chats. Invalid, revoked and expired tokens all answer 401 Invalid or expired token. Each use updates the token's last_used_at and use_count.

A share link in the browser carries the token as #token=<value>. The web app reads it and posts it to /auth/token for you.

Check the session¶

GET /api/auth/check needs no login. It answers:

{"authenticated": true, "auth_required": true, "role": "viewer", "username": "alice", "no_download": false}

Proxy users also get "proxy_auth": true. When no login mode is configured, the answer carries "setup_required": true.

Log out¶

POST /api/logout ends the session named by the cookie, closes that session's WebSocket connections, deletes every push subscription of that user and clears the cookie. It always answers {"success": true}. When the request carried a session cookie, the answer also sends Clear-Site-Data: "cache" so the browser drops the media it kept. A request without the cookie, such as another site's form post, does not get the header. That header empties the browser's HTTP cache for the viewer only. The service worker, cookies and local settings stay, and the viewer's static files download again on the next visit. Browsers apply it over HTTPS only.

curl -s -b jar.txt -X POST http://localhost:8000/api/logout

The master can end other people's sessions through the admin routes. See End sessions.

Rate limit¶

/api/login and /auth/token share one limit: 15 attempts per client IP in 5 minutes, then 429. The client IP is the socket peer unless TRUST_PROXY_HEADERS=true, in which case the viewer reads X-Forwarded-For or X-Real-IP. The only other rate limit is on asking for a transcript. See Transcripts. Exposing the viewer safely explains the proxy setup.

Who can call what¶

Master routes answer 403 Admin access required to everyone else. They also answer 403 when the request carries X-Viewer-Only: true, even with a master cookie. That header also makes the master credentials fail at login.

A chat route answers the same 404 Chat not found for a ref that does not exist, a malformed ref and a chat the caller may not see. What a caller may see combines the operator's DISPLAY_CHAT_IDS filter with the caller's allowed_accounts and allowed_chat_refs grants.

Logins with no_download set get 403 Downloads disabled for this account on media bytes, thumbnails, transcript routes and export. In message payloads their media file_path and url are null, downloaded is false, transcripts are removed and a shared contact's raw_data.contact.vcard is left out. Avatars stay available to them.

Health and status¶

GET /api/health answers {"status": "ok", "database": "connected"}. When the database probe fails it answers HTTP 503 with {"status": "degraded", "database": "unreachable"}. The viewer container's health check calls this route.

GET /api/stats answers the stored daily figures and some runtime settings and flags:

For a restricted login the counts cover only its chats. POST /api/stats/refresh recounts the whole archive, which takes a while on a large one. Do not call it on a schedule.

GET /api/status holds counts and timestamps only, never chat names or content. It is sent with Cache-Control: private, no-store.

curl -s -b jar.txt http://localhost:8000/api/status

{
  "backup": {"last_run": "2026-09-28T03:00:12", "in_progress": false},
  "stats_calculated_at": "2026-09-28T00:00:05",
  "listeners": [
    {
      "account_id": 1,
      "active": true,
      "active_since": "2026-09-27T18:04:40",
      "last_update_at": "2026-09-28T09:41:12.503118+00:00",
      "deletions_blocked": 0,
      "last_rate_limit_at": null
    }
  ],
  "media": {"downloaded": 1200, "pending": 3, "exhausted": 0, "skipped": 45},
  "database": {"backend": "postgresql", "size_bytes": 734003200}
}

backend is sqlite or postgresql. A monitoring script can alert when backup.last_run is too old, when a listener is not active, or when media.exhausted grows. A listener is active while it stamps its heartbeat, every 30 seconds, and for three minutes after the last stamp. active_since stays on a listener that is not active when it stopped without shutting down, as after a killed container; a clean stop clears it. listener_active in /api/stats follows the same rule.

Each listener row also carries:

An active listener whose last_update_at stops moving is connected but receiving nothing: alert when it is older than what your chats normally go without an update. A deletions_blocked above 0 means deletions were not recorded; the SYNC_DELETIONS_EDITS backup pass records them. With SYNC_DELETIONS_EDITS_DAYS above 0 it records only those posted inside the window. See Checking that it runs.

Accounts, chats and folders¶

All of these need any login.

The chat list preview¶

preview is the chat's newest message that was not deleted in Telegram, or null when the chat has none. It is read from the copy of the chat the row's ref opens, under the same restrictions as the chat's messages, so it never shows a message the caller could not open in the chat. It carries text and a kind only, never a file or a transcript. GET /api/chats/{chat_ref} does not return it.

Example:

"preview": {
  "message_id": 1288,
  "date": "2026-09-30T08:57:00",
  "text": "Perfect, save me a seat",
  "sender": "Esme",
  "kind": "text",
  "outgoing": false,
  "action": null,
  "action_title": null
}

Messages¶

All of these need a login that can see the chat.

Paging through messages¶

Offset paging gets slower as the offset grows. For long walks use the cursor: pass the date and id of the last message you received as before_date and before_id.

curl -s -b jar.txt \
  'http://localhost:8000/api/chats/<ref>/messages?limit=200&before_date=2026-09-01T10:15:00&before_id=48213'

A lone before_id=N returns messages with ids below N. after_id=N returns messages with ids above N.

deleted_only=true keeps only the messages deleted in Telegram that the archive kept, the rows with is_deleted set to 1, newest first. It works with or without search: without it you get every kept deletion of the chat, with it the deletions that match. It combines with topic_id and the cursors like the other filters. It is a read and stays inside the chat the ref names, so a viewer restricted to some chats or accounts, or a share link, gets the same 404 for another chat as without it.

curl -s -b jar.txt \
  'http://localhost:8000/api/chats/<ref>/messages?limit=50&offset=0&deleted_only=true'

edited_only=true keeps only the edited messages, newest first, the same way. A message counts as edited when Telegram marks it (edit_date is set and edit_hide is not 1) or the archive kept at least one earlier version of it (version_count above 0): either can hold without the other, for a message first archived after its edit or an earlier empty text the archive filled in. edit_hide is Telegram's flag for that edit_date: 1 when Telegram says the edit is not to be shown, which it does when only the reactions changed, 0 when it shows, and null when the source did not report it: a message archived before the archive kept the flag, or one from a Telegram export import. A null flag counts as shown. It is the rule the viewer's pencil follows, and edited_messages in /api/chats/{chat_ref}/stats counts the same rows. Like deleted_only, it is a read that combines with search, topic_id and the cursors and stays inside the chat the ref names.

curl -s -b jar.txt \
  'http://localhost:8000/api/chats/<ref>/messages?limit=50&offset=0&edited_only=true'

Each message nests its media. media.id is the media key, {message_id}_{type}, and media.url is /media/{chat_ref}/{key}. media.downloaded is false for a row waiting for a download, such as a file check-media --repair marked to download again; such a row can keep its file_path. A kind with no file (geo, contact, poll, venue, geo_live and the others in Media) has media.url null, even when an older release left a file_path on it. The one exception is a location, a venue or a live location whose row holds its map picture (file_name of the form map_<16 hex>.jpg or .png): its media.url is the picture, served by the media route under the chat's rules, and file_name, file_size, mime_type, width and height describe it. A login whose downloads are off still gets null. A location Telegram served no picture for has skip_reason map_not_served. What it holds is in raw_data under a key named after the kind:

A field Telegram did not send is left out, so a location Telegram sent without a point has no lat or long. A message with no media row (the listener writes none for these kinds) still has its key in raw_data. A reply also carries reply_to_media_type, the kind of the message it answers, which comes from that message's raw_data when it has no media row, and reply_to_media_title, a venue's title, when it answers a venue. sender_avatar_url points at /media/avatar/{chat_ref}/{message_id}. Transcripts are attached when transcription is on.

In GET /api/chats/{chat_ref}/messages each message carries its reactions in two lists. reactions holds the live ones, one entry per emoji with its count. removed_reactions holds the reactions taken back that the archive kept, newest first: one entry per emoji, from its latest drop, with emoji, count (how many went), count_before (the count before the drop, above count when some stayed), removed_at (when the archive noticed, in UTC) and back_at (when an emoji taken back to zero was seen again, or null). An emoji that came back is in both lists. reaction_history lists every state of the message's reactions the archive kept, oldest first: emoji, count (0 when taken back), previous_count (null for the first state), observed_at and source (listener, backup, or baseline for a state copied from the reactions kept before 9.0). This route caps reaction_history so a busy post stays small: it holds the message's 20 newest states, plus each emoji's newest state, its latest drop and the first state with a count after that drop, so removed_reactions reads the same as from every state. reaction_history_omitted is how many older states it left out, 0 when the list is complete. Both exports return every state. Neither list names a person, because the archive stores counts per emoji. reactions[].user_ids can still list ids from rows written one per reactor before 7.23.0, until the backup or the listener reconciles that message again. /messages/by-date returns only reactions.

In GET /api/chats/{chat_ref}/messages each message also carries snapshots, the newest state the archive kept of its poll and of its link preview. See Poll and link preview snapshots.

Poll and link preview snapshots¶

raw_data.poll and raw_data.webpage hold a poll and a link preview as the archive first captured them, and never change. When a later read shows another state, the archive adds a snapshot: a poll's votes, results or closing, or the preview card's fields. A read that shows the newest kept state adds nothing. The listener writes them from edit events and poll updates, and the backup and the sync from their reads. Live locations are not followed.

snapshots is an object keyed by kind, poll or preview, and empty when the archive kept no later state. Each entry describes the newest state of that kind:

The snapshots read through the same chat and account as the messages: a viewer restricted to some accounts sees only the snapshots its accounts wrote. Both exports list every state, oldest first.

Message versions¶

Each earlier version of an edited message has these fields:

Only the listener sees each edit as it happens, and only while it runs: edits made while it was away reach it as one. The sync, a backup and an import read the text current at that moment, so several edits between two reads leave one version. When any version has one of those sources, or no source, the number of versions is a lower bound on the number of edits. The same holds when the oldest version's date is later than the message's date: the archive first saw the message already edited.

Search, tags and the change feed¶

All of these need any login. Results cover only chats the caller can see.

/api/search/messages is a word-prefix full-text search across chats, newest first. Each result has id, date, text, sender_name, sender_account_id, is_deleted, topic_title, matched_in and a chat object with ref, title, first_name, last_name, username, type, is_forum and avatar_url.

/api/tags/{tag} takes a #hashtag or a $CASHTAG and answers 400 for anything else. Encode # as %23 in the URL:

curl -s -b jar.txt 'http://localhost:8000/api/tags/%23holiday?scope=all&limit=50'

/api/changes lists deletions, edits and new transcripts, newest first, and with reactions=true the reactions taken back. Each change has kind, date, cursor, chat with ref, title and type, message_id and sender_name, plus:

A reaction row is one drop the archive kept in the reaction history: a count below the one before it, dated when the archive noticed. A partial drop and a complete one both list, and so does a removal kept before 9.0. A drop that two accounts holding one channel both saw lists once. They are left out without reactions=true, since they come and go far more often than the rest.

chat_ref narrows the feed to one chat. For a channel or group that several accounts hold, that is every copy the caller may see, and each change is listed once under the copy the feed for every chat lists it under, so a row's chat.ref can name another account's copy of the same chat. A private chat narrows to the copy that ref names, since each account's private chat with one person is a different conversation. A chat the caller cannot see answers 404, the same as an unknown ref. Paging works the same way.

Hard deletions never appear, and no-download logins get no transcript rows. The response is sent with Cache-Control: private, no-store.

To walk the feed, pass next_cursor from each answer as cursor on the next request, keeping the other parameters, until next_cursor comes back null. The walk is lossless: every change in the window is listed exactly once, however many share one timestamp and whatever the page size. Changes are ordered by date, newest first, then by kind (deleted, edited, transcript, reaction), then by the row's own keys, and the cursor names the place of one row in that order, so the next page starts right after it. Each row's cursor works the same way, if you stop partway and resume from a row you kept. It is opaque: sealed with a key the archive keeps in its database, so it names no chat id, cannot be edited, and still works after a restart. A malformed or edited cursor answers 400.

before still works for clients written before cursor: it is an exclusive date bound, and next_before is the last row's date. Paging with it skips the changes that share that exact date, so a burst of deletions stored at one instant can lose rows at a page boundary. Use cursor for anything that has to be complete, such as keeping evidence.

To poll for new changes, pass the time of your last poll as since:

curl -s -b jar.txt 'http://localhost:8000/api/changes?since=2026-09-28T00:00:00Z&limit=200'

Media¶

A media key has the form {message_id}_{type}, for example 42_photo or 7_video_note. Get keys from message payloads or from the media gallery route. An earlier photo or file an edit replaced has the key {message_id}_v{n}, from the url of its message version: n is its place among the message's earlier media, 1 for the first one kept. It works on the file, thumbnail and open routes, and the transcript routes read its transcripts; asking for a new transcript of it answers 404. A key for an earlier media the message does not have answers 404.

The viewer serves files a browser can show inline. It sends other files, and any request with download=1, as an attachment.

Media, thumbnails and avatars are sent with Cache-Control: private, no-cache, an ETag and a Last-Modified. The browser may keep a copy, but it asks the server before each reuse, and the viewer runs the same login and chat checks on that request. A session that still has access gets 304 Not Modified and no body, so the file is not sent again. A logged-out browser gets 401, never the kept copy. Copies cached by an older release, which did not ask, can still be reused until their old lifetime runs out, up to a day for thumbnails and avatars; logging out once over HTTPS clears them. Editing a viewer, or changing a token's chats or downloads, ends its sessions, so that browser gets 401 too. A session that no longer sees the chat gets 404. Originals and thumbnails answer 403 to a login whose downloads are off; avatars stay available to it. When its session ends, the viewer page reloads itself at the same address, so the next login on the same tab does not see the chat that was open until the server allows it again. The files under /static are not behind a login and keep their own caching.

Custom emoji¶

A reaction made with a custom emoji has emoji set to custom_<document_id>. A custom emoji in text is an entity {type: "custom_emoji", offset, length, document_id}, where document_id is a string of decimal digits in every viewer answer and live frame: the messages, pinned and by-date routes, message versions, and the new_message and edit frames. Before 9.3.0 it was a JSON number, which a browser rounds. The chat exports keep it a number. GET /api/custom-emoji?ids=<id>,<id>,... takes 1 to 100 decimal document ids and answers 400 for anything else. It answers an object keyed by the id as a string: a document id is larger than a JSON number holds without rounding in a browser. Each value is {kind, alt, text_color, ready}. kind is image, tgs or webm when the file is on disk, else null; alt is the ordinary emoji Telegram gives as its meaning; text_color is true when Telegram draws the emoji in the colour of the text; ready is true when the file can be fetched. An id the archive does not know is left out.

GET /media/emoji/{document_id} serves the file as image/webp, application/x-tgsticker or video/webm, and answers 404 for an id with no file. A file is named after its id and never rewritten, so it is sent with Cache-Control: private, max-age=31536000, immutable.

Both routes need a login that can read at least one chat, and answer 403 to a grant with no chat. They are not tied to a chat: the file is the same public emoji pack file for every chat. A share link and a login whose downloads are off can call them, as for avatars.

After an edit replaced a message's media, the url of its current media carries ?v={n}, so a browser never shows cached bytes of the old media under it. The routes ignore the parameter; add download=1 with &.

The gallery route takes types as a comma list, limit default 50, up to 200, and either before_id or after_id. Both take a media key; before_id pages to older items and after_id to newer ones. Sending both is a 400. It answers {items, has_more}, where each item has id set to the media key plus thumb_url and media_url, and the message's text, is_deleted and deleted_at.

The open routes answer {"ok": true} on success and 404 Not configured when their command is unset. /media/open accepts only types the viewer shows inline and answers 415 for others. /media/open-path accepts any type. Both answer 400 File name cannot be passed to the command when the file name cannot be passed to the command, and 500 when the command fails to start or exits non-zero within half a second.

Export¶

GET /api/chats/{chat_ref}/export streams a chat as one JSON file, or with format=html as a ZIP of HTML pages and media (see HTML export). It needs a login that can see the chat and answers 403 for no-download logins, in both formats. It is sent with Cache-Control: private, no-store, so neither the browser nor a proxy keeps a copy.

from must be before to, or the route answers 400. A changed_since that is not ISO 8601, an empty one included, answers 400. Without any of them, the export holds the whole chat. changed_since narrows from and to, and each message it keeps carries its whole history. A change the archive writes into the message row itself (a pin, a media download or a transcript that finishes later) does not select a message, and a message removed with DELETION_MODE=hard is gone from every export. It follows the same rules as the command's --changed-since, including the recipe for exporting on a schedule in Exporting only what changed. In a viewer export the chat ref and the message id together are the key to merge files on. Save the stream to a file:

curl -s -b jar.txt -o june.json \
  'http://localhost:8000/api/chats/<ref>/export?from=2026-06-01&to=2026-06-30'
curl -s -b jar.txt -o changes.json \
  'http://localhost:8000/api/chats/<ref>/export?changed_since=2026-06-01T03:59:55Z'

The response is an application/json attachment named <chat name>_export.json:

{
  "chat": {"id": -1001234567890, "ref": "<ref>", "type": "channel", "title": "Example", "username": null},
  "filters": {"from": "2026-06-01", "to": "2026-06-30"},
  "messages": []
}

filters appears only when from, to or changed_since was given. The window picks messages by their send date. With changed_since, filters also holds changed_since, the UTC time it was read as (ISO 8601, no offset).

Each message has id, date, sender (name, username), text, is_outgoing and reply_to, and these fields that say what the archive kept:

A location, a contact, a poll or another kind with no file has a media_payload object, keyed and shaped as in raw_data (see Paging through messages).

Each entry of versions has these fields:

The export pairs earlier media with versions the way the edit history does. It sits under the text version with the same date.

Export media¶

Each media entry, current or earlier, has these fields. None is a file path, and the JSON export holds no files.

So every transcript in the file names a media listed in the same file, on its message or under one of its versions. A voice note whose audio an edit replaced, with a transcript of each audio:

{
  "id": 1270,
  "text": "",
  "edit_date": "2026-10-01T10:40:00",
  "media": [
    {"media_id": "-1001900000001_1270_voice_v1", "type": "voice", "file_name": "1270_second.ogg",
     "file_size": 9000, "mime_type": "audio/ogg", "width": null, "height": null, "duration": 9}
  ],
  "versions": [
    {
      "text": "", "date": "2026-10-01T10:38:00", "captured_at": "2026-10-01T10:40:00",
      "source": "listener", "entities": null, "rich_message": null,
      "media": [
        {"media_id": "-1001900000001_1270_voice", "type": "voice", "file_name": "1270_first.ogg",
         "file_size": 7000, "mime_type": "audio/ogg", "width": null, "height": null, "duration": 7}
      ]
    }
  ],
  "transcripts": [
    {"media_id": "-1001900000001_1270_voice_v1", "text": "Meet at seven thirty at the north lot.", "...": "..."},
    {"media_id": "-1001900000001_1270_voice", "text": "Meet at eight at the south lot.", "...": "..."}
  ]
}

Before 9.0 the file also ended with a flat message_versions list. It is gone: every version is under its message. See Upgrading to 9.0.

Everything in the file is read from one snapshot of the archive, so a backup writing during the export cannot make a message disagree with its versions, its media, its reaction history, its snapshots or its transcripts. The export reads a message's versions, media, reaction states and snapshots as it writes that message, so a long chat is never held in memory at once. If they ever stop lining up with the messages, the export stops with an error instead of writing messages without them. The file then ends early and is not valid JSON.

HTML export¶

With format=html the route answers an application/zip attachment named <chat name>_export.zip. from, to and changed_since work as they do for JSON. Three more parameters choose the media:

These answer 400: a format other than json or html, an unknown name in media (the message names it), a max_file_mb outside 1 to 3900, and media, max_file_mb or players sent with format=json. The 403 for a no-download login comes before any of them.

curl -s -b jar.txt -o june.zip \
  'http://localhost:8000/api/chats/<ref>/export?format=html&media=photo,video,voice&max_file_mb=100&from=2026-06-01&to=2026-06-30'

The ZIP holds one folder, ChatExport_<chat name>/, laid out the way Telegram Desktop lays out its exports:

A media folder appears only when it holds a file. The names inside are ours, <message id>_<n> plus the file's extension, so no stored name can reach outside the folder. The original file name shows in the page and in the link's download attribute. The pages load no script, font or remote file. Each one sets a Content Security Policy that blocks scripts.

A file left out keeps its card without a link, with the reason: not included in this export, larger than the limit, not downloaded to the archive, or missing from the archive's storage. The ZIP is written while it streams, so the response has no Content-Length. The messages are first read from one snapshot of the archive into a temporary file on the server, about the size of the JSON export, so the snapshot closes before the download starts however slow the client is. If a file fails to read after its entry has started, the response stops before the ZIP's closing directory, and unzip reports the archive as broken instead of handing back a short one.

Transcripts¶

Each transcript has id, status, error, text, language, source, engine_name, engine_version, preset, models, confidence, duration_s, requested_at, completed_at and turns.

The POST routes queue a request, or return the one already open, and make no outbound call themselves. They answer 409 when transcription is off, when the media has no sound, or when the file is not downloaded yet. For anyone but the master they answer 429 with a Retry-After header after TRANSCRIPTION_ASK_RATE_LIMIT presses in 10 minutes from the same client, or when TRANSCRIPTION_ASK_MAX_OPEN pressed files already wait for the backup. A press on a file whose request is already open returns that request and is never refused. In an open viewer (ALLOW_ANONYMOUS_VIEWER=true) the same holds for a file whose newest result is done or skipped: the press returns it and queues nothing. A login's press on such a file queues it again. For the rate limit, Retry-After and the detail say when the next press is allowed. For the cap, room only comes back when a drain of the backup sends waiting files, so Retry-After is a polling hint of 15 minutes, the default TRANSCRIPTION_DRAIN_INTERVAL_MINUTES. All transcript routes except status answer 403 for no-download logins. Setup is in Voice transcription.

Live updates over WebSocket¶

/ws/updates is a WebSocket and is not in the OpenAPI document. There is no server-sent events endpoint.

The viewer checks the upgrade request the same way it checks any HTTP request, using the viewer_auth cookie or the proxy header. A failed login closes the socket with code 4001. The Origin header must match Host or appear in CORS_ORIGINS, or the socket closes with 4003. The viewer holds at most MAX_WS_CONNECTIONS sockets, default 200, and refuses more with close code 1013. Each socket follows at most MAX_WS_SUBSCRIPTIONS_PER_CONNECTION chats, default 16.

The client sends:

{"action": "subscribe", "chat_ref": "<ref>"}
{"action": "unsubscribe", "chat_ref": "<ref>"}
{"action": "ping"}

The server replies with subscribed, subscribe_denied, unsubscribed or pong. A denial past the subscription limit carries reason: "subscription_limit".

Event frames all carry type and chat_ref:

The nested media of a new_message frame's message, and of an edit frame, has the shape /api/chats/{ref}/messages gives a message's media: id is the {message_id}_{type} key, and url is the ref-addressed /media/ URL, or null when the file is not on disk. A location, a venue or a live location carries the URL of its map picture the same way. The URL of media an edit replaced ends in ?v={n}, so a browser never shows the earlier file from its cache. A login whose downloads are off gets url and file_path null and no_download: true, as on the messages route. An edit frame without media says the media did not change. It is also left out when the frame would pass PostgreSQL's notification size limit, after the entities; the text is never left out.

The viewer closes a socket with 4001 Session revoked when its session ends: logout, expiry, eviction, an admin change to the viewer account or share token behind it, or the end-all action. How updates reach the viewer is in Live updates and notifications.

Push notifications¶

/api/notifications/settings answers {"enabled": false, "reason": "Not authenticated"} when password login is on and the cookie is missing or expired.

POST /api/push/subscribe takes {endpoint, keys: {p256dh, auth}, chat_ref}, with chat_ref optional to follow one chat. It answers 400 unless PUSH_NOTIFICATIONS=full, 400 for an invalid endpoint, and 400 when the body sends chat_id instead of chat_ref. On success it answers {"status": "subscribed", "chat_ref": ...}. POST /api/push/unsubscribe takes {endpoint} and answers {"status": "unsubscribed"} or {"status": "not_found"}. It answers 400 Push notifications not enabled when push is off.

Administration¶

Every route here is master only, and every write lands in the audit log. The concepts behind them are in Logins, viewer accounts and share links.

Viewer accounts¶

The create body:

A taken name answers 409. The old field allowed_chat_ids answers 400. Create a viewer who sees two chats:

curl -s -b jar.txt -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"a-long-password","allowed_chat_refs":["<ref1>","<ref2>"]}' \
  http://localhost:8000/api/admin/viewers

{"id": 3, "username": "alice", "allowed_accounts": null, "allowed_chat_refs": ["<ref1>", "<ref2>"], "is_active": 1, "no_download": 0}

PUT takes any of the same fields. It answers 400 when the body changes nothing and 404 for an unknown id.

Share tokens¶

The create body takes label, allowed_chat_refs, no_download and expires_at as ISO 8601. allowed_chat_refs is required and must be a non-empty list: a share token always has a scope.

curl -s -b jar.txt -H 'Content-Type: application/json' \
  -d '{"label":"family","allowed_chat_refs":["<ref1>"],"no_download":true,"expires_at":"2026-12-31T23:59:59Z"}' \
  http://localhost:8000/api/admin/tokens

{"id": 5, "label": "family", "token": "<64 hex characters>", "allowed_chat_refs": ["<ref1>"], "no_download": 1, "expires_at": "2026-12-31T23:59:59", "created_at": "2026-09-28T10:00:00"}

Build a share link as https://<viewer address>/#token=<token>.

End sessions¶

There is no route that lists or ends sessions by id. These calls end sessions:

Lock a viewer out without deleting the account:

curl -s -b jar.txt -X PUT -H 'Content-Type: application/json' \
  -d '{"is_active":false}' http://localhost:8000/api/admin/viewers/3

Revoke a share token:

curl -s -b jar.txt -X PUT -H 'Content-Type: application/json' \
  -d '{"is_revoked":true}' http://localhost:8000/api/admin/tokens/5

End every session but your own, for example after changing VIEWER_PASSWORD:

curl -s -b jar.txt -X POST "http://localhost:8000/api/admin/sessions/end-all?keep_current=true"

Only POST /api/admin/sessions/end-all ends a session of the master login. Changing VIEWER_PASSWORD does not. A second viewer on the same database drops the ended sessions within 60 seconds. See A second viewer.

Audit log and settings¶

Internal endpoints¶

These routes serve other parts of the system. Clients should not call them.

Errors and headers¶

Errors come back as {"detail": "..."}.

CORS_ORIGINS defaults to * with credentials off, so a browser page on another origin cannot send the cookie. List explicit origins to turn credentials on for them. Every response carries X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, Referrer-Policy: strict-origin-when-cross-origin and a same-origin Content-Security-Policy.