AiTun API Reference
All REST endpoints on https://aitun.cc/aitun-api/* — subdomains, agent tokens, AiMail mailboxes & email fetch. This page is public: it works with or without authentication.
Auth: send Authorization: Bearer <TOKEN> on every call.
Three token types: aitagt_… agent token (manage subdomains / mailboxes / tokens) ·
ait_… subdomain token (starts tunnels: aitun-client -k ait_… -p 8080) ·
aitm_… mailbox token (read one mailbox's recent emails).
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 | /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. AiMail 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_ token. Limits: normal 5 · vip 10 · svip 50 · ssvip unlimited. |
| 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 tokens (self-management) agent token
Agent token self-management (scopes: token:read / token:write)
| Method | Endpoint | Description |
|---|
| GET | /aitun-api/agent-tokens/list | List your agent tokens (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). |
| DELETE | /aitun-api/agent-tokens/{id} | Revoke (cannot revoke itself). |
6. 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"}' |
| Delete mailbox | curl -s -X DELETE https://aitun.cc/aitun-api/mailbox/{MAILBOX_ID} -H "Authorization: Bearer aitagt_XXX" |
| Fetch latest 10 emails | curl -s "https://aitun.cc/aitun-api/mail/recent?n=10" -H "Authorization: Bearer aitm_XXX" |
| Read one email | curl -s https://aitun.cc/aitun-api/mail/message/{EMAIL_ID} -H "Authorization: Bearer aitm_XXX" |
| Start a tunnel | aitun -k ait_XXX -p 8080 (subdomain token, CLI — not a REST call) |