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/docs/modules/api.md (or send Accept: text/markdown).

API 模块

版本化的公开契约、密钥管道与 OpenAPI 端面。

询问本指南

开始之前

使用“文件”→“打开文件夹”在 Visual Studio Code 中打开下载的 supastack 项目，然后选择“终端”→“新建终端”。存储库根目录是包含 package.json、apps 和 packages 的文件夹。运行下面的命令并保持终端打开。如果无法识别命令，请先完成工具安装指南，然后再继续。

首先阅读平台教程。服务器是响应浏览器或电话请求的应用程序进程。 Web 读取 apps/web/.env.local，Expo 读取 apps/mobile/.env.local，数据库迁移命令读取 root .env。无数据库/仪表板演示与真实/身份验证帐户分开，需要迁移Postgres。仅电话或桌面结帐需要单独运行的 Web 后端。

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。