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 /zh-tw/docs/mobile/api.md (or send Accept: text/markdown).
移動端 API
應用如何與伺服器通訊 —— 會話、可達性與負載。
初學者演練
先決條件：閱讀下面的兩個初學者指南並完成移動本地設定。將Expo值放入apps/mobile/.env.local中；將 EXPO_PUBLIC_API_URL 設定為您的裝置可以訪問的後端主機。僅限移動裝置的結帳沒有網路後端，因此請單獨啟動或連線一個。成功的 Expo 匯出證明 JavaScript 捆綁包，而不是裝置或購買接受。
簡而言之：工作區是一個團隊的單獨使用者、資料和設定。伺服器是可信後端；讓提供商金鑰遠離瀏覽器和電話程式碼。遷移是建立或更新表的版本化資料庫更改。人工智慧模型是回答的引擎；型號目錄是伺服器上可用型號 ID 和價格的列表。提供商是一種外部服務，例如人工智慧、電子郵件或計費服務。權利是允許工作區使用某項功能的授權。 Webhook 是一個服務傳送到另一個服務的 URL 的訊息。
1、在apps/mobile/.env.local中，將EXPO_PUBLIC_API_URL設定為手機可訪問的執行後端地址；請勿從物理裝置使用 localhost。
2. 按照移動本地設定啟動 Expo、登入並開啟工作區、設定和聊天螢幕。
3. 期望來自同一工作區的經過身份驗證的資料。如果請求超時，請檢查手機和計算機網路，並在僅限移動裝置的結帳中單獨啟動後端。
對於自定義程式碼，請從提供的 prompts/README.md 開始，然後複製最接近的提示：對於應用程式螢幕為 prompts/new-app-screen.md，對於公共頁面為 prompts/new-landing-page.md。對於伺服器、資料庫或提供商工作，請為您的編碼代理提供本指南的任務，並要求其讀取 AGENTS.md、.ai/PROJECT_CONTEXT.md 和匹配的 .ai/ 映象；檢查此處指定的確切原始檔；列出檔案並在編輯前進行檢查；保留工作區所有權和僅限伺服器的機密；並向您展示差異。告訴它您想要的行為、輸入和輸出欄位、允許的角色、預期的成功和錯誤以及測試帳戶、提供程式或裝置。使用樣本值；永遠不要貼上真正的秘密。
瞭解本機範圍
Expo 包括本機身份驗證/會話和深度連結以及工作區、設定、聊天和 RevenueCat 購買介面。共享業務行為和授權保留在 Web 後端/包中； apps/mobile/src 下的本機客戶端呼叫這些 API 時無需嵌入提供者憑據。
使用會話認證的BFF
/api/mobile 路由涵蓋權益、RevenueCat 購買可用性與伺服器同步、組織、成員、邀請、審計、API 金鑰、webhook、域名、計劃任務、功能請求、推送 token、外觀、電商、內容、額度與用量。它們保留工作區歸屬和角色檢查，與 sk_ bearer 金鑰的 /api/v1 公共契約不同。
使用裝置可訪問的 EXPO_PUBLIC_API_URL 和已配置的 origin/scheme；公開的 Expo 變數絕不包含供應商憑據。
在本機目標上進行驗證
檢查您打算支援的裝置/版本上的載入/錯誤/空狀態、重新連線、過期會話、禁止的管理操作和深層連結返回。 Expo 匯出證明捆綁，而不是本地交付或購買接受。
安裝與配置
應用呼叫 /api/mobile 和版本化的 /api/v1 端面下的 API,使用成員會話而非 Web 應用的 Cookie 假設。EXPO_PUBLIC_API_URL 是客戶端唯一知道的源;它在設計上是公開的,不攜帶金鑰。
會話令牌來自 Better Auth Expo 流程,儲存在原生安全儲存中 —— 絕不在明文 AsyncStorage 或打包配置中。
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/mobile/push-tokens # register this device for push
/api/chat/threads*, /api/chat/stream # chat, same contract as web
POST /api/v1/agent-runs # budgeted assistant runs
Session: /api/auth/* (Better Auth Expo flow)
# Optional server-only token for authenticated Expo push sends:
# EXPO_ACCESS_TOKEN=實現流程
在第一個認證請求之前解析儲存的會話,當伺服器報告過期時重新整理,被吊銷時乾淨地登出。將 API 不可達和無效會話視為不同狀態 —— 一個重試,另一個返回登入。
保持負載與 Web 契約相同:無論哪個客戶端呼叫,伺服器都應用相同的工作區、entitlement 和驗證規則。
驗證與排障
測試飛航模式失敗、會話中途令牌過期、已吊銷會話,以及帶著已儲存有效令牌的冷啟動。以失敗關閉(拒絕)結束的請求是正確的;以失敗開放結束的是釋出前要修復的 bug。