> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# API 模組

版本化的公開契約、金鑰管道與 OpenAPI 端面。

## 開始之前

使用“檔案”→“開啟資料夾”在 Visual Studio Code 中開啟下載的 supastack 專案，然後選擇“終端”→“新建終端”。儲存庫根目錄是包含 package.json、apps 和 packages 的資料夾。執行下面的命令並保持終端開啟。如果無法識別命令，請先完成工具安裝指南，然後再繼續。

首先閱讀平臺教程。伺服器是響應瀏覽器或電話請求的應用程式程式。 Web 讀取 apps/web/.env.local，Expo 讀取 apps/mobile/.env.local，資料庫遷移命令讀取 root .env。無資料庫/儀錶板演示與真實/身份驗證帳戶分開，需要遷移Postgres。僅電話或桌面結帳需要單獨執行的 Web 後端。

[安裝工具並獲取程式碼](https://supastack.dev/zh-tw/docs/web/before-you-start.md)

[學習命令、檔案和配置](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)

[完成Web首次執行教程](https://supastack.dev/zh-tw/docs/web/ship-in-5-minutes.md)

```
corepack pnpm --filter @supastack/web dev
```


## 安裝與配置

packages/api 是公開 REST 端面的真實來源:請求、響應和錯誤信封的 zod 模式,加上在 /api/v1/openapi 提供的 OpenAPI 檔案(openApiDocument)。路由處理器組合這些模式,而不是重新定義形狀。

API 金鑰按工作區簽發,字首為 sk_<env>_,以常量時間比較的雜湊儲存,並攜帶作用域 —— 預設讀取。api-keys.ts 擁有建立、查詢和吊銷。

```
apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi
```


## 實現流程

在現有版本內新增端點:擴充套件模式、保持錯誤信封,並重新生成 OpenAPI 端面,使 /api/docs 保持準確。破壞性變更獲得新版本,而不是悄悄改變形狀。

從提交的金鑰解析呼叫方的工作區,應用與 Web 應用相同的 entitlement 和驗證規則,並按金鑰限流。


## 驗證與排障

對每個路由形狀針對包模式做契約測試。驗證未知的、已吊銷的和作用域不足的請求都以檔案化的錯誤信封失敗,並且 OpenAPI 檔案保持為合法 JSON。


## 下一篇

[限流](https://supastack.dev/zh-tw/docs/modules/rate-limiting.md)