> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone API

> Full /papi/* surface for paired approval apps.

Base URL: the paired `host` (usually `https://<label>.relay.fau.run`). All routes below
except `POST /papi/pair` require [device signing](https://docs.fau.run/developer/apps/signing.md).

Canonical wire description: [Wire specification](https://docs.fau.run/developer/protocol/spec.md) § Phone API.

## Endpoints

### `POST /papi/pair`

See [Pairing](https://docs.fau.run/developer/apps/pairing.md). Unsigned.

### `POST /papi/push-token`

Register or clear this install’s Expo push token.

```json theme={null}
{"token":"ExponentPushToken[…]"}
```

Clear:

```json theme={null}
{"token":""}
```

Response: `{"ok":true,"registered":true|false}`.

Token must look like `ExponentPushToken[…]` or `ExpoPushToken[…]`. Details:
[Push](https://docs.fau.run/developer/apps/push.md).

### `GET /papi/pending`

List open prompts.

```json theme={null}
{
  "approvals": [ /* Approval */ ],
  "paused": false,
  "server_time": 1760000000
}
```

Poll on a timer (foreground + when returning to foreground). Also refresh when a push
arrives.

### `POST /papi/decide`

```json theme={null}
{
  "approval_id": "ap_…",
  "decision": "deny",
  "ts": 1760000123,
  "nonce": "<random>"
}
```

Optional edit fields may accompany send flows when the product allows changing the
draft before allow — follow the reference app if you implement edit-and-send.

| `decision` | Kind | Meaning |
| - | - | - |
| `deny` | access | Refuse |
| `once` | access | Allow once |
| `30_days` | access | Time-bounded allow |
| `always_category` | access | Standing allow for requested categories |
| `reject` | send | Do not send |
| `send` | send | Send this draft |

Response: `{"ok":true}` on success. Expired / unknown ids fail closed.

### `POST /papi/pause`

```json theme={null}
{"paused": true}
```

When paused, agents cannot obtain new access; your UI should say so clearly. Any `2xx`
is success (body shape is not strictly required).

### `GET /papi/activity?limit=`

Recent decisions in a phone-friendly form (for a history screen). **Sign the path
including the query string.**

## Approval object

```json theme={null}
{
  "id": "ap_…",
  "kind": "access",
  "agent_domain": "assistant.example",
  "agent_verified": true,
  "match_code": "47",
  "created_at": 1760000000,
  "expires_at": 1760000300,
  "summary": "wants to read your travel email for 30 days",
  "requested": {
    "tier": "raw_read",
    "categories": ["travel"],
    "duration_days": 30
  },
  "detail": {
    "question": "…",
    "thread_subject": "…",
    "draft": {
      "draft_id": "…",
      "to": [],
      "subject": "",
      "body": "",
      "attachments": []
    }
  }
}
```

| Field | UI |
| - | - |
| `agent_domain` | Primary identity line |
| `agent_verified` | If false, show that the user connected this agent themselves |
| `match_code` | Two digits — large and obvious; must match what the agent shows |
| `summary` | Human line for the card |
| `detail` | Extra context; for `send`, render the draft carefully |

Default prompt TTL is on the order of **five minutes** (`expires_at`). Sort by urgency
(soonest expiry first).

## UX rules that are part of the product

* **Deny first** in reading order; never mark Allow as the suggested control.
* Confirm before `send` (irreversible).
* Do not offer `always_category` until the user has allowed that category before, unless
  you have a very explicit standing-permission UX.
* If `paused` is true, show how to unpause.

## Errors

Treat transport failures as “laptop unreachable — keep the Mac awake.” Treat `4xx` as
actionable (re-pair, expired prompt, bad signature). Do not retry `4xx` in a tight loop.


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