> ## 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/docs/web/before-you-start.md)

[学习命令、文件和配置](https://supastack.dev/zh/docs/web/terminal-basics.md)

[完成Web首次运行教程](https://supastack.dev/zh/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/docs/modules/rate-limiting.md)