API 参考

所有端点都相对于 API 的 base URL，位于 /v1 前缀之下（参见 Versioning）。所有需要认证的端点都使用由 POST /v1/auth/verify-login-code 设置的 httpOnly session cookie——目前还没有单独的 API 密钥认证方式（参见 Authentication）。

auth

Method	Path	Auth	备注
POST	/v1/auth/request-login-code	—	{ email }. 通过邮件发送 6 位验证码，首次使用时创建账户；始终返回相同的消息。按 IP 和按邮箱分别进行限流。
POST	/v1/auth/verify-login-code	—	{ email, code }. 设置 session cookie。按 IP 和按邮箱分别进行限流。
POST	/v1/auth/logout	session	清除 session cookie。
GET	/v1/auth/me	session	返回当前用户。
GET	/v1/auth/google	—	重定向到 Google OAuth。
GET	/v1/auth/google/callback	—	OAuth 回调；成功后重定向回应用内。
GET	/v1/auth/facebook	—	重定向到 Facebook OAuth。
GET	/v1/auth/facebook/callback	—	OAuth 回调；成功后重定向回应用内。
POST	/v1/auth/forgot-password	—	{ email }。无论该邮箱是否已注册，始终返回相同的消息。
POST	/v1/auth/reset-password	—	{ token, password }。Token 仅可使用一次，且会过期。

chat

Method	Path	Auth	备注
POST	/v1/chat	session	{ model, messages, conversationId?, idempotencyKey }。以纯文本形式流式返回响应体；响应的 x-conversation-id 头携带 conversation id。idempotencyKey 是必需的——使用相同 key 重试的请求永远不会重复计费或重复调用供应商。

skills

Method	Path	Auth	备注
POST	/v1/skills	session	{ name, instruction, input_schema?, output_schema? }。创建一个你账户私有的 Skill。
GET	/v1/skills	session	列出你自己的 Skill。
GET	/v1/skills/templates	session	列出可复制为你自己 Skill 的起始模板。
POST	/v1/skills/templates/:id/duplicate	session	将一个模板复制为你自己的新 Skill。
POST	/v1/skills/import	session	{ name, instruction, input_schema?, output_schema?, version? }——与 GET /v1/skills/:id/export 产生的数据形状完全一致，因此 export → import 可以往返互通。任何其他字段（id、owner_id、organization_id、allowed_tools）都会被直接拒绝；被导入的 Skill 永远不会从文件中带入工具绑定（tool binding）。
GET	/v1/skills/:id	session	你拥有的一个 Skill，包含它的所有版本。
GET	/v1/skills/:id/export	session	可移植的 { name, instruction, input_schema, output_schema, version } 数据形状，与 import 端点的输入相匹配。
POST	/v1/skills/:id/versions	session	{ instruction, input_schema?, output_schema? }。发布一个新的不可变版本。
POST	/v1/skills/:id/run	session	{ model, input, conversationId?, idempotencyKey }。重新进入与 POST /v1/chat 相同的 chat 处理流程，input 代替那一条用户消息——具有相同的 idempotency/quota/ledger 行为。

conversations

Method	Path	Auth	备注
GET	/v1/conversations	session	列出你自己的对话。
GET	/v1/conversations/:id	session	单个对话及其消息。对于你不拥有的对话会返回 404。

files

Method	Path	Auth	备注
GET	/v1/files	session	列出你自己已上传的文件。
POST	/v1/files	session	Multipart 上传，字段名为 file。接受纯文本、Markdown、PDF 和 .docx，最大 20 MB。
DELETE	/v1/files/:id	session	删除一个你拥有的文件（存储对象 + 记录）。

plans

Method	Path	Auth	备注
GET	/v1/plans	—（公开）	列出各 plan 的价格和允许使用的模型——刻意设为公开，以便在登录前就能看到价格。

billing

Method	Path	Auth	备注
POST	/v1/billing/checkout	session	{ planId, provider: "sepay" | "paddle" }。被收取的金额始终来自服务端对 plan 的查询，绝不会来自客户端。Free 和 Enterprise 这两个 plan 无法通过此方式结账。
GET	/v1/billing/quota	session	你当前的每日 quota 限额与剩余余额。

运行中的 API 还存在另外两个资源，但本文档中没有将它们作为面向客户的功能记录：/v1/webhooks/*（仅入站，由 SePay/Paddle 调用——不是你自己要调用的东西）和 /v1/admin/*（内部使用，仅限 admin）。