Skip to main content
Base URL: the paired host (usually https://<label>.relay.fau.run). All routes below except POST /papi/pair require device signing. Canonical wire description: Wire specification § Phone API.

Endpoints

POST /papi/pair

See Pairing. Unsigned.

POST /papi/push-token

Register or clear this install’s Expo push token.
Clear:
Response: {"ok":true,"registered":true|false}. Token must look like ExponentPushToken[…] or ExpoPushToken[…]. Details: Push.

GET /papi/pending

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

POST /papi/decide

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. Response: {"ok":true} on success. Expired / unknown ids fail closed.

POST /papi/pause

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

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.