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.
| Code | Status | Meaning | Recommended action |
|---|---|---|---|
| bad_request | 400 | The request body or parameters are invalid. | Check the message: it names the offending field. |
| unauthorized | 401 | The API key is missing, malformed or unknown. | Send your key as Authorization: Bearer <key>. If it was regenerated, use the new one. |
| forbidden | 403 | The key is valid, but this request is not permitted. | The response names the required permission and the plan that includes it. |
| account_blocked | 403 | The account has been blocked. | The request cannot be retried. |
| not_found | 404 | The 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_allowed | 405 | The endpoint does not accept this method. HEAD is not accepted anywhere. | Use a method from the Allow header. |
| conflict | 409 | The resource conflicts with one that already exists. | Choose another name. |
| quota_exhausted | 429 | A plan quota has been used up. Only under shared limits. | Wait until reset_at, or switch the application to hybrid. |
| scope_required | 403 | The 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_limited | 429 | Too 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_credits | 402 | The application's balance cannot cover the request. | Fund the application from your account balance in the bot. |
| too_large | 413 | The export would be larger than 50 MB. Nothing was charged. | Narrow the export with a chat or a filter. |
| busy | 503 | Aether has no room for the request right now. Nothing was charged. | Retry after the number of seconds in Retry-After. |
| unavailable | 503 | What 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. |
| internal | 500 | Something 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.
| Operation | Per | Price | When | Plan 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:
| Modes | Requests / second | Burst | Notes |
|---|---|---|---|
| shared, hybrid | 10 | 20 | The plan's own rate limit. If you reach it, slow down and retry after the interval in Retry-After. |
| credits | 50 | 100 | Credits carry no product rate limit; this is only a safety ceiling. A well-behaved client should never reach it. |
| all applications of one account | 60 | 120 | Shared by every application of the account, whatever their modes. A safety ceiling, like the one under credits. |
| the whole API | 300 | 600 | Shared 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.
| Header | Description |
|---|---|
| X-Aether-Billing | The billing mode the request was served under: shared, credits or hybrid. |
| X-Aether-Cost | The cost of this request in credits. Zero under shared limits and for free operations. |
| X-Aether-Balance | The 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-Ops | The operations this request was billed for, comma-separated. |
| X-Aether-Quota-Reset | When the exhausted quota resets, as a Unix timestamp. Sent with quota_exhausted. |
| Retry-After | How many seconds to wait before retrying. Sent with rate_limited, busy, and unavailable when waiting helps. |
Application
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.
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| 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.
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.
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.
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
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.
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.
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.
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.
List chats
Returns one page of the chats in your archive, with the number of messages in each.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| 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.
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| 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.
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| 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.
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
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.
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.
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.
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.
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.
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 a secret by id
Deletes an entry by the entry_id returned when it was stored.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| 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
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.
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.
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.
Retrieve a shortcut
Returns a single shortcut by its id.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| 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.
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| 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 a shortcut
Deletes a shortcut. Its name becomes available again immediately.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| 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
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.
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| 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
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.
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.
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.
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.
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.
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.
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.
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.