Skip to main content
Everything an agent does on a phone goes through these endpoints. The MCP phone tools call the same API.
Authenticate with your API key in the X-API-Key header. See Authentication. Phones endpoints use 0 API credits and need no paid plan. The API key must belong to the account that is signed in to Appeeky Desktop.
All endpoints live under https://api.appeeky.com/v1. Successful responses return { "data": ... }. Errors return { "error": { "code": "...", "message": "..." } }.

List phones

Each connector is one Mac that is running Appeeky Desktop with phone sharing on. When no Mac is sharing, connectors is an empty array.

Run an action

The body has one field, invocation, with a method and that method’s parameters.
device is optional when exactly one phone is online, and at most 200 characters. Actions that take observe return an observation by default, and { "kind": "done", "action": "<method>" } when you pass "observe": false. See Actions for every parameter, its default and the platform support.

Response shapes

Actions that wait for approval

When a tap or long_press needs approval, the HTTP request stays open until you approve, deny, or the request expires after 10 minutes. Set your HTTP client’s timeout to more than 10 minutes for these calls.
  • Approved: the action runs and you get the normal result.
  • Denied or expired: status 422 with the code APPROVAL_DENIED.
  • Your connection closed while waiting: the approval request is still open. If you approve it, the tap runs. Call observe to see the result.
See Approvals and safety for which taps pause.

Run the phone agent

The response is application/x-ndjson: one JSON event per line. The run stops after 30 steps, when the agent reports it is done, or when you deny an approval. Close the connection to stop it early. See Phone agent for an example stream and how runs end.

Approvals

List approvals

Returns up to 50 requests, newest first. pending leaves out requests that have already passed their expiry time.

Decide an approval

Send true to approve or false to deny. The response is the updated request, without the screenshot:
This endpoint accepts only a signed-in dashboard session. A request with an API key is rejected, so an agent can never approve its own tap. Use the Phones page in the dashboard to decide.

Errors

See Troubleshooting for the common PHONE_ACTION_FAILED messages and what to do about each.