For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/mobile/api.md (or send Accept: text/markdown).
Mobile API
How the app talks to the server — sessions, reachability, and payloads.
Beginner walkthrough
Prerequisites: Read the two beginner guides below and finish Mobile local setup. Put Expo values in apps/mobile/.env.local; set EXPO_PUBLIC_API_URL to a backend host your device can reach. A mobile-only checkout has no web backend, so start or connect one separately. A successful Expo export proves the JavaScript bundle, not device or purchase acceptance.
Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL.
1. In apps/mobile/.env.local, set EXPO_PUBLIC_API_URL to the running backend address reachable from your phone; do not use localhost from a physical device.
2. Follow Mobile local setup to start Expo, sign in, and open workspace, settings, and chat screens.
3. Expect authenticated data from the same workspace. If requests time out, check the phone and computer network and start the backend separately in a mobile-only checkout.
For custom code, start with the supplied prompts/README.md and copy the closest prompt: prompts/new-app-screen.md for an app screen or prompts/new-landing-page.md for a public page. For server, database, or provider work, give your coding agent this guide's task and ask it to read AGENTS.md, .ai/PROJECT_CONTEXT.md, and matching .ai/ mirrors; inspect the exact source files named here; list files and checks before editing; preserve workspace ownership and server-only secrets; and show you the diff. Tell it the behavior you want, input and output fields, allowed roles, expected success and errors, and the test account, provider, or device. Use sample values; never paste a real secret.
Understand native scope
Expo includes native auth/session and deep links alongside workspace, settings, chat, and RevenueCat purchase surfaces. Shared business behavior and authorization stay in the web backend/packages; native clients under apps/mobile/src call those APIs without embedding provider credentials.
Use the session-authenticated BFF
The /api/mobile routes cover entitlement, RevenueCat purchase availability and server sync, organization, members, invitations, audit, API keys, webhooks, domains, schedules and feature requests. They preserve workspace ownership and role checks. They are different from the sk_ bearer-key /api/v1 public contract.
Use your device-reachable EXPO_PUBLIC_API_URL and the configured origin/scheme; public Expo variables never contain provider credentials.
Verify on native targets
Check loading/error/empty states, reconnect, expired session, forbidden management actions and deep-link returns on the device/build you intend to support. An Expo export proves bundling, not native delivery or purchase acceptance.
Setup and configuration
The app calls the API under /api/mobile and the versioned /api/v1 surface with the member's session rather than cookie assumptions from the web app. EXPO_PUBLIC_API_URL is the only origin the client knows; it is public by design and carries no secrets.
Session tokens come from the Better Auth Expo flow and are kept in native secure storage — never in plain AsyncStorage or bundled config.
GET /api/mobile/entitlement # access state for the member
GET /api/mobile/organization # active workspace context
GET /api/mobile/usage # current-month AI spend, meter caps, and credit balance
GET /api/mobile/appearance # synced appearance bundle (GET/PUT)
POST /api/v1/ai-tasks # authorized work, same as web
Session: /api/auth/* (Better Auth Expo flow)
# Optional server-only token for authenticated Expo push sends:
# EXPO_ACCESS_TOKEN=Implementation workflow
Resolve the stored session before the first authenticated request, refresh it when the server reports expiry, and sign out cleanly when it is revoked. Treat unreachable API and invalid session as different states — one retries, the other returns to sign-in.
Keep payloads identical to the web contract: the server applies the same workspace, entitlement, and validation rules regardless of which client called.
Verification and troubleshooting
Test airplane-mode failures, expired tokens mid-session, revoked sessions, and a cold start with a stored valid token. A request that fails closed (denied) is correct; one that fails open is a bug to fix before release.