> ## Documentation Index > Fetch the complete documentation index at: https://docs.phoneuse.com/llms.txt > Use this file to discover all available pages before exploring further. # Check that the service is up > 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`. A hosted deployment running the billing loop reports one boolean for it, and nothing else about the deployment is disclosed. ## OpenAPI ````yaml /api/openapi.json get /healthz openapi: 3.1.0 info: title: Phonebase HTTP API version: 0.1.0 summary: >- Every HTTP operation the control plane mounts, generated from the app's own route table. description: >- The control plane exposes two HTTP surfaces, and reading the boundary between them matters more than reading any single endpoint. The CONTROL surface is what your backend and your operators call. It takes a bearer token in the `Authorization` header, and two credential channels resolve to the same authorization context: an OAuth 2.1 access token for interactive clients, or an org scoped API key for headless ones. The DEVICE surface, under `/vrx/{runToken}/v1`, is what a worker calls while executing one run. Its credential is the run token in the url path, and it reads no `Authorization` header at all. Device control itself is not REST. An agent taps, swipes and reads the screen over the Model Context Protocol at `POST /mcp`, one tool call at a time. There is no `POST /v1/devices/{id}/tap`, and if you are looking for one, start with the tool reference instead. Operations marked `"x-phonebase-modes": ["hosted"]` exist only on a hosted deployment; a local checkout does not mount them. servers: - url: '{origin}' description: Your control plane origin. variables: origin: default: https://mcp.phonebase.co enum: - https://mcp.phonebase.co - http://127.0.0.1:8788 description: >- The hosted deployment serves the public origin its metadata document advertises, and that is the default here. Select the loopback entry instead when you are running a local checkout, which serves the port `PORT` names. security: [] tags: - name: Apps description: Save immutable application builds and manage explicit device operations. - name: Managed Proxy description: >- Organization-owned fixed egress resources, independent one-time orders and verified network relationships. - name: Health description: Liveness, unauthenticated. - name: Gateway enrollment description: >- How a new gateway computer trades a one-time enrollment code for its tunnel credential. Unauthenticated: the code is the credential. - name: Gateway releases description: >- What a gateway computer installs: the current edge release of a channel. Called with the gateway's own credential. - name: MCP description: The JSON-RPC endpoint an agent drives devices through. - name: Copilot description: >- Drive a device by chatting. A signed in person's own conversations, streamed. Hosted deployments only. - name: Discovery description: Where to authenticate. Served on hosted deployments only. - name: Runs description: Start, watch and steer a run. - name: API keys description: Mint and revoke headless credentials. Hosted deployments only. - name: Device surface description: What a worker calls with its run token to observe and act. - name: Usage description: Read your org's own receipts and consumption. Hosted deployments only. - name: Devices description: Read the fleet your credential can see. Hosted deployments only. - name: Notifications description: >- What a person needs to know when they are not watching, and which emails they receive. Hosted deployments only. - name: Webhooks description: >- Subscribe your own system to what happens here, and read what was delivered. Hosted deployments only. - name: Provisioning description: >- Whether an organisation is provisioned, and how it becomes so. Hosted deployments only, and both operations answer a declared 503 on a deployment that cannot provision yet. paths: /healthz: get: tags: - Health summary: Check that the service is up description: >- 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`. A hosted deployment running the billing loop reports one boolean for it, and nothing else about the deployment is disclosed. operationId: getHealthz responses: '200': description: The service is serving. content: application/json: schema: $ref: '#/components/schemas/Health' security: [] components: schemas: Health: type: object properties: ok: type: boolean description: True whenever the process is serving. service: type: string description: A constant service identifier. status: type: string enum: - ok - degraded - incident description: >- ONE WORD about the whole service, so a reader does not have to invent its own definition of down from the per subsystem booleans below. `degraded` means at least one of those booleans is false; `incident` means an operator declared one, and a declaration wins over a clean set of loops because a person can see faults this process cannot. An absent subsystem is a configuration and never counts against this word. incident: type: object properties: title: type: string description: >- One sentence, written by an operator, meant to be shown to a person. url: type: string description: >- Where to read more. The public status page unless something narrower was named. required: - title - url additionalProperties: false description: >- Present only while an operator has declared an incident. A half declaration (a sentence with no link) is discarded rather than published, because a banner whose link goes nowhere teaches people to ignore banners. statusPage: type: string description: >- The public status page, when this deployment has one. Published so a reader links to it without hardcoding an address, and absent rather than guessed when there is none. revision: type: string description: >- The exact build this process is running, as an opaque identifier. Published because it is the only way to tell a deployment that finished from one that is still rolling, and absent when nothing was baked into the image rather than guessed at. billing: type: object properties: ok: type: boolean viewC: type: string required: - ok additionalProperties: false description: >- Present only on a hosted deployment that runs the billing loop. `viewC` appears only while a billing migration is outstanding and names which way it is outstanding. frames: type: object properties: ok: type: boolean required: - ok additionalProperties: false description: Present only where the frame retention sweep runs. webhooks: type: object properties: ok: type: boolean required: - ok additionalProperties: false description: Present only where the webhook delivery loop runs. fulfilmentUnwind: type: object properties: ok: type: boolean required: - ok additionalProperties: false description: >- Present only where the loop that unwinds a paid order that never arrived runs. fleetIntegrity: type: object properties: ok: type: boolean required: - ok additionalProperties: false description: >- Whether every device this deployment sells is one the provider still has, and none of them reaches the end of its paid provider term within the alert window (72 hours by default) without being renewed. ABSENT when the verdict is unknown, which is why a reader must treat a missing key as 'not answered' and never as 'fine': staging omits it today and production does not. email: type: object properties: ok: type: boolean required: - ok additionalProperties: false description: >- Whether a notification can reach a person by mail. False is a real and ordinary state: the bell still fills, and nobody is told while the console is shut. Not counted into `status`. cloudReadyEmail: type: object properties: enabled: type: boolean required: - enabled additionalProperties: false description: >- Whether the worker that emails the buyer when a Cloud phone is ready is running in this process. False is the ordinary state until delivery is switched on. Not counted into `status`. liveVideo: type: object properties: state: type: string enum: - configured - unconfigured - partial - invalid description: >- `configured`: live video for robot-driven phones is on. `unconfigured`: this deployment has no media server, which is an ordinary configuration. `partial` or `invalid`: somebody started configuring one and it is not usable yet, so live video is off and robot-driven phones answer still images. required: - state additionalProperties: false description: >- Whether live video for robot-driven phones is switched on here. Never counted into `status`. latencyProbes: type: object properties: state: type: string enum: - installed - missing description: >- `installed`: rig latency probe results can be recorded and read. `missing`: the database this deployment runs on does not have their table yet, so that one capability is off and everything else is served normally. required: - state additionalProperties: false description: >- Whether the rig latency probe results are available here. Present only on a deployment with a database. Never counted into `status`. opsAlerts: type: object properties: state: type: string enum: - configured - partial - unconfigured - unavailable description: >- `configured`: operations alerts are mailed to the on-call list, or to the staff organization's admins. `unconfigured`: nothing alert-specific is set, an ordinary configuration. `partial`: somebody set part of it, so alerts are recorded and shown on the operations console and `reasons` says what is missing. `unavailable`: the database has no alert tables yet, so no alert is recorded or mailed at all (red for operations; still never counted into `status`). reasons: type: array items: type: string enum: - not_hosted - email_sender - recipient_directory - staff_org_id - on_call_list_unusable - on_call_list_entries_dropped - alert_tables_missing description: >- What is missing or unusable, by name. Never an address or a value. description: Empty when `state` is `configured`. required: - state - reasons additionalProperties: false description: >- Whether operations alerts reach a person by email here. Never counted into `status`. ownerMoney: type: object properties: state: type: string enum: - configured - unconfigured - refused_live_key_on_staging - refused_environment_undeclared description: >- Whether the owner's refund from the operator surface may move money here. `refused_live_key_on_staging`: this deployment says it is staging and holds a live payment key, so the refund is refused. `refused_environment_undeclared`: a live key on a deployment that does not say which it is. required: - state additionalProperties: false description: Hosted only. A configuration, never counted into `status`. staffDirectory: type: object properties: state: type: string enum: - configured - unconfigured - partial description: >- Whether staff management from the operator surface can reach the identity provider. `partial`: keys are configured and none can be matched to the staff organisation, so staff management is refused. required: - state additionalProperties: false description: Hosted only. A configuration, never counted into `status`. staffOrgs: type: object properties: state: type: string enum: - configured - unconfigured - unbound - misconfigured description: >- Whether anybody can be admitted to the operator surface. `configured`: the staff organisations are each bound to an identity provider instance this deployment trusts. `unconfigured`: none is set, so nobody is staff by choice. `unbound`: one is set without its instance while several instances or none are trusted, so nobody is staff and every operator call is answered 404 until it names its instance. `misconfigured`: at least one entry was malformed and left out at startup (the startup log says which and why); the others still admit their staff, unless the one left out was the first, in which case nobody is staff. required: - state additionalProperties: false description: >- Hosted only. A configuration, never counted into `status`. A state only, never an organisation id. schedules: description: >- The customer-facing schedule sweeper. `disabled` is a configuration and never degrades `status`. oneOf: - type: object properties: state: type: string enum: - disabled required: - state additionalProperties: false - type: object properties: state: type: string enum: - running ok: type: boolean required: - state - ok additionalProperties: false provisioning: description: >- The loop that puts a cloud phone in a customer's hands. `disabled` means every such order waits for a person, which is why absence is PUBLISHED here rather than left as a missing key. oneOf: - type: object properties: state: type: string enum: - disabled required: - state additionalProperties: false - type: object properties: state: type: string enum: - running ok: type: boolean required: - state - ok additionalProperties: false deviceTakes: description: >- The loop that takes a device back when a session ends without releasing it. `disabled` means a session that ends badly keeps its machine. oneOf: - type: object properties: state: type: string enum: - disabled required: - state additionalProperties: false - type: object properties: state: type: string enum: - running ok: type: boolean required: - state - ok additionalProperties: false cloudBillingScan: description: >- The hosted missed-Stripe-webhook Cloud billing scan. `disabled` means no periodic recovery pass runs on this instance. oneOf: - type: object properties: state: type: string enum: - disabled required: - state additionalProperties: false - type: object properties: state: type: string enum: - running ok: type: boolean required: - state - ok additionalProperties: false cloudRenewalScan: description: >- The hosted managed Cloud term scan. `disabled` means no periodic pass runs; `running` can be observation-only, with supplier spending and period-end billing stop separately switched off. oneOf: - type: object properties: state: type: string enum: - disabled required: - state additionalProperties: false - type: object properties: state: type: string enum: - running ok: type: boolean required: - state - ok additionalProperties: false rigTelemetry: type: object properties: ok: type: boolean description: >- False when the storage for robot arm health samples reaches less than one day ahead, or has not been measured yet. Samples stop being stored when it runs out; device health and availability are unaffected. partitionHeadroomMs: type: integer minimum: 0 description: >- How far ahead of now sample storage is prepared, in milliseconds, rounded down to a whole hour. Absent until the first measurement. required: - ok additionalProperties: false description: >- Present only on a hosted deployment with a database, where robot arm health samples are kept. Not counted into `status`. opsStream: type: string enum: - listen - polling description: >- How this replica hears the operator console's live events. `listen`: a checked database notification channel delivers them as they happen. `polling`: they are read every 5 seconds, which is also what serves when no notification channel is configured. Present only where the operator surface runs with a database. Never counted into `status`. tenancy: type: object properties: checkout: type: object properties: state: type: string enum: - open - closed - unconfigured description: >- Whether the purchase surface is open, shut on purpose, or has never been configured. Shut and never-configured are the same absent settings, so they are told apart here rather than guessed at. mode: type: string enum: - test - live - unknown description: >- Whether the purchase surface moves real money. Read off the payment provider key the deployment holds, so a deployment cannot declare one and charge the other. `unknown` means there is no key, or one whose shape this service does not recognise; a reader showing a test-mode notice must show it for `test` alone. dayPass: type: string enum: - priced - unpriced - withheld description: >- Whether this deployment holds a price for the robot arm iPhone day pass. It describes the configuration only: no sku sells the day pass today, so `GET /v1/skus` lists no `day` row even when this says `priced`. `withheld` means a price is configured on a till that takes real money and is deliberately not used. cloudPhone: type: string enum: - priced - unpriced - withheld description: >- Whether Cloud phone prices are configured and available on this till. `withheld` means prices were configured but the live Cloud phone billing interlock removed them while supplier renewal and Stripe reconciliation are incomplete. The generic till may still be `open`. required: - state - mode additionalProperties: false required: - checkout description: >- Deployment posture, on a hosted deployment only. Enums throughout and never a timestamp, an issuer name or a count: a reader learns which gates are armed, not when one opens. required: - ok - service - status additionalProperties: false description: >- Deliberately terse. The backend inventory is reconnaissance material and is never reported on an unauthenticated endpoint. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.