REST API

Base URL: https://api.fones.ai/v1 (also /v1 on fones.ai). JSON in, JSON out. The machine-readable version is /openapi.json.

Conventions

• Auth. Authorization: Bearer fones_.... Each phone route needs one scope: phones:read, phones:control or phones:buy. The console’s session cookie can do everything.
• Errors. Any non-2xx answer has the body { "error": { "code": "...", "message": "..." } }, sometimes with more fields (missing_cents on a 402). See Errors.
• Lists return { "data": [...], "next_before": "..." }, newest first. Pass ?limit= (1 to 100, default 50) and ?before=<next_before> for the next page; next_before is null on the last one.
• Idempotency. Routes that buy accept an Idempotency-Key header (up to 200 printable characters, kept 30 days). The same key returns the same phone again and never charges twice, also for retries sent at the same time; the same key with another request (another body, route or phone) is a 409 idempotency_conflict.
• Coordinates are a grid from 0 to 1000 on both axes, whatever the phone’s resolution.
• Money is in US cents (balance_cents, monthly_cents). Times are ISO 8601 in UTC.

Routes

“any” routes take any key or the session. “console” routes take the signed-in console session only (403 session_required with a key), so a leaked key can neither mint keys nor move your webhook. Writes with the session must come from the console’s own origin.

Catalog

Each add-on includes available. Unconfigured numbers and static IPs are refused before charging, both with a new phone and when added later. Phones alone remain available.

GET /v1/catalog

{
  "tiers": [
    { "id": "cloud", "name": "Cloud phone", "monthly_cents": 1900 },
    { "id": "identity", "name": "Real phone identity", "monthly_cents": 4900 }
  ],
  "models": [
    { "id": "android13", "name": "Cloud phone, Android 13", "tier": "cloud" },
    { "id": "s24fe", "name": "Samsung Galaxy S24 FE", "tier": "identity" },
    { "id": "pixel6", "name": "Google Pixel 6", "tier": "identity" }
  ],
  "addons": [
    { "id": "number", "name": "Number", "monthly_cents": 900, "available": false },
    { "id": "proxy", "name": "Static IP", "monthly_cents": 600, "available": false }
  ],
  "balance_cents": 5000
}

Phones

The phone object

{
  "id": "ph_7k2m9q",
  "label": "signup-bot",
  "tier": "identity",
  "model": "pixel6",
  "status": "ready",
  "online": true,
  "number": "+15555550134",
  "number_status": "ready",
  "ip": "203.0.113.24",
  "proxy_status": "ready",
  "auto_renew": true,
  "monthly_cents": 6400,
  "paid_until": "2026-11-22T10:24:00Z",
  "created_at": "2026-10-22T10:20:11Z",
  "ready_at": "2026-10-22T10:24:00Z",
  "ended_at": null,
  "error": null
}

status is provisioning, ready, failed or ended. online says whether the phone is running (as of the last few minutes). number_status and proxy_status are provisioning while a number or static IP you paid for is being set up, ready once number or ip shows it, and null without one. monthly_cents is what the next renewal costs: the phone and its ready add-ons (0 once it ended or failed). paid_until is the end of the current period, the same for the phone and its add-ons; null for a failed (refunded) setup.

Buy a phone

POST /v1/phones with an Idempotency-Key header.

The first month of the phone and the add-ons you asked for comes from the balance at once, in one charge, all or nothing. Answers 202 with the phone, status provisioning; about 15 to 30 minutes later phone.ready (with number.ready and proxy.ready for what came with it). If the setup fails for good, the phone is failed, the whole charge is refunded and you get phone.failed. An add-on bought with the phone that cannot be set up never fails the phone: the phone becomes ready without it, and that add-on alone is taken off and refunded (number.failed, proxy.failed). 402 insufficient_balance (with missing_cents) when the balance is short; nothing is charged.

Change or end a phone

PATCH /v1/phones/:id with { "label": "...", "auto_renew": false } (label: null clears it). Renewal goes on or off for the phone and its add-ons together.

A phone and its add-ons renew in one charge at paid_until. If the balance is short then, they all keep working for 3 days of grace (renewal is tried again hourly), then end together; nothing is charged for a part of them.

DELETE /v1/phones/:id turns renewal off: the phone runs until paid_until, then ends with its add-ons. DELETE /v1/phones/:id?now=true releases it at once, with no refund; the phone is wiped before anyone else gets it. Both answer the phone. A phone still provisioning (never ready) is cancelled at once by either one: it ends and everything it was charged comes back (phone.ended, reason released). Whenever a phone ends, a number or static IP still being set up then is refunded, as when it is removed before it worked.

Screen and actions

Look

GET /v1/phones/:id/screenshot returns the image (image/png or image/jpeg). With ?format=json: { "type": "image/png", "data": "<base64>", "width": 1080, "height": 2400 }.

GET /v1/phones/:id/ui returns the nodes on screen (empty nodes nothing can tap are left out). x, y is a node’s center and bounds its box as [left, top, right, bottom], all on the grid:

{
  "nodes": [
    { "text": "Phone number", "description": null, "id": "com.example.market:id/phone", "class": "android.widget.EditText", "clickable": true, "x": 500, "y": 418, "bounds": [56, 395, 944, 441] },
    { "text": "Send code", "description": null, "id": "com.example.market:id/send", "class": "android.widget.Button", "clickable": true, "x": 500, "y": 560, "bounds": [56, 538, 944, 582] }
  ]
}

The grid is worked out from the screen size the phone has at that moment, so it stays right after a wm size from the shell.

Act

POST /v1/phones/:id/actions with one action:

{ "type": "swipe", "x1": 500, "y1": 800, "x2": 500, "y2": 200 }

Answers { "ok": true }, or { "ok": true, "output": "..." } for shell. 409 phone_not_ready while the phone is provisioning, failed or ended; 502 phone_error when the phone did not answer (retry), or did not confirm (look before retrying).

Number and texts

POST /v1/phones/:id/number adds a US mobile number to a ready phone ($9 a month; Idempotency-Key accepted). It is charged now for what is left of the phone’s current period (half a period left: half the price). Once it is ready it is part of the phone’s renewal price; if the phone renews while it is still being set up, it is charged for the rest of the new period when it becomes ready (and taken off and refunded if that cannot be paid). It answers 202 with the phone, number_status provisioning, then ready with number.ready.

• 402 insufficient_balance (with missing_cents) when the balance does not cover the rest of the period; nothing is charged.
• 503 no_capacity when no number can be had right now: the charge is refunded at once. A number that fails later is refunded too, with number.failed.
• 409 conflict when the phone has one (or one is being added or taken off right now); 409 phone_not_ready while the phone is being set up (buy it with number: true instead); 409 phone_unpaid while the phone’s period is unpaid (in grace after a short renewal): top up, and once it renews add the number.
• A number that fails, or that you remove before it is ready, gets back everything it was charged.

DELETE /v1/phones/:id/number takes it off at once and the next renewal is cheaper (number.removed); no refund once it worked. 409 phone_not_ready while the phone is being set up.

GET /v1/phones/:id/sms lists texts, newest first, each with number, the number that received it. ?since=<ISO time> for the ones from then on. Texts arrive within about a minute.

{
  "data": [
    { "id": "sms_5q2r8t", "number": "+15555550134", "from": "+15555550188", "text": "Your Market code is 482913. Do not share it.", "code": "482913", "received_at": "2026-10-22T10:24:31Z" }
  ],
  "next_before": null
}

Static IP

POST /v1/phones/:id/proxy gives a ready phone a fixed US residential IP ($6 a month; Idempotency-Key accepted), charged and renewed like a number. It answers 202 with proxy_status provisioning; once the phone routes through it (a minute or two) ip shows it and you get proxy.ready. 503 no_capacity when none is free: refunded at once. If routing fails for good you get proxy.failed and the refund. The same 402 and 409 answers as for a number. DELETE /v1/phones/:id/proxy takes it off at once (proxy.removed); no refund once it worked, everything back before.

Apps

GET /v1/apps lists the catalog: { "data": [{ "id": "...", "name": "...", "package": "..." }] }.

POST /v1/phones/:id/apps with { "app": "<id>" } installs one on the phone and answers { "ok": true } (it can take a minute). Then open_app with its package.

Activity

GET /v1/activity lists every action sent to your phones in the last 30 days, newest first: { "id", "phone_id", "actor", "action", "detail", "ok", "error", "ms", "at" }. actor is the API key id, or console. detail is short (500,418, home, 12 characters): typed text and shell commands are never kept, only their length. error is the error code of a failed action, ms how long the phone took. Filter with ?phone_id= and ?ok=false (only failed actions) or ?ok=true.

Account, keys, webhook, billing

• GET /v1/account: { "id", "email", "balance_cents", "monthly_cents", "webhook_url", "created_at" }; monthly_cents is what renews every 30 days.
• GET /v1/api-keys lists keys (never the secret): { "id", "name", "scopes", "last4", "created_at", "last_used_at" }. POST /v1/api-keys with { "name"?, "scopes"? } answers 201 with the same fields plus key: the key is shown this once. Up to 10 keys. DELETE /v1/api-keys/:id revokes one.
• PUT /v1/webhook with { "url" } (https, public) sets the endpoint. It answers { "url", "secret_last4" }, plus secret the first time: the signing secret (whsec_...) is shown this once. Changing the URL keeps the secret. GET /v1/webhook answers { "url", "secret_last4" }, never the secret. DELETE removes the URL. POST /v1/webhook/rotate-secret makes a new secret and answers { "url", "secret", "secret_last4", "previous_secret_until" }: until then deliveries are signed with both. POST /v1/webhook/test sends a webhook.test event and answers { "id", "delivered", "status_code", "error" }. See Webhooks.
• POST /v1/billing/topup with { "amount_usd": 50 } (whole dollars, from $10) returns { "url" }, a checkout page.
• GET /v1/billing/subscriptions lists what renews: one subscription per phone, whose price is the phone and its add-ons: { "id", "kind": "phone", "ref": "<phone id>", "price_cents", "status", "auto_renew", "paid_until", "renews_at", "created_at" }. status is active (also with renewal off: auto_renew is then false, and it ends at paid_until), grace (unpaid, still running) or, for the moment it takes to end, ending.
• GET /v1/billing/ledger lists every charge and credit: { "id", "amount_cents", "kind", "ref", "created_at" }. kind is topup, phone (what phones and add-ons cost), refund or adjustment. For phone and refund, ref starts with the phone id, then @:

ref.split("@")[0] is the phone id.

Errors