Aether Plug-In API v1

Programmatic access to your archive, your vault and your account settings.

Introduction

Aether Plug-In is a REST API that gives your own programs access to your Aether account: the archive of your Business chats, your vault and your account settings. Everything you can do from the bot's screens, you can do from a script, a webhook or a service of your own.

Access is granted through an application. An application is a named API key with a billing arrangement attached to it. It belongs to your account, it can reach your account only, and there is no OAuth flow, consent screen or third party involved — you create one in the bot and start making requests.

Aether Plug-In is included with the 🛸 Max plan. A 🛸 Max account may hold up to 3 applications, each with its own key. Should the subscription lapse, your applications, keys and balances are kept intact — the keys simply stop answering until 🛸 Max is active again.

Scope of the API

The API is deliberately narrow, and it helps to know its boundaries before you begin:

  • The archive is read-only. Messages enter the archive by being sent in a Business chat and by no other route. The API lets you search, read and export them; it never inserts, edits or removes them.
  • Applications are managed in the bot. Creating an application, regenerating its key, changing its billing mode and funding its balance are all done from the bot. A key cannot create other keys or add money to itself.
  • An application spends only its own balance. The API never buys a subscription and never tops up your account.

Obtaining an API key

To get started, open the bot and navigate to Menu → Applications. Create an application, give it a name and pick a billing mode — both may be changed at any time. The API key is displayed once, on the screen that creates it, so copy it somewhere safe before leaving that screen.

Afterwards, the bot only ever shows the first twelve characters of a key, which is enough to tell your keys apart. If you lose a key, regenerate it from the same screen: the new key works immediately and the old one stops working at the same moment.

A key is 47 characters long and looks like this:

aek_dGhpcyBpcyBub3QgYSByZWFsIGtleSBhdCBhbGw

Treat your API key like a password. Anyone holding it can read your archive and open your vault with the keys it knows.

Scopes

A new key can read: the archive, the account, the vault's entries with their keys. What reaches past that into something you cannot take back is opened to a key separately, by you, on the application's screen in the bot — and it is closed by default, for every application including the ones created before scopes existed:

  • settings:write — changing the account's settings: the retention policy (which can delete messages from your real chats in Telegram), the vault's reveal window, the Actions prefix and the language.
  • vault:write — writing to the vault: saving an entry, moving one to another key, issuing its recovery codes, recovering it and deleting it.

A request a key's scopes do not cover is answered 403 with the error code scope_required and the scope it needs; nothing is charged, and nothing in the request can open it.

Authentication

The API authenticates every request with your application's key. Pass it as a bearer token in the Authorization header:

curl https://aether.xchunk.org/v1/account \
  -H "Authorization: Bearer aek_your-key-here"

Two alternative forms are accepted for clients that cannot set an Authorization header in the usual way — some webhook configuration screens, for instance. You may send the bare key without the Bearer scheme, or send it in the X-Aether-Key header. All three forms are equivalent.

curl https://aether.xchunk.org/v1/account \
  -H "X-Aether-Key: aek_your-key-here"

Authentication failures

A request with a missing, malformed or unknown key receives a 401 Unauthorized response with the code unauthorized and a WWW-Authenticate header. A request with a valid key receives 403 Forbidden when the application has been disabled, the account is blocked, or the account's plan no longer includes Aether Plug-In.

Making requests

All endpoints live under /v1 and speak JSON. Requests that carry a body should set Content-Type: application/json. Here is a complete first request that searches your archive and shows the billing headers returned with it:

curl -sS -D- https://aether.xchunk.org/v1/messages/search \
  -H "Authorization: Bearer $AETHER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conditions":[{"field":"text","mode":"ct","value":"invoice"}]}'

HTTP/1.1 200 OK
X-Aether-Billing: credits
X-Aether-Cost: 1000
X-Aether-Balance: 4999000
X-Aether-Ops: search:query

{"ok":true,"data":{"messages":[…],"total":37,"page":0,"pages":4,"per_page":10,"query_id":"5tQx0bYFvHh1nC2kq9Lr3w"}}

The X-Aether-Cost header is expressed in credits, so 1000 is a tenth of a cent. An application on shared limits reports a cost of 0 and no balance header — see Billing headers for the full set.

The search is what is billed, once. Its other pages are free: pass the query_id to POST /v1/messages/search/page with the page you want, for up to 30 minutes after the search was run.

Every endpoint takes the method shown in its reference and no other. HEAD is not accepted: it is answered with 405 method_not_allowed and nothing is charged. Responses are never cached — every one of them carries Cache-Control: no-store.

Responses

Every response is a JSON object in one of two shapes. A successful request returns ok: true and the payload under data:

{"ok": true, "data": { … }}

A request that could not be fulfilled returns ok: false and an error object:

{"ok": false, "error": {"code": "quota_exhausted",
                        "message": "the plan's quota for this operation is spent",
                        "limit": "search:daily", "used": 2000, "limit_value": 2000,
                        "reset_at": 1757203200}}

When handling errors, branch on code rather than message. The code is stable and part of the API contract; the message is written for a human reading a log and may change between versions. Some codes come with a reason that narrows them down — why a portrait is not available, for instance — and it is just as stable.

The same shape is used for a path under /v1 that is not an endpoint (404 not_found) and for a method an endpoint does not accept (405 method_not_allowed, with the accepted methods in the Allow header).

POST /v1/messages/export is the one exception to the envelope: it responds with the export document itself, so your client can stream it straight to a file.

Error handling

Every error response carries one of the codes below, along with the HTTP status shown.

CodeStatusMeaningRecommended action
bad_request400The request body or parameters are invalid.Check the message: it names the offending field.
unauthorized401The API key is missing, malformed or unknown.Send your key as Authorization: Bearer <key>. If it was regenerated, use the new one.
forbidden403The key is valid, but this request is not permitted.The response names the required permission and the plan that includes it.
account_blocked403The account has been blocked.The request cannot be retried.
not_found404The resource does not exist or is not yours, or the path is not an endpoint.Check the id and the path. A wrong vault passphrase also returns this code.
method_not_allowed405The endpoint does not accept this method. HEAD is not accepted anywhere.Use a method from the Allow header.
conflict409The resource conflicts with one that already exists.Choose another name.
quota_exhausted429A plan quota has been used up. Only under shared limits.Wait until reset_at, or switch the application to hybrid.
scope_required403The application's owner has not opened what the request does to its key: settings:write or vault:write, named in scope.Ask the owner to open the scope on the application's screen in the bot. Nothing in the request can.
rate_limited429Too many requests in a short time — or, with reason vault_locked, too many wrong keys and recovery codes tried on the account's vault, which then takes none for a while and tells its owner.Wait for the number of seconds in retry_after (also sent as the Retry-After header).
insufficient_credits402The application's balance cannot cover the request.Fund the application from your account balance in the bot.
too_large413The export would be larger than 50 MB. Nothing was charged.Narrow the export with a chat or a filter.
busy503Aether has no room for the request right now. Nothing was charged.Retry after the number of seconds in Retry-After.
unavailable503What you asked for cannot be served as things stand. error.reason says why.Retry after Retry-After when it is sent; otherwise retrying will not help.
internal500Something went wrong on our side. Any charge has been refunded.Retry the request. If the problem persists, let us know.

Errors are never billed

You pay for successful responses, not for attempts. A request that ends in an error — an invalid request, a refusal, a rate limit or a failure on our side — is refunded in full before the response is sent, so the balance reported in the response headers is always the balance you actually have. In the rare event that a refund could not be applied, the headers report what was actually charged, and the charge is returned automatically within about a quarter of an hour.

Usage counts answers the same way: a request that ends in an error is taken off the call counts in GET /v1/usage and GET /v1/app together with its charge, whichever billing mode the application is on.

Exports are billed when the document has been sent. An export that fails on our side is refunded — before the download starts it is an ordinary error response, and after that the connection is closed early, so a cut-off document is never mistaken for a complete one. If you stop reading an export part-way through, it is charged; one that never reached you is not.

Billing modes

Each application is billed in exactly one of three modes. The mode is chosen when you create the application and may be switched at any time from the bot; a switch takes effect on the very next request.

Shared limits shared

Your plan pays. The balance is never charged.

  • Every request counts against your account's quotas, exactly as if you had done the same thing in the bot.
  • When a quota is used up, the request is refused with 429 quota_exhausted and reset_at tells you when it becomes available again.
  • The plan's rate limit applies.
  • The application does not need a balance; it is never charged.

Usage credits credits

The application pays. Your account's quotas are left untouched.

  • Every priced operation is charged to the application's balance.
  • Your account's daily quotas — searches, exports, portraits — are neither checked nor spent.
  • Ceilings on what your account may hold still apply, and credits pay to exceed them: a vault entry beyond the plan's ceiling is charged vault:entry once, when it is created.
  • No product rate limit; only the safety ceiling applies.
  • If the balance cannot cover a request, it is refused with 402 insufficient_credits and nothing is performed.

Hybrid hybrid

Your plan pays while it has room; credits cover the rest.

  • Every request counts against your plan first, exactly as under shared limits.
  • An operation your plan's quota can no longer cover is charged to credits. The plan is asked again on every request, so the moment the quota resets, or your plan grows, it pays again. Other quotas are unaffected.
  • Operations with no quota behind them — reading a message, opening a vault entry — are covered by your plan and never charged.

Under hybrid, an operation your plan's quota can no longer cover is charged to the application's balance at the full price. The plan is asked on every request, so an operation it covers is never charged. An operation is never both counted against the quota and charged to the balance, and never neither.

Credits

An application's balance is kept in credits. One credit is one millionth of a US dollar — a finer unit than the account balance, because a search costs a tenth of a cent while a subscription is bought a month at a time.

One cent of account balance converts to 10000 credits, and one dollar to 1000000. The conversion is exact in both directions: nothing is lost when you fund an application, and nothing is lost when you withdraw the money back to your account.

Applications are funded from your account balance in the bot. They cannot be funded through the API or directly from a card, an application cannot spend more than has been put on it, and it can never take your account into debt.

Price list

The prices below are the ones currently in force on this deployment. They are also available at runtime from GET /v1/prices, so a client can always read live prices rather than rely on this page.

The When column describes when the balance is charged. Every call marks an operation that is billed each time it runs: under credits the balance pays, under shared limits your plan pays, and under hybrid your plan pays until its quota is used up. Past the plan marks a ceiling on what your account may hold: staying within the ceiling is free on every mode, and credits only pay for going beyond it.

OperationPerPriceWhenPlan quota
search:query
One search of the archive, or the count behind one. Paging through the answer by its query_id is free (search:page).
query $0.001 every call search:daily
search:page
Another page of a query already paid for, by the query_id its first page answered with.
page free never —
messages:read
One read that is not a search: the chat list, a single message, a message's edit history.
request $0.00025 every call —
export:run
Starting one export, whatever it turns out to hold.
export $0.025 every call export:weekly
export:message
One message inside an export, charged up front for the whole result before a byte of it is written.
message $0.0001 every call export:messages
portrait:build
One chat portrait. Under credits every request is charged, including a repeat of the same chat.
portrait $0.05 every call portrait:weekly
glance:insights
The whole archive summarised in one answer.
request $0.005 every call —
vault:read
One decryption: opening an entry with its passphrase, or recovering one with a code.
request $0.0025 every call —
vault:write
One write that touches key material: saving an entry, renaming it, reissuing its recovery codes.
request $0.005 every call —
vault:entry
One entry kept past the plan's ceiling, charged once when it is written.
entry $0.025 past the plan vault:entries
vault:delete
Destroying an entry. Free on every billing mode.
request free never —
actions:read
One read of the shortcuts an account keeps.
request $0.0001 every call —
actions:write
Creating, renaming, editing or deleting one shortcut.
request $0.001 every call —
actions:entry
One shortcut kept past the plan's ceiling, charged once when it is created.
action $0.01 past the plan actions:saved
account:read
The plan, the quotas, the settings and the application's own state. Free on every billing mode.
request free never —
settings:write
Changing a retention or language setting. Free on every billing mode.
request free never —

For reference: a Max subscription costs $19.99 a month and includes 2,000 searches a day, while the same searches paid for in credits would come to $2.00 a day. Credits are the way to use the API without worrying about ceilings — not a cheaper way to buy the product.

Rate limits

Requests are rate limited per application, and the applications of one account share a ceiling of their own above that, as does the API as a whole. The limit of an application depends on its billing mode:

ModesRequests / secondBurstNotes
shared, hybrid1020The plan's own rate limit. If you reach it, slow down and retry after the interval in Retry-After.
credits50100Credits carry no product rate limit; this is only a safety ceiling. A well-behaved client should never reach it.
all applications of one account60120Shared by every application of the account, whatever their modes. A safety ceiling, like the one under credits.
the whole API300600Shared by every application of every account. Reaching it is our capacity, not your client: retry after Retry-After.

A request over the limit receives 429 Too Many Requests with the error code rate_limited and a Retry-After header telling you how long to wait.

Under shared limits, a request may also be answered with quota_exhausted straight away when the plan's quota for that operation is already known to be spent. Quota state is refreshed at least every 30 seconds, so a quota that has just reset may take a few seconds to become available again. A request is never charged or counted by this early refusal.

Billing headers

Every response to a request whose key was accepted includes headers describing what the request cost, so a client can meter its own usage without a second request. A request refused before that — a missing or unknown key, a blocked account, a path that is not an endpoint, a method an endpoint does not accept — carries none of them, and nothing was charged.

HeaderDescription
X-Aether-BillingThe billing mode the request was served under: shared, credits or hybrid.
X-Aether-CostThe cost of this request in credits. Zero under shared limits and for free operations.
X-Aether-BalanceThe application's remaining balance in credits, as of this request. Omitted under shared limits, and in the rare case the balance could not be read.
X-Aether-OpsThe operations this request was billed for, comma-separated.
X-Aether-Quota-ResetWhen the exhausted quota resets, as a Unix timestamp. Sent with quota_exhausted.
Retry-AfterHow many seconds to wait before retrying. Sent with rate_limited, busy, and unavailable when waiting helps.

Application

GET /v1/app free

Retrieve the current application

Returns the application your key belongs to: its name, billing mode, remaining balance and spending so far. The key itself is never returned; it was shown once, when it was issued.

Response · data

{
  "id": 12,
  "name": "Support desk",
  "billing": "hybrid",
  "key_prefix": "aek_7Fh2Kd",
  "key_issued_at": "2026-09-01T10:04:11Z",
  "balance": {"credits": 4975000, "display": "$4.975"},
  "funded": {"credits": 5000000, "display": "$5.00"},
  "spent": {"credits": 25000, "display": "$0.025"},
  "requests": 1204,
  "last_used_at": "2026-09-06T08:22:40Z",
  "disabled": false,
  "created_at": "2026-09-01T10:04:11Z",
  "account_id": 1256738876
}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode, so an application can always check its balance even after it has run out of credits.
  • The balance is read at the moment of the call, and the X-Aether-Balance header of this response carries the same figure.
GET /v1/usage free

Retrieve usage

Returns the application's spending over a period, aggregated per priced operation. Pass by_day=true to receive the same totals broken down by day.

Parameters

NameInTypeRequiredDescription
days query integer no · default 30 Number of days to cover, 1 to 365.
by_day query boolean no · default false Include the day-by-day breakdown: true or false. Anything else is refused.

Response · data

{
  "from": "2026-08-08",
  "to": "2026-09-06",
  "calls": 1204,
  "credits": {"credits": 25000, "display": "$0.025"},
  "ops": [
    {"op": "search:query", "calls": 20, "units": 20, "credits": {"credits": 20000, "display": "$0.02"}},
    {"op": "messages:read", "calls": 20, "units": 20, "credits": {"credits": 5000, "display": "$0.005"}}
  ]
}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
  • calls counts billed operations rather than HTTP requests: a single export bills two operations.
GET /v1/account free

Retrieve the account

Returns the account your key belongs to: its plan, the permissions it includes, when it expires, the account balance in cents and every quota with its current usage.

Response · data

{
  "account_id": 1256738876,
  "plan": {
    "tier": "max",
    "name": "Max",
    "price_cents": 1999,
    "until": "2026-10-01T00:00:00Z",
    "permissions": ["glance:allow_insights", "plugin:allow_use"]
  },
  "balance_cents": 1204,
  "quotas": [
    {"key": "search:daily", "label": "Searches", "unit": "searches", "limit": 2000,
     "used": 41, "remaining": 1959, "unlimited": false, "window": "day",
     "reset_at": "2026-09-07T00:00:00Z"}
  ],
  "measured_at": 1757160000
}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
  • balance_cents is your account balance. It cannot be spent through the API; funding an application from it is done in the bot.
  • The report is measured at most once every 10 seconds per account, and measured_at says when: polling it faster returns the same reading.
GET /v1/quotas free

Retrieve quotas

Returns the quotas section of GET /v1/account on its own, for clients that poll it. Under shared limits it shows how much room is left before requests are refused; under hybrid, how much is left before requests start costing credits.

Response · data

[
  {"key": "messages:stored", "label": "Archived messages", "unit": "messages",
   "limit": 1000000, "used": 51204, "remaining": 948796, "unlimited": false},
  {"key": "export:weekly", "label": "Exports", "unit": "exports", "limit": 100,
   "used": 3, "remaining": 97, "unlimited": false, "window": "week",
   "reset_at": "2026-09-08T00:00:00Z"}
]

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
  • Read from the same reading as GET /v1/account, at most 10 seconds old.
GET /v1/prices free

Retrieve prices and rate limits

Returns the price of every operation, the number of credits one cent buys and the rate limits of each billing mode, as currently configured on this deployment.

Response · data

{
  "prices": [
    {"op": "search:query", "label": "Archive query", "unit": "query",
     "price": {"credits": 1000, "display": "$0.001"}, "limit": "search:daily",
     "charging": "always", "description": "One search of the archive, or the count behind one."}
  ],
  "credits_per_cent": 10000,
  "rates": {
    "shared":  {"per_second": 10, "burst": 20},
    "hybrid":  {"per_second": 10, "burst": 20},
    "credits": {"per_second": 50, "burst": 100}
  },
  "account_rate": {"per_second": 60, "burst": 120},
  "global_rate": {"per_second": 300, "burst": 600},
  "quota_ttl_seconds": 30
}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.

Archive

POST /v1/messages/search

Search messages

Runs a query against your archived messages and returns one page of matches. Conditions are combined in the order given; the number of conditions per query, and substring matching, depend on your plan.

Request body

{
  "chat": -1001234567890,
  "conditions": [
    {"field": "text", "mode": "ct", "value": "invoice"},
    {"field": "created", "mode": "eq", "conn": "and", "value": "2026-09-01"}
  ],
  "page": 0
}

Response · data

{
  "messages": [
    {"id": 90210, "message_id": 4471, "chat": -1001234567890, "sender": 1256738876,
     "receiver": 42, "text": "the invoice is attached", "sender_username": "ann",
     "deleted": false, "created_at": "2026-09-01T09:14:02Z", "versions": 2}
  ],
  "total": 37,
  "page": 0,
  "pages": 4,
  "per_page": 10,
  "query_id": "5tQx0bYFvHh1nC2kq9Lr3w"
}

Billing

Under credits, $0.001 per query. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies. Counts against the search:daily quota of your plan.

Notes

  • Every call is one query and is billed as one, whatever page it asks for. The other pages of the same query are free through POST /v1/messages/search/page with the query_id this answer carries.
  • Under shared limits each call spends one of the plan's daily searches. Under hybrid the plan pays until the daily allowance is used up and credits pay after that. Under credits the allowance is not touched.
  • GET /v1/fields lists the fields a condition may use.
  • A text value is matched exactly as sent, spaces included. A date matches a whole day: a plain date is that day in UTC, and a timestamp with an offset, such as 2026-09-01T00:30:00+05:00, is that calendar day in its own zone.
  • The total and the page in one answer always describe the same moment. The page number is a live position, so a message archived between two requests shifts the pages after it.
POST /v1/messages/search/page free

Turn a page of a search

Returns another page of a search already run, named by the query_id its answer carried: the same chat and the same conditions, at the page asked for.

Request body

{"query_id": "5tQx0bYFvHh1nC2kq9Lr3w", "page": 1}

Response · data

{
  "messages": [
    {"id": 90190, "message_id": 4402, "chat": -1001234567890, "sender": 1256738876,
     "receiver": 42, "text": "invoice for August", "deleted": false,
     "created_at": "2026-08-30T17:40:11Z", "versions": 1}
  ],
  "total": 37,
  "page": 1,
  "pages": 4,
  "per_page": 10,
  "query_id": "5tQx0bYFvHh1nC2kq9Lr3w"
}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode, and it spends no search: the query was paid for by its first page.
  • A query can be paged for 30 minutes after it was run, by the application that ran it; an application keeps its 20 most recent. After that — or after a restart of the service — the answer is 404 not_found, and the search is run again.
  • The plan's rules on the query apply to every page, as they did to the first. The page number is a live position, exactly as in POST /v1/messages/search.
POST /v1/messages/count

Count matching messages

Accepts the same query as the search endpoint and returns only the number of matches.

Request body

{
  "conditions": [{"field": "media", "mode": "eq", "value": "photo"}]
}

Response · data

{"total": 412}

Billing

Under credits, $0.001 per query. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

Notes

  • Does not spend a search from the plan's daily allowance, just as counting in the bot does not.
  • Under credits it is billed as one query.
POST /v1/messages/export requires Exports · Free

Export messages

Returns every message matching the query as a single JSON document. This is the only endpoint that does not use the response envelope: the body is the document itself, so it can be written straight to a file. The number of messages is sent in the X-Aether-Export-Total header and in the document's own total field.

Request body

{
  "chat": -1001234567890,
  "conditions": [{"field": "created", "mode": "eq", "value": "2026-09-01"}]
}

Response · data

{
  "account_id": 1256738876,
  "exported_at": "2026-09-06T08:30:00Z",
  "total": 412,
  "filters": 1,
  "chat": -1001234567890,
  "messages": [ … ]
}

Billing

Under credits, $0.025 per export. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies. Counts against the export:weekly quota of your plan.

Notes

  • The whole export is priced and charged before the first byte is sent: export:run for the export itself plus export:message for every message in it. An application that cannot cover it never starts one.
  • The document is the archive as it stood when the export began: a message archived, edited or removed while it is prepared is not in it, and total is exactly the number of messages it holds.
  • An export is capped at 50 MB. An export that would pass the cap is refused with too_large before a byte is sent, and nothing is charged.
  • The charge becomes final when the document has gone out. An export that fails on our side is refunded — before the first byte as an ordinary error response, after it by breaking the connection off, so a cut-off document never arrives as a complete one. An export you stop reading is charged if any of it reached you; X-Aether-Cost states the charge as it stood when the document started.
  • Under shared limits the plan's weekly export allowance and export size ceiling apply. Under credits neither does, and every message is paid for.
GET /v1/chats

List chats

Returns one page of the chats in your archive, with the number of messages in each.

Parameters

NameInTypeRequiredDescription
page query integer no · default 0 The page to return, starting at 0.

Response · data

{
  "chats": [{"id": -1001234567890, "title": "Ann Weber", "messages": 4471}],
  "total": 38,
  "page": 0
}

Billing

Under credits, $0.00025 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

GET /v1/messages/{id}

Retrieve a message

Returns a single message by its archive id — the id field of a search result. This is not Telegram's message id, which is only unique within a chat.

Parameters

NameInTypeRequiredDescription
id path integer yes The message's archive id.

Response · data

{
  "id": 90210, "message_id": 4471, "chat": -1001234567890, "sender": 1256738876,
  "receiver": 42, "text": "the invoice is attached", "media_type": "document",
  "file_id": "BQACAgIAAx…", "deleted": false, "created_at": "2026-09-01T09:14:02Z"
}

Billing

Under credits, $0.00025 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

Notes

  • file_id is only included when your plan includes the media viewer. Otherwise the message is returned without it.
GET /v1/messages/{id}/versions requires Edit history · Pro

Retrieve message versions

Returns every version of a message's text, latest first. The first entry is the current text; how far back the history goes depends on your plan.

Parameters

NameInTypeRequiredDescription
id path integer yes The message's archive id.

Response · data

{
  "versions": [
    {"text": "the invoice is attached", "at": 1756719242, "current": true},
    {"text": "the invoce is attached", "at": 1756719190, "current": false}
  ]
}

Billing

Under credits, $0.00025 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

GET /v1/fields free

List searchable fields

Returns every field a search condition may use, together with the match modes each accepts. A field that is not listed here is not accepted in a query.

Response · data

[
  {"key": "text", "kind": "string", "modes": ["ct", "eq"]},
  {"key": "chat", "kind": "int64", "modes": ["eq"]},
  {"key": "created", "kind": "time", "modes": ["eq"]}
]

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.

Vault

POST /v1/vault/entries scope vault:write

Store a secret

Encrypts a secret under a passphrase and returns the id of the new entry and the one-time recovery codes issued with it. The passphrase is never stored, and the entry cannot be opened without either the passphrase or one of the codes — not even by Aether.

Request body

{
  "passphrase": "the pale blue dot",
  "plaintext": "AKIA…"
}

Response · data

{"entry_id": 31, "recovery_codes": ["7K3QMX9TBA4F8ZRQW2NCHD6PVJ", "Q2W8ERT4YA9M3PKZX7CVBN5H1D", "H6J4K2NM8NP9Q3RS5T7VW1X0YZ", "A1B2C3D4E5F6G7H8J9KM0NPQRS"]}

Billing

Under credits, $0.005 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies. Counts against the vault:entries quota of your plan.

Notes

  • The recovery codes are returned once and cannot be retrieved later. Store them safely.
  • entry_id is what DELETE /v1/vault/entries/{id} takes. It addresses the entry and opens nothing.
  • Under shared limits the plan's ceiling on entries applies. Under credits and hybrid an entry beyond that ceiling is charged once, as vault:entry, when it is created.
POST /v1/vault/entries/reveal

Reveal a secret

Decrypts the entry that the passphrase opens and returns its plaintext.

Request body

{"passphrase": "the pale blue dot"}

Response · data

{"plaintext": "AKIA…"}

Billing

Under credits, $0.0025 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

Notes

  • The passphrase is always sent in the request body, never in the path or query string.
  • A passphrase that opens nothing returns 404 — deliberately the same response as a wrong passphrase.
POST /v1/vault/entries/rename requires Vault renames · Go scope vault:write

Change a passphrase

Moves an entry to a new passphrase. The secret itself is unchanged; only the passphrase that opens it is.

Request body

{"passphrase": "the pale blue dot", "new_passphrase": "a mote of dust"}

Response · data

{}

Billing

Under credits, $0.005 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

POST /v1/vault/entries/codes scope vault:write

Reissue recovery codes

Discards the entry's existing recovery codes and issues a fresh set. Use it when a set may have leaked: the old codes stop working the moment this call returns.

Request body

{"passphrase": "the pale blue dot"}

Response · data

{"recovery_codes": ["7K3QMX9TBA4F8ZRQW2NCHD6PVJ", "Q2W8ERT4YA9M3PKZX7CVBN5H1D", "H6J4K2NM8NP9Q3RS5T7VW1X0YZ", "A1B2C3D4E5F6G7H8J9KM0NPQRS"]}

Billing

Under credits, $0.005 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

POST /v1/vault/entries/recover scope vault:write

Recover a secret

Opens an entry with one of its one-time recovery codes and moves it to a new passphrase. The code is spent, the remaining codes are replaced with a fresh set, and from then on the entry opens with the new passphrase.

Request body

{"code": "7K3QM-X9TBA-4F8ZR-QW2NC-HD6PVJ", "new_passphrase": "a mote of dust"}

Response · data

{
  "plaintext": "AKIA…",
  "rekeyed": true,
  "recovery_codes": ["Z9Y8X7W6V5T4S3R2Q1P0NMKJHG", "F3E2D1C0BA9Z8Y7X6W5V4T3S2R", "M5N6P7Q8R9S0T1V2W3X4Y5Z6A7", "B8C9D0E1F2G3H4J5K6M7N8P9QR"],
  "revoked": 3
}

Billing

Under credits, $0.0025 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

Notes

  • new_passphrase is required: the fresh codes exist only in this answer, and an entry you can still open with a passphrase you chose is not lost with it if the answer never arrives.
  • Using a recovery code always notifies the account owner in Telegram.
POST /v1/vault/entries/delete free scope vault:write

Delete a secret by passphrase

Deletes the entry that the passphrase opens. This is a POST rather than a DELETE because the passphrase belongs in a request body.

Request body

{"passphrase": "the pale blue dot"}

Response · data

{}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
  • The entry is removed permanently, and its passphrase may be used for a new entry right away.
DELETE /v1/vault/entries/{id} free scope vault:write

Delete a secret by id

Deletes an entry by the entry_id returned when it was stored.

Parameters

NameInTypeRequiredDescription
id path integer yes The entry_id the store answered with.

Response · data

{}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.

Actions

GET /v1/actions requires Actions · Go

List shortcuts

Returns every shortcut on your account, the prefix they are typed after, and how many more your plan allows.

Response · data

{
  "prefix": ".",
  "actions": [
    {"id": 3, "name": "kiss", "body": "Hi [[YOU_FIRST]], sending this over now.",
     "uses": 42, "used_at": 1757145760,
     "created_at": "2026-08-01T12:00:00Z", "updated_at": "2026-08-01T12:00:00Z"}
  ],
  "quota": {"key": "actions:saved", "label": "Actions", "unit": "actions",
            "limit": 50, "used": 1, "remaining": 49, "unlimited": false}
}

Billing

Under credits, $0.0001 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

POST /v1/actions requires Actions · Go

Create a shortcut

Creates a shortcut. The name is what you type after the prefix and must be unique on your account; the body is the text the bot sends in its place, placeholders included.

Request body

{"name": "kiss", "body": "Hi [[YOU_FIRST]], sending this over now."}

Response · data

{"id": 3, "name": "kiss", "body": "Hi [[YOU_FIRST]], sending this over now.",
 "min_args": 0, "args_required": false,
 "uses": 0, "created_at": "2026-09-06T08:40:00Z", "updated_at": "2026-09-06T08:40:00Z"}

Billing

Under credits, $0.001 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies. Counts against the actions:saved quota of your plan.

Notes

  • A body that uses a placeholder your plan does not include is refused here, rather than rendering as nothing in a conversation later.
  • A body is at most 900 UTF-16 code units — a letter of any alphabet is one, an emoji two — so it always fits a caption once media is attached. A longer body, or one containing a NUL character, is refused with 400 bad_request.
  • Under credits and hybrid a shortcut beyond the plan's ceiling is charged once, as actions:entry, when it is created.
GET /v1/actions/placeholders requires Actions · Go

List placeholders

Returns every placeholder a shortcut body may use and whether your plan includes it, so a client can validate a body before creating it.

Response · data

[
  {"token": "[[YOU_FIRST]]", "label": "you_first", "level": "basic", "allowed": true},
  {"token": "[[ARG1]]", "label": "arg", "level": "basic", "allowed": true},
  {"token": "[[STARS]]", "label": "stars", "level": "exclusive", "allowed": false,
   "required_plan": "max"}
]

Billing

Under credits, $0.0001 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

GET /v1/actions/{id} requires Actions · Go

Retrieve a shortcut

Returns a single shortcut by its id.

Parameters

NameInTypeRequiredDescription
id path integer yes The shortcut's id.

Response · data

{"id": 3, "name": "kiss", "body": "Hi [[YOU_FIRST]], sending this over now.",
 "uses": 42, "used_at": 1757145760,
 "created_at": "2026-08-01T12:00:00Z", "updated_at": "2026-08-01T12:00:00Z"}

Billing

Under credits, $0.0001 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

Notes

  • uses counts the calls that matched the shortcut, counted before the message is rendered and sent — a call that rendered to nothing or that Telegram refused is one of them. used_at is the latest of them, as a Unix timestamp.
PATCH /v1/actions/{id} requires Actions · Go

Update a shortcut

Updates a shortcut. Every field is optional and only the fields present are changed, all of them in one write: a request that fails on one field — a rename that collides, a body that is refused — changes none of them, and a request that succeeds changes all of them at once, so a body and its args_required never apply separately.

Parameters

NameInTypeRequiredDescription
id path integer yes The shortcut's id.

Request body

{"body": "Order [[ARG1]] is ready, [[ARG2]].", "args_required": true}

Response · data

{"id": 3, "name": "order", "body": "Order [[ARG1]] is ready, [[ARG2]].",
 "min_args": 2, "args_required": true, "uses": 42}

Billing

Under credits, $0.001 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

Notes

  • A body reads the words typed after the shortcut through [[ARG1]] … [[ARG9]] and [[ARGS]]. min_args is derived from the body and is read-only.
  • With args_required false, a call with fewer words still fires and the missing arguments render as empty; with it true, the shortcut does not fire and your message is sent exactly as typed.
  • A request that only switches args_required is accepted on every plan, so a shortcut made on an earlier plan can still be put the way you want it.
DELETE /v1/actions/{id} requires Actions · Go

Delete a shortcut

Deletes a shortcut. Its name becomes available again immediately.

Parameters

NameInTypeRequiredDescription
id path integer yes The shortcut's id.

Response · data

{}

Billing

Under credits, $0.001 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

Insights

GET /v1/insights requires At a Glance · Free

Retrieve insights

Returns a handful of sentences summarising your archive: how much it holds, what stands out in it, and which allowances are about to run out.

Response · data

{"insights": ["You have archived 51,204 messages across 38 chats.", "Your weekly exports are nearly spent."]}

Billing

Under credits, $0.005 per request. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies.

Notes

  • Insights are built on workers the bot shares with the API, and the API builds one answer at a time. A request that cannot get its turn within two seconds is answered 503 busy with a Retry-After.
GET /v1/portraits/{chat} requires Chat portraits · Free

Retrieve a portrait

Analyses a whole conversation and describes the person on the other side: the archetype they fall into, the writing traits behind it, what they write about, when they write, and which of your other conversations sound similar.

Parameters

NameInTypeRequiredDescription
chat path integer yes The chat id, as returned by GET /v1/chats.

Response · data

{
  "chat_id": -1001234567890,
  "subject": {"title": "Ann Weber", "username": "ann", "messages": 4471,
              "first": "2026-01-04T08:00:00Z", "last": "2026-09-06T08:00:00Z"},
  "built_at": "2026-09-06T08:41:00Z",
  "cached": false,
  "model": {"version": 7, "fitted_at": "2026-09-06T00:00:00Z"},
  "summary": "Writes in long, careful sentences, mostly late in the evening.",
  "archetype": {"key": "the_essayist", "label": "The Essayist", "fit": 0.81},
  "traits": [{"key": "verbosity", "name": "Verbosity", "level": "high",
              "score": 0.78, "z": 1.24}],
  "topics": ["invoice", "deadline", "draft"],
  "rhythm": {"chronotype": "night owl", "tempo": "measured", "week": "weekdays",
             "peak_hours": [21, 22], "mean_gap_seconds": 412.5, "weekend_share": 0.12},
  "activity": {"messages": 4471, "words": 88213, "unique_terms": 6104,
               "messages_per_day": 18.2, "media_share": 0.07},
  "confidence": {"level": "high", "score": 0.86}
}

Billing

Under credits, $0.05 per portrait. Under shared limits your plan covers it and nothing is charged. Under hybrid your plan covers it until its quota is used up, then the same price applies. Counts against the portrait:weekly quota of your plan.

Notes

  • A portrait that cannot be returned says why in error.reason: model_training (503 unavailable, with Retry-After — come back later), not_enough_history or empty_chat (404 not_found — the chat has to grow first), portraits_disabled (503 unavailable — waiting does not help). Nothing is charged until a portrait is returned.
  • Under shared limits and hybrid, a chat already portrayed this week can be requested again for free — the plan counts chats, not requests. Under credits every request is charged.
  • The similar-chats and style-shift sections are included depending on your plan.

Settings

GET /v1/settings/retention free

Retrieve retention settings

Returns the retention policy in force: what happens when the archive is full, how long a message is kept, and the windows ttl_seconds may be set to.

Response · data

{
  "mode": "rotate", "ttl_seconds": 2592000, "in_chat": false,
  "can_ttl": true, "can_in_chat": true,
  "ttl_choices": [0, 86400, 604800, 2592000, 7776000, 15552000, 31536000],
  "archive": {"key": "messages:stored", "label": "Archived messages", "unit": "messages",
              "limit": 1000000, "used": 51204, "remaining": 948796, "unlimited": false}
}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
PATCH /v1/settings/retention free scope settings:write

Update retention settings

Updates the retention policy. Every field is optional. mode decides what happens when the archive is full: keep refuses new messages, rotate drops the oldest to make room. ttl_seconds drops a message after the given time regardless of space; zero disables it. in_chat also deletes a message from Telegram when it leaves the archive.

Request body

{"mode": "rotate", "ttl_seconds": 2592000, "in_chat": false}

Response · data

{"mode": "rotate", "ttl_seconds": 2592000, "in_chat": false, "can_ttl": true, "can_in_chat": true, "ttl_choices": [0, 86400, 604800, 2592000, 7776000, 15552000, 31536000]}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
  • ttl_seconds and in_chat are plan features. If your plan does not include one, the request is refused rather than silently ignored.
  • ttl_seconds is one of ttl_choices — a closed set. Any other number is refused with 400 bad_request.
  • Fields sent together are applied together: a request that changes two of them changes both or neither.
GET /v1/settings/vault free

Retrieve vault settings

Returns whether a revealed vault message is removed from the chat automatically, after how long, and the windows reveal_ttl_seconds may be set to.

Response · data

{"reveal_ttl_seconds": 60, "auto_deletes": true, "can_reveal_ttl": true, "reveal_ttl_choices": [15, 30, 60, 180, 300, 600, 1800]}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
PATCH /v1/settings/vault free requires Decryption timer · Pro scope settings:write

Update vault settings

Sets how long a revealed vault message stays in the Telegram chat before the bot removes it: one of reveal_ttl_choices, or zero to go back to the default of 60 seconds.

Request body

{"reveal_ttl_seconds": 180}

Response · data

{"reveal_ttl_seconds": 180, "auto_deletes": true, "can_reveal_ttl": true, "reveal_ttl_choices": [15, 30, 60, 180, 300, 600, 1800]}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
  • reveal_ttl_seconds is required and is one of reveal_ttl_choices — a closed set. Any other number is refused with 400 bad_request.
GET /v1/settings/actions free

Retrieve Actions settings

Returns the shortcut prefix, which placeholder families your plan includes, and how many shortcuts remain.

Response · data

{"prefix": ".", "can_use": true, "can_media": true, "can_advanced": true,
 "can_exclusive": true,
 "quota": {"key": "actions:saved", "limit": 50, "used": 1, "remaining": 49, "unlimited": false}}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
PATCH /v1/settings/actions free scope settings:write

Update Actions settings

Sets the character shortcuts are typed after, so that "kiss" is triggered by ".kiss". Only a fixed set of characters is accepted.

Request body

{"prefix": "!"}

Response · data

{"prefix": "!", "can_use": true, "can_media": true, "can_advanced": true, "can_exclusive": true}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
GET /v1/settings/language free

Retrieve language settings

Returns the language you chose, the language your Telegram client reports, and which of the two is in effect.

Response · data

{"chosen": "", "detected": "ru", "effective": "ru", "supported": ["en", "ru"]}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.
PATCH /v1/settings/language free scope settings:write

Update language settings

Sets the language the bot uses. language is required; an empty string reverts to following your Telegram client. A body without it, or with null, is refused.

Request body

{"language": "en"}

Response · data

{"chosen": "en", "detected": "ru", "effective": "en", "supported": ["en", "ru"]}

Billing

Free on every billing mode.

Notes

  • Free on every billing mode.