# Phonebase

> The mobile execution layer for AI agents.

- [Phonebase docs](https://docs.phoneuse.com/index.md): The mobile execution layer for AI agents.
- [Quickstart](https://docs.phoneuse.com/quickstart.md): Get a key, connect an MCP client, and drive a real phone in about ten minutes.
- [The console](https://docs.phoneuse.com/getting-started/console.md): The browser face of the control plane: which screens exist, what each one does, and what has no screen at all.
- [MCP config](https://docs.phoneuse.com/getting-started/mcp-config.md): The exact config block for each transport, and what changes between them.
- [First session](https://docs.phoneuse.com/getting-started/first-session.md): Acquire a device, observe it, act on it, release it, one call at a time.
- [Reading a trace](https://docs.phoneuse.com/getting-started/trace.md): What the control plane hands back, and how to confirm an action later.
- [For agents](https://docs.phoneuse.com/getting-started/for-agents.md): Machine readable entry points, and which MCP server is which.
- [Buy, drive and return a device](https://docs.phoneuse.com/guides/first-device.md): The whole loop, end to end, in the console and over the API, with the readings from a real run.
- [Webhooks](https://docs.phoneuse.com/guides/webhooks.md): Be told when a run ends, when it needs a person, when a schedule fires, and when an order changes.
- [Install apps from the App Store](https://docs.phoneuse.com/guides/upload-app-package.md): Choose an approved app for your phone and follow its installation result.
- [MCP surface](https://docs.phoneuse.com/mcp/overview.md): The tool surface an agent drives, and the contract that keeps it stable.
- [Tool reference](https://docs.phoneuse.com/mcp/reference.md): Every tool on the MCP surface, with its scope, annotations and fields.
- [Errors](https://docs.phoneuse.com/mcp/errors.md): The error envelope a failed tool call carries, and every code it can name.
- [Transports](https://docs.phoneuse.com/mcp/transports.md): stdio and HTTP publish the same tools. Here is what actually differs.
- [Authentication](https://docs.phoneuse.com/mcp/auth.md): Two credential channels, eight scopes, one authorization context.
- [Progress and takeover](https://docs.phoneuse.com/mcp/progress-and-takeover.md): Long running actions, and the moments a person has to step in.
- [Chat with the copilot](https://docs.phoneuse.com/copilot/chat.md): The chat protocol behind the console's copilot: threads on the server, a streamed UI message protocol, approvals that ride the stream, and the limits a turn runs under.
- [Device tiers](https://docs.phoneuse.com/devices/tiers.md): How input reaches a device, and what that costs you in fidelity.
- [Capabilities](https://docs.phoneuse.com/devices/capabilities.md): What a given device can and cannot do, declared rather than discovered.
- [Agent tier](https://docs.phoneuse.com/agent/overview.md): Hand a goal to phonebase or to your own worker instead of driving each step yourself.
- [Bring your own worker](https://docs.phoneuse.com/agent/worker.md): You supply the worker that executes a run. Here is what it has to do and how to get one running.
- [Runs](https://docs.phoneuse.com/agent/runs.md): The lifecycle of one autonomous run, and who is allowed to move it.
- [CLI](https://docs.phoneuse.com/cli/overview.md): An operator client over the same control plane, with no behaviour of its own.
- [Installation](https://docs.phoneuse.com/cli/installation.md): Install the CLI from npm, or run it from a checkout.
- [Commands](https://docs.phoneuse.com/cli/commands.md): Every CLI command, its arguments and its options.
- [CLI in CI](https://docs.phoneuse.com/cli/ci-cd.md): How to run the CLI in your own pipeline, and what ours does with it today.
- [Zero software footprint](https://docs.phoneuse.com/security/zero-software-footprint.md): What the physical tier claims about a device under test, and what it does not.
- [Org isolation](https://docs.phoneuse.com/security/org-isolation.md): Where the boundary between orgs runs, and what enforces it.
- [Frame retention](https://docs.phoneuse.com/security/frame-retention.md): How long captured screen frames are kept, and who can read them.
- [A leaked credential](https://docs.phoneuse.com/security/leaked-credentials.md): What to do first when a key or a run token has been exposed.
- [Acceptable use](https://docs.phoneuse.com/security/acceptable-use.md): What you may not do with a phone you drive through PhoneBase, and what we do about it.
- [Metering units](https://docs.phoneuse.com/billing/units.md): What the control plane counts, and what it deliberately does not.
- [Billing modes](https://docs.phoneuse.com/billing/modes.md): The two ways a device is billed, the current rates, and how to choose between them.
- [Spending controls](https://docs.phoneuse.com/billing/spending-controls.md): What bounds your bill today, including the control that does not exist.
- [Changelog](https://docs.phoneuse.com/changelog.md): What changed on the surfaces you install or call, and how to find out when a shape moves.
- [API overview](https://docs.phoneuse.com/api/index.md): Two HTTP surfaces, and where the boundary between them runs.
- [Versioning and compatibility](https://docs.phoneuse.com/api/versioning.md): What the /v1 path does and does not promise, and the one mechanism that tells you when a shape you parse moves.
- [Rate limits](https://docs.phoneuse.com/api/rate-limits.md): Three budgets, one refusal shape, and the headers that tell you where you stand.
- [Check that the service is up](https://docs.phoneuse.com/api/endpoints/health/check-that-the-service-is-up.md): An unauthenticated liveness probe. `status` is the one word to branch on: `ok`, `degraded` when a background loop has stopped moving, or `incident` when an operator has declared one. A declared incident also carries `incident.title` and `incident.url`.
- [Check the run's device channel](https://docs.phoneuse.com/api/endpoints/device-surface/check-the-runs-device-channel.md): Confirms the run is live and its channel is serving.
- [List the run's device](https://docs.phoneuse.com/api/endpoints/device-surface/list-the-runs-device.md): Returns exactly one device: the one this run is bound to. A run token is never a fleet listing, and it cannot be walked sideways onto another device.
- [Fetch a frame](https://docs.phoneuse.com/api/endpoints/device-surface/fetch-a-frame.md): Returns raw image bytes, not JSON and not base64.
- [Report the run's outcome](https://docs.phoneuse.com/api/endpoints/device-surface/report-the-runs-outcome.md): How a worker says it is done. It lives on this surface rather than on the run surface because a worker holds exactly one credential, its run token, and should never need an org credential to close its own work. The token also pins WHICH run is being reported, so a worker cannot close somebody else's…
- [Act on the device](https://docs.phoneuse.com/api/endpoints/device-surface/act-on-the-device.md): Look before you touch: an action is refused until this run has fetched at least one frame, because coordinates with no frame behind them have no meaning.
- [Why there is no event stream](https://docs.phoneuse.com/api/endpoints/mcp/why-there-is-no-event-stream.md): There is no event stream to resume, so this method is refused. The refusal is documented rather than omitted, because a client that expects a stream should learn why it will not get one.
- [Send a JSON-RPC request](https://docs.phoneuse.com/api/endpoints/mcp/send-a-json-rpc-request.md): The Model Context Protocol endpoint. It speaks JSON-RPC over one request and one response, so it is a single operation here rather than one per tool: a document that flattened the tools into endpoints would describe a protocol the service does not speak, and a client written against it would fail on…
- [Why there is no session to end](https://docs.phoneuse.com/api/endpoints/mcp/why-there-is-no-session-to-end.md): There is no session to terminate, so this method is refused. The refusal is documented rather than omitted, for the same reason the event stream is: a client that closes its sessions should be able to see that there is nothing here to close.
- [Discover visible devices and authoritative application scopes](https://docs.phoneuse.com/api/endpoints/apps/discover-visible-devices-and-authoritative-application-scopes.md): Read-only adapter capability projection. No inventory collection, wake, boot, lease acquisition/renewal or device action. Return independent supported/unsupported/unknown for inventoryRead/install/update/uninstall and authoritative scope or null; updatedAt is capability knowledge time only. Invisibl…
- [Read last confirmed phone apps](https://docs.phoneuse.com/api/endpoints/apps/read-last-confirmed-phone-apps.md): Read cached authoritative facts only, no device calls/lease effects. Missing target rows are unknown, not absent. Listings filter to currently visible devices. Last refresh errors never erase last confirmed facts.
- [Request bounded read-only application checks](https://docs.phoneuse.com/api/endpoints/apps/request-bounded-read-only-application-checks.md): All IDs authorized before admission; invisible/cross-org target ->404. Per-target transport/offline failures recorded after acceptance. Coalesce identical concurrent reads and apply refresh policy; do not wake, acquire, renew or run an install as a probe.
- [Read application-check progress](https://docs.phoneuse.com/api/endpoints/apps/read-application-check-progress.md)
- [Read per-device check outcomes](https://docs.phoneuse.com/api/endpoints/apps/read-per-device-check-outcomes.md)
- [Recover a lost mutation response by original key](https://docs.phoneuse.com/api/endpoints/apps/recover-a-lost-mutation-response-by-original-key.md): Original org/principal and original operation scopes revalidated (not just apps:read). Never returns another actor request even within org. Found request points to original stable resource. 404 is not proof that an action never happened: key may be absent, hidden or expired. Never create a replaceme…
- [List installable apps](https://docs.phoneuse.com/api/endpoints/apps/list-installable-apps.md): Managed Android app store. Requires apps:read, devices:read. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Ins…
- [Read installation history](https://docs.phoneuse.com/api/endpoints/apps/read-installation-history.md): Managed Android app store. Requires apps:read, devices:read. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Ins…
- [Install an app](https://docs.phoneuse.com/api/endpoints/apps/install-an-app.md): Managed Android app store. Requires apps:read, devices:read, devices:act, devices:lease. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run;…
- [Recover an app installation](https://docs.phoneuse.com/api/endpoints/apps/recover-an-app-installation.md): Managed Android app store. Requires apps:read, devices:read. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Ins…
- [Check an app installation](https://docs.phoneuse.com/api/endpoints/apps/check-an-app-installation.md): Managed Android app store. Requires apps:read, devices:read. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Ins…
- [Get a short-lived URL for one archived frame](https://docs.phoneuse.com/api/endpoints/runs/get-a-short-lived-url-for-one-archived-frame.md): Returns a presigned URL that renders one frame, good for about a minute. Fetch this with your credential, then use the `url` it returns as the image source: this route needs a bearer token and an `img` element cannot send one.
- [List your runs](https://docs.phoneuse.com/api/endpoints/runs/list-your-runs.md): Your organisation's runs, newest first. Each entry carries the goal the run was started with and how it ended, so a run is still readable long after it finished and a lost runId is recoverable. Page with the `nextBefore` cursor a full page hands back; when it is absent you have reached the end.
- [Start a run on a device](https://docs.phoneuse.com/api/endpoints/runs/start-a-run-on-a-device.md): Hand one device your organisation holds to a run with a goal and a budget. Your organisation must already hold it: starting a run is permission to let a loop act for you, not permission to take the device, and this route is the one place that difference is visible (a gesture DOES take).
- [Read a run, optionally waiting for it to move](https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move.md): Returns the run as it is now. With `waitMs` it waits for the state to leave `sinceState` and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel.
- [Put a run on hold](https://docs.phoneuse.com/api/endpoints/runs/put-a-run-on-hold.md): Suspends the agent. The run moves to `paused`, the worker's channels are shut until Resume (it is served no frames and its actions are refused), its deadline FREEZES, and the run's lease slides to a fresh ten minute window so the hold has one. The worker's steps are untouched: resuming carries on fr…
- [Lift a stop and let the run carry on](https://docs.phoneuse.com/api/endpoints/runs/lift-a-stop-and-let-the-run-carry-on.md): Lifts either kind of stop, and only a person can lift either.
- [Cancel a run](https://docs.phoneuse.com/api/endpoints/runs/cancel-a-run.md): Ends the run. An action already in flight when you cancel is refused before it reaches the device, so cancelling stops the arm rather than merely marking a record. Terminal is terminal: cancelling a finished run leaves it as it was.
- [Discover where to authenticate](https://docs.phoneuse.com/api/endpoints/discovery/discover-where-to-authenticate.md): RFC 9728 protected resource metadata. The control plane is a resource server only: it issues no tokens and runs no authorization endpoints, and this document names the authorization server that does.
- [Discover where to authenticate, at the endpoint suffixed path](https://docs.phoneuse.com/api/endpoints/discovery/discover-where-to-authenticate-at-the-endpoint-suffixed-path.md): The same document as the unsuffixed path, byte for byte. Both exist because clients try both, and the bearer challenge points at this one.
- [List the org's keys](https://docs.phoneuse.com/api/endpoints/api-keys/list-the-orgs-keys.md): Your org's keys, newest first, one page at a time. Secrets are not stored in recoverable form and are never in this response. `lastUsedAt` is written off the request path, so it can lag slightly behind the last real use, which is worth knowing before you read a quiet key as unused.
- [Mint an API key](https://docs.phoneuse.com/api/endpoints/api-keys/mint-an-api-key.md): Creates a headless credential for your org. ANY signed-in member of the org can mint one, whatever their role: this is the product's only headless credential, and the first step of getting started asks for it.
- [Describe the calling key](https://docs.phoneuse.com/api/endpoints/api-keys/describe-the-calling-key.md): The API key making this request, about itself: its id, name, organisation, scopes and expiry. This is what `phonebase whoami` shows. Only an API key may call it; a signed-in person has no current key and is refused 403. It never returns the secret.
- [Revoke the calling key](https://docs.phoneuse.com/api/endpoints/api-keys/revoke-the-calling-key.md): The API key making this request revokes ITSELF, effective on the very next request. This is what `phonebase logout` calls. It can reach no other key, so it is not key management, and like every revocation it asks for no fresh sign-in. A signed-in person is refused 403 and revokes keys by id instead.
- [Revoke a key](https://docs.phoneuse.com/api/endpoints/api-keys/revoke-a-key.md): Revocation takes effect on the very next request: the endpoint keeps no session and holds no long lived connection, so there is nothing in flight to outlive it.
- [Rename, renew or narrow a key](https://docs.phoneuse.com/api/endpoints/api-keys/rename-renew-or-narrow-a-key.md): Updates an active key in place. Reach can only SHRINK: `scopes` must be a subset of what the key already holds, and `deviceIds` must stay inside the key's current set (a key on the whole org can be narrowed to any devices the org owns, but there is no way back from a set to the whole org). Widening…
- [Rotate a key](https://docs.phoneuse.com/api/endpoints/api-keys/rotate-a-key.md): Mints a successor key with the same name, scopes and device subset (fresh lifetime, fresh secret) and shortens the old key's expiry to the grace deadline, atomically. The successor's token appears ONCE, in this response, exactly like creation.
- [Start a CLI sign-in](https://docs.phoneuse.com/api/endpoints/api-keys/start-a-cli-sign-in.md): What `phonebase login` calls first. Takes no credential. Returns a short code to show the person, the console page to approve it on, and a poll token. A signed-in person opens the page (any device will do), checks the code and approves; the CLI then collects an ordinary API key with `POST /v1/cli-se…
- [Poll a CLI sign-in, and collect its key](https://docs.phoneuse.com/api/endpoints/api-keys/poll-a-cli-sign-in-and-collect-its-key.md): Poll every `intervalMs` with the poll token from `POST /v1/cli-sessions`. While nobody has answered, the status is `pending`. Once a person approves, the NEXT poll mints the key and returns it with `status: approved`, and every poll after that answers `consumed`. The key is delivered exactly once: i…
- [Look at a CLI sign-in before approving it](https://docs.phoneuse.com/api/endpoints/api-keys/look-at-a-cli-sign-in-before-approving-it.md): What the approval page shows: the name and version the CLI reported (unverified, so compare them with the terminal in front of you), when it started and whether it is still waiting. Any signed-in person may read it; an API key is refused.
- [Approve a CLI sign-in](https://docs.phoneuse.com/api/endpoints/api-keys/approve-a-cli-sign-in.md): Approving a sign-in mints an API key for it, so it asks exactly what `POST /v1/api-keys` asks: a signed-in person of either role, and no scope your own session does not hold. No recent identity check. The key acts for the organisation you have active, is created by you, and appears on the Keys page…
- [Deny a CLI sign-in](https://docs.phoneuse.com/api/endpoints/api-keys/deny-a-cli-sign-in.md): Ends a waiting sign-in so its code can never be approved; the CLI's next poll says `denied`. Use it on a code you did not start. Any signed-in person may deny; an API key is refused.
- [Console behavior events](https://docs.phoneuse.com/api/endpoints/usage/console-behavior-events.md): Contract version 2. Send a client-generated batch UUID with immutable request contents on retries. Within your organization and signed-in person, the first successful response is replayed for 24 hours without writing more events or extending the window. After expiration, the UUID can identify a new…
- [List your org's receipts](https://docs.phoneuse.com/api/endpoints/usage/list-your-orgs-receipts.md): Every action your org has taken, newest first. This is the enumeration counterpart to the `get_receipt` tool: use that one to recover a lost response, and this one to answer what has happened.
- [Read one receipt](https://docs.phoneuse.com/api/endpoints/usage/read-one-receipt.md): One recorded action, addressed by the `idempotencyKey` you sent with it. This is the permanent URL for a receipt: the listing answers what has happened, and this answers what happened in one case, without paging to find it again.
- [Mark a receipt reviewed](https://docs.phoneuse.com/api/endpoints/usage/mark-a-receipt-reviewed.md): Records that a person opened this receipt, and who. This is what makes a needs review queue possible: `requiresManualReview` says an action's physical effect is unknown, and until now nothing said whether anybody came to look.
- [Read your org's usage this period](https://docs.phoneuse.com/api/endpoints/usage/read-your-orgs-usage-this-period.md): Settled usage for the current billing period, per device, derived from the same per-lease rows billing reads. Built for a headless integrator: the hosted product shows this in a browser, and this endpoint is how you read it without one.
- [Take a device from the shared pool](https://docs.phoneuse.com/api/endpoints/devices/take-a-device-from-the-shared-pool.md): For pay-as-you-go access. You did not buy a phone, you bought the right to use one, so there is no device of yours to list until you take one: this is the call that gets you a device for a session.
- [List the devices you can see](https://docs.phoneuse.com/api/endpoints/devices/list-the-devices-you-can-see.md): Every device your credential can address, in any status. This is the REST counterpart of the `list_devices` tool and reads the same directory, so the two cannot disagree about what you own.
- [Read one device](https://docs.phoneuse.com/api/endpoints/devices/read-one-device.md): One device's current status and capabilities without enumerating the fleet. Every status is a valid answer here, including `offline`: this route reports state, it does not refuse devices that are not usable right now.
- [Rename a device](https://docs.phoneuse.com/api/endpoints/devices/rename-a-device.md): Sets the label you see this device by. The name is yours: nothing in the control plane reads it, and `deviceId` remains the only thing that addresses the device.
- [Look at a device's screen](https://docs.phoneuse.com/api/endpoints/devices/look-at-a-devices-screen.md): The current screen, as raw image bytes. The media type says which encoding.
- [Take a device](https://docs.phoneuse.com/api/endpoints/devices/take-a-device.md): Claim exclusive use of a device and get a lease back. Send the `leaseId` on every gesture and on the release; leases expire on their own after ten minutes, so renew if you are still working.
- [Give a device back](https://docs.phoneuse.com/api/endpoints/devices/give-a-device-back.md): Release a lease by the id the acquire returned. Releasing a device you do not hold does nothing, so a retry is safe.
- [Keep a device longer](https://docs.phoneuse.com/api/endpoints/devices/keep-a-device-longer.md): Extend a lease you already hold, so work longer than one lease can keep its device. The expiry SLIDES to ten minutes from now; it does not add ten minutes to the old one, and `leaseId` and `acquiredAt` do not change, so keep using the same id.
- [Act on a device](https://docs.phoneuse.com/api/endpoints/devices/act-on-a-device.md): One gesture per request: tap, swipe, long press, type text, press a key, open an app. Coordinates are in the normalized 0-1000 grid, so nothing has to know the device's resolution.
- [Who is driving a device](https://docs.phoneuse.com/api/endpoints/devices/who-is-driving-a-device.md): One read for the question a Control view asks after every gesture: is an agent on this device, is a colleague, and whose lease is it under.
- [Open a live video session on a device](https://docs.phoneuse.com/api/endpoints/devices/open-a-live-video-session-on-a-device.md): Mint the short-lived vendor token a browser needs to drive this device as real-time video, the interactive alternative to polling the screenshot route. Hand the whole body to the video SDK: `token` is the SDK credential, `baseUrl` is the endpoint it connects to, `padCode` is the device's vendor inst…
- [Wake a device's screen](https://docs.phoneuse.com/api/endpoints/devices/wake-a-devices-screen.md): Ask a device to wake its screen and clear its lock screen. A cloud phone that started with its screen off shows no picture until something wakes it, so a live video session opened on it would sit blank; call this to bring it up, and call it again on a reconnect if the picture has not arrived.
- [Open a live view of a device](https://docs.phoneuse.com/api/endpoints/devices/open-a-live-view-of-a-device.md): Ask how to show this device's screen live, and get everything the player needs in one answer. Every device answers with the same shape; `transport` says which entry of `connect` to use.
- [Stop a robot arm now](https://docs.phoneuse.com/api/endpoints/devices/stop-a-robot-arm-now.md): Halt the arm driving this phone: its queued gestures are dropped, the motion in progress is cancelled and the pen is lifted. It does not wait behind the gesture it interrupts, and it does not lock the device: gestures sent afterwards run as usual. Safe to repeat. It is delivered whenever the arm's c…
- [Read the server's clock](https://docs.phoneuse.com/api/endpoints/devices/read-the-servers-clock.md): The server's clock, for a player lining its timestamps up with the device's. `receivedAt` is when the request reached the handler and `sentAt` is when the answer left it, both ISO-8601 with milliseconds. With your own send and receive times that gives the usual four-timestamp offset estimate. Any cr…
- [List the devices your organisation currently holds](https://docs.phoneuse.com/api/endpoints/devices/list-the-devices-your-organisation-currently-holds.md): The leases your organisation holds right now, among the devices this credential can see. This is what answers "how many of my devices are in use"; `GET /v1/devices` answers how many exist and how many are reachable, and the two are different questions.
- [Where the media server delivers room events](https://docs.phoneuse.com/api/endpoints/devices/where-the-media-server-delivers-room-events.md): NOT AN ENDPOINT YOU CALL. The media server behind live video posts here when somebody joins or leaves a device's room and when a stream's tracks come and go. What it drives is one thing: a robot arm's live stream stops a few seconds after its last viewer leaves, instead of the 30 seconds the arm wai…
- [Ask the copilot](https://docs.phoneuse.com/api/endpoints/copilot/ask-the-copilot.md): One copilot turn, streamed. Two protocols answer on this route for one release, chosen by `Accept`.
- [Answer a copilot approval](https://docs.phoneuse.com/api/endpoints/copilot/answer-a-copilot-approval.md): Answer one `approval.request` from an open copilot stream.
- [Run one tool the person named](https://docs.phoneuse.com/api/endpoints/copilot/run-one-tool-the-person-named.md): Run ONE tool directly, as yourself, with no model involved and no tokens spent. This is what a `/screenshot` or a `/press_key home` typed in the console's composer becomes.
- [Stop the turn this thread is running](https://docs.phoneuse.com/api/endpoints/copilot/stop-the-turn-this-thread-is-running.md): Stop the copilot mid-turn. The loop stops before its next model step or tool call, and what it had written is stored like any other ending, so the thread reads as a turn that stopped rather than one that vanished.
- [Pick a cut copilot stream back up](https://docs.phoneuse.com/api/endpoints/copilot/pick-a-cut-copilot-stream-back-up.md): A phone that went to the background, a tab switched away from, a network that dropped. Reconnect here, say which message you were reading and how many of its parts you already have, and the rest arrives as the same UI message chunks the live stream sends, under the same header and ending with the sa…
- [Your copilot threads](https://docs.phoneuse.com/api/endpoints/copilot/your-copilot-threads.md): Your own conversations with the copilot, newest activity first: titles and counts, never bodies.
- [One thread, with a page of its messages](https://docs.phoneuse.com/api/endpoints/copilot/one-thread-with-a-page-of-its-messages.md): The thread and its newest messages, oldest first, as UI messages a chat client renders without translation. A tool part in state `approval-requested` on the last message is a question still waiting: answer it on POST /v1/copilot.
- [Delete a thread](https://docs.phoneuse.com/api/endpoints/copilot/delete-a-thread.md): Removes the thread from every listing and every read. There is no undo, and the id cannot be reused. Receipts for anything the copilot did in it are unaffected: they were never part of the thread.
- [Rename a thread](https://docs.phoneuse.com/api/endpoints/copilot/rename-a-thread.md): The title is the one field a person edits; everything else the conversation writes.
- [Your webhook subscriptions](https://docs.phoneuse.com/api/endpoints/webhooks/your-webhook-subscriptions.md): What your org has subscribed to, and where. Signing secrets are not here: one is returned when a subscription is created and again when it is rotated, and never after.
- [Subscribe your system to what happens here](https://docs.phoneuse.com/api/endpoints/webhooks/subscribe-your-system-to-what-happens-here.md): Creates a subscription and returns its signing secret ONCE. Store the secret where your receiver can read it: to get another you have to rotate, which stops the old one working.
- [Remove a subscription](https://docs.phoneuse.com/api/endpoints/webhooks/remove-a-subscription.md): Deletes it outright, and its delivery records with it. A delivery log for a subscription nobody can see is a log nobody can interpret, so it goes too. Disable instead if you want to keep the history.
- [Enable or disable a subscription](https://docs.phoneuse.com/api/endpoints/webhooks/enable-or-disable-a-subscription.md): A disabled subscription receives nothing. Deliveries already queued for it are not retried either: you said you did not want them, and finishing a retry schedule against a subscription somebody just turned off is the opposite of that.
- [Replace a signing secret](https://docs.phoneuse.com/api/endpoints/webhooks/replace-a-signing-secret.md): Returns a new signing secret and the old one STOPS WORKING IMMEDIATELY. There is no overlap window, so a receiver still verifying with the old secret will reject every delivery from this moment: update it before you rotate, or accept a gap.
- [Send a test delivery](https://docs.phoneuse.com/api/endpoints/webhooks/send-a-test-delivery.md): Queues one delivery on the SAME path a real event takes: same signature, same headers, same retries. It answers as soon as the delivery is queued rather than waiting for your endpoint, so read the result from the deliveries listing.
- [What was delivered, and what happened](https://docs.phoneuse.com/api/endpoints/webhooks/what-was-delivered-and-what-happened.md): Every delivery attempted for one subscription, newest first: the event, when it was tried, what your endpoint answered, how many attempts it has had, and when the next one is due.
- [List managed Proxy products](https://docs.phoneuse.com/api/endpoints/managed-proxy/list-managed-proxy-products.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Read a managed Proxy product](https://docs.phoneuse.com/api/endpoints/managed-proxy/read-a-managed-proxy-product.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Quote a managed Proxy purchase](https://docs.phoneuse.com/api/endpoints/managed-proxy/quote-a-managed-proxy-purchase.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Read the original quote](https://docs.phoneuse.com/api/endpoints/managed-proxy/read-the-original-quote.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [List your Proxy orders](https://docs.phoneuse.com/api/endpoints/managed-proxy/list-your-proxy-orders.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Reserve a quoted Proxy order](https://docs.phoneuse.com/api/endpoints/managed-proxy/reserve-a-quoted-proxy-order.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Read a Proxy order and its settlement](https://docs.phoneuse.com/api/endpoints/managed-proxy/read-a-proxy-order-and-its-settlement.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Request hosted Checkout for an order](https://docs.phoneuse.com/api/endpoints/managed-proxy/request-hosted-checkout-for-an-order.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Cancel a Proxy order](https://docs.phoneuse.com/api/endpoints/managed-proxy/cancel-a-proxy-order.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [List your managed Proxies](https://docs.phoneuse.com/api/endpoints/managed-proxy/list-your-managed-proxies.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Read a managed Proxy](https://docs.phoneuse.com/api/endpoints/managed-proxy/read-a-managed-proxy.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Rename a managed Proxy](https://docs.phoneuse.com/api/endpoints/managed-proxy/rename-a-managed-proxy.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Archive an expired detached Proxy](https://docs.phoneuse.com/api/endpoints/managed-proxy/archive-an-expired-detached-proxy.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [List your Proxy network operations](https://docs.phoneuse.com/api/endpoints/managed-proxy/list-your-proxy-network-operations.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Bind, unbind, transfer or replace a Proxy](https://docs.phoneuse.com/api/endpoints/managed-proxy/bind-unbind-transfer-or-replace-a-proxy.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Read a Proxy operation](https://docs.phoneuse.com/api/endpoints/managed-proxy/read-a-proxy-operation.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Read a device's confirmed Proxy relationship](https://docs.phoneuse.com/api/endpoints/managed-proxy/read-a-devices-confirmed-proxy-relationship.md): Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require curren…
- [Check whether your organisation is provisioned](https://docs.phoneuse.com/api/endpoints/provisioning/check-whether-your-organisation-is-provisioned.md): Your own organisation's provisioning state, and when it last changed. The console renders one screen per `status`, so this is the read that decides which one a signed-in user sees.
- [What your organisation has bought, and where each purchase got to](https://docs.phoneuse.com/api/endpoints/provisioning/what-your-organisation-has-bought-and-where-each-purchase-got-to.md): Your own organisation's device purchases, newest first. This is the read that lets a paid customer with no device yet be shown something other than an empty screen.
- [Every time the date on an order moved, and why](https://docs.phoneuse.com/api/endpoints/provisioning/every-time-the-date-on-an-order-moved-and-why.md): When a purchase settles against an empty shelf it comes back as `awaiting_provisioning` with a date, and that date is an ESTIMATE rather than a promise precisely because we may move it. This is the record of every time we did, newest first, with who did it and why.
- [Cancel an order that has not arrived, and get all of it back](https://docs.phoneuse.com/api/endpoints/provisioning/cancel-an-order-that-has-not-arrived-and-get-all-of-it-back.md): Ends an order that is still `awaiting_provisioning` and refunds the whole payment.
- [Give a device back and stop the meter](https://docs.phoneuse.com/api/endpoints/provisioning/give-a-device-back-and-stop-the-meter.md): Ends a `provisioned` order. The device goes back, your ownership of it goes, and billing for it stops.
- [Stop future Cloud phone renewal at Stripe's current period end](https://docs.phoneuse.com/api/endpoints/provisioning/stop-future-cloud-phone-renewal-at-stripes-current-period-end.md): An org admin can disable a monthly Cloud phone's next Stripe charge without returning the phone or refunding the current payment. The server verifies the exact account, Customer, subscription, Price, latest verified paid invoice and current billing period, then schedules `cancel_at_period_end=true`…
- [Read a Cloud phone's current monthly renewal state](https://docs.phoneuse.com/api/endpoints/provisioning/read-a-cloud-phones-current-monthly-renewal-state.md): For a paid monthly Cloud phone, read the current Stripe subscription and latest verified paid invoice. The response says whether another monthly charge is scheduled and when the current verified paid period ends. When a draft or open invoice needs review, `invoiceReview=true` and `paidThrough` can b…
- [How much copilot you have, and how much is gone](https://docs.phoneuse.com/api/endpoints/provisioning/how-much-copilot-you-have-and-how-much-is-gone.md): Your organisation's monthly copilot allowance, what has been spent against it this period, and whether it is gone.
- [What you owe next](https://docs.phoneuse.com/api/endpoints/provisioning/what-you-owe-next.md): The next bill: when it lands, what it comes to, and how many lines it has.
- [Open the billing portal](https://docs.phoneuse.com/api/endpoints/provisioning/open-the-billing-portal.md): Returns a link into the payment provider's hosted billing page for your organisation. Changing the card, reading invoices and downloading receipts all happen there; this service draws none of them itself.
- [List what can be bought and what it costs](https://docs.phoneuse.com/api/endpoints/provisioning/list-what-can-be-bought-and-what-it-costs.md): The price list, one entry per pair of sku and billing mode, so that a caller drawing a purchase screen has a number to show before the customer commits. Prices are PRE TAX and come from the payment provider's own price objects; this service reports them and never computes one.
- [Start provisioning this organisation](https://docs.phoneuse.com/api/endpoints/provisioning/start-provisioning-this-organisation.md): Begins a purchase and returns somewhere to send the browser.
- [Where the payment provider delivers](https://docs.phoneuse.com/api/endpoints/provisioning/where-the-payment-provider-delivers.md): NOT AN ENDPOINT YOU CALL. The payment provider posts here, and this is the step that turns a settled payment into admission and a provisioned device, and a reversal back out again.
- [Where the identity provider delivers](https://docs.phoneuse.com/api/endpoints/provisioning/where-the-identity-provider-delivers.md): NOT AN ENDPOINT YOU CALL. The identity provider posts here, and today this does one thing: it sends the sign-up verification email, in plain text, when the provider's own template is set not to deliver.
- [The bell, and the list behind it](https://docs.phoneuse.com/api/endpoints/notifications/the-bell-and-the-list-behind-it.md): What has happened that a person might want to know about: a run that needs somebody, and what became of an order.
- [Mark notifications read](https://docs.phoneuse.com/api/endpoints/notifications/mark-notifications-read.md): Marks these notifications read FOR YOU. Nobody else's bell changes.
- [Which emails you receive](https://docs.phoneuse.com/api/endpoints/notifications/which-emails-you-receive.md): Your own email preferences. `isDefault` is true until you set them, and what you see until then is what your role implies: an admin receives everything, a member receives requests for a person only.
- [Change which emails you receive](https://docs.phoneuse.com/api/endpoints/notifications/change-which-emails-you-receive.md): Send either field or both. A field you leave out keeps its current value, and when you have never set these that value is your role's default rather than off: sending only `emailOrders: false` must not silently turn off the emails a run sends when it asks for a person too.
- [Enroll a gateway computer](https://docs.phoneuse.com/api/endpoints/gateway-enrollment/enroll-a-gateway-computer.md): A new gateway computer trades an enrollment code, once, for its gateway id and tunnel credential. The installer calls it over HTTPS before the computer has any credential, so no `Authorization` is read: the code in the body is the credential. A gateway-bound code has 8 characters and lives 15 minute…
- [Read the current edge release](https://docs.phoneuse.com/api/endpoints/gateway-releases/read-the-current-edge-release.md): The manifest a gateway computer installs from: the newest release published on the channel that has not been withdrawn, with one package per platform. An installer reads it before installing, and an installed edge may read it again.
- [Help](https://docs.phoneuse.com/help/overview.md): Where to look, in the order that usually works.
- [Troubleshooting](https://docs.phoneuse.com/help/troubleshooting.md): Symptoms, what each one is telling you, and what to do next.
- [What phonebase is not](https://docs.phoneuse.com/help/what-phonebase-is-not.md): The boundaries of this surface, so you can rule it in or out quickly.

## OpenAPI Specs

- [openapi](/api/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.