AiTun API Reference
All REST endpoints on https://aitun.cc/aitun-api/* — subdomains, agent access keys, Agent Email mailboxes, Agent SMS phones & email/SMS fetch. This page is public: it works with or without authentication.
Auth: send Authorization: Bearer <TOKEN> on every call.
Four token types: aitagt_… agent access key (manage subdomains / mailboxes / SMS phones / tokens) ·
ait_… subdomain token (starts tunnels: aitun-client -k ait_… -p 8080) ·
aitm_… mailbox key (read one mailbox's recent emails) ·
atsms_… SMS token key (read the token's recent SMS across its auto-classified numbers).
Success returns HTTP 200 + JSON (with success:true); failures return 4xx/5xx + {"error":"..."} (401 unauthenticated · 403 missing scope · 404 not found · 409 already taken).
1. Public endpoints no auth
Public endpoints — no authentication required
| Method | Endpoint | Description |
|---|
| GET | /aitun-api/server/version | Server version + config (tier mailbox limits, retention, mail domain). |
| GET | /aitun-api/subdomain/check/{name} | Is this subdomain free? Add ?domain_base=aitun.cc for 2nd-level domains. |
| GET | /aitun-api/mailbox/check?name=xxx | Is xxx@aitun.cc available? |
| GET | /aitun-api/sms/check?phone=xxx | Validate a phone number format (digits, no country code). Numbers are not exclusive — any number can be added; pushes are authenticated by the per-phone atsms_ key. |
| GET | /downloads/aitun-tunnel-skill.md | Agent skill document (tunnel usage for AI agents). |
2. Subdomains agent token
Requires aitagt_ (scopes: subdomain:read / subdomain:create / subdomain:delete / subdomain:renew)
| Method | Endpoint | Description |
|---|
| GET | /aitun-api/subdomain/list | List all your subdomains — each row includes its ait_ token for aitun-client -k. |
| POST | /aitun-api/subdomain/register | Register one. Body: {"name":"myapp","domain_base":"t.aitun.cc"} (domain_base: t.aitun.cc default 3-level, or aitun.cc 2-level VIP). |
| POST | /aitun-api/subdomain/{id}/renew-token | Rotate the subdomain's ait_ token (old one dies instantly). |
| DELETE | /aitun-api/subdomain/{id} | Delete the subdomain and its tunnels. |
3. Agent Email mailboxes agent token
Requires aitagt_ (scopes: mailbox:read / mailbox:create / mailbox:delete / mailbox:renew)
| Method | Endpoint | Description |
|---|
| POST | /aitun-api/mailbox/register | Register {name}→name@aitun.cc. Body: {"name":"mybox"}. Response includes the mailbox's aitm_ key. Limit: 5 free + purchased extras. |
| GET | /aitun-api/mailbox/list | List all your mailboxes (each includes its aitm_ token). |
| GET | /aitun-api/mailbox/{id}/emails?limit=n | Recent n emails of one mailbox (subject + snippet), via agent token. |
| POST | /aitun-api/mailbox/{id}/token | Regenerate the mailbox's aitm_ token (old one dies instantly). |
| DELETE | /aitun-api/mailbox/{id} | Delete the mailbox and all stored emails. |
4. Email fetch aitm_ token
Uses the mailbox's own aitm_ token (not the agent token)
| Method | Endpoint | Description |
|---|
| GET | /aitun-api/mail/recent?n=10 | ONE command — latest n (max 10) emails of the token's mailbox: subject, sender, snippet, id. |
| GET | /aitun-api/mail/message/{EMAIL_ID} | Full text/plain body of one email. |
Storage: text-only, rolling latest 10 per mailbox, attachments auto-stripped — built for verification-code (OTP) workflows.
5. Agent SMS tokens (receive-code) agent token
Requires aitagt_ (scopes: sms:read / sms:create / sms:delete / sms:renew)
| Method | Endpoint | Description |
|---|
| POST | /aitun-api/sms/register | v4.16 Create a NEW bare token — body is optional (an empty JSON object is fine; a legacy {"phone":"..."} is attached as number #1). Response includes the atsms_ key. Limit: 5 free + purchased extras ($1/token). |
| GET | /aitun-api/sms/list | List your SMS tokens (each with its atsms_ key, nested phones[] — max 2, auto-classified — and stored-message counts). Legacy flat phones[] still returned. |
| GET | /aitun-api/sms/{id}/messages?limit=n&phone_id=x | Recent n SMS of one token across its numbers (optionally filtered to one number), each message tagged with phone_id. |
| POST | /aitun-api/sms/{id}/token | Regenerate the token's atsms_ key (old one dies instantly — update the aitunSMS app!). |
| DELETE | /aitun-api/sms/{id} | Delete the token, its numbers and all stored SMS. |
The phone runs the open-source aitunSMS Android app: it pushes received SMS to aitun.cc; numbers are auto-classified from the pushes (dual-SIM = 2 numbers per token, single SIM = 1; a THIRD number is rejected with {"use_new_token":true}). Rolling latest 10 SMS per number — built for verification-code (OTP) workflows.
6. SMS fetch atsms_ token
Uses the token's atsms_ key (not the agent token)
| Method | Endpoint | Description |
|---|
| GET | /aitun-api/sms/recent?n=20 | ONE command — latest n (max 20 = dual-SIM 2 numbers × rolling 10) SMS across the token's numbers: sender, snippet, received_at, id, phone_id, phone (the SIM number the message arrived on); response also carries phones[] and token_full. |
| GET | /aitun-api/sms/message/{SMS_ID} | Full text body of one SMS (response includes the phone number it arrived on). |
| POST | /aitun-api/sms/push | APK ingest — push received SMS. Body: {"phone":"","messages":[{"phone":"135...","sender":"...","body":"...","received_at":"RFC3339"}]}. Each message's phone (falls back to top-level phone) is auto-classified by last-7 match; unknown numbers auto-register while the token has room; a 3rd number → 403 {"use_new_token":true,"token_full":true}. |
7. Agent access keys (self-management) agent token
Agent access key self-management (scopes: token:read / token:write)
| Method | Endpoint | Description |
|---|
| GET | /aitun-api/agent-tokens/list | List your agent access keys (excludes self; values hidden). |
| POST | /aitun-api/agent-tokens/create | Create one. Body: {"name":"my-zagent"} — omit scopes for full access, or pass an explicit comma-separated list (subdomain:read/create/delete/renew, token:read/write, mailbox:read/create/delete/renew, sms:read/create/delete/renew). |
| PUT | /aitun-api/agent-tokens/{id} | Update name / scopes / expiry. |
| DELETE | /aitun-api/agent-tokens/{id} | Revoke (cannot revoke itself). |
8. Quick start copy & paste
| Task | Command |
|---|
| List subdomains | curl -s https://aitun.cc/aitun-api/subdomain/list -H "Authorization: Bearer aitagt_XXX" |
| Register mailbox | curl -s -X POST https://aitun.cc/aitun-api/mailbox/register -H "Authorization: Bearer aitagt_XXX" -H "Content-Type: application/json" -d '{"name":"mybox"}' |
| Fetch latest 10 emails | curl -s "https://aitun.cc/aitun-api/mail/recent?n=10" -H "Authorization: Bearer aitm_XXX" |
| Create an SMS token | curl -s -X POST https://aitun.cc/aitun-api/sms/register -H "Authorization: Bearer aitagt_XXX" -H "Content-Type: application/json" -d '{}' |
| Fetch latest 20 SMS | curl -s "https://aitun.cc/aitun-api/sms/recent?n=20" -H "Authorization: Bearer atsms_XXX" |
| Read one SMS | curl -s https://aitun.cc/aitun-api/sms/message/{SMS_ID} -H "Authorization: Bearer atsms_XXX" |
| Start a tunnel | aitun -k ait_XXX -p 8080 (subdomain token, CLI — not a REST call) |