Skip to content

index.md

Latest commit

 

History

History
56 lines (39 loc) · 2.7 KB

index.md

File metadata and controls

56 lines (39 loc) · 2.7 KB
Raw
title REST API 参考
description Sink 的 OpenAPI 文档、身份认证、CORS 与端点索引。

REST API 参考

交互式文档

每个 Sink 实例都会发布 API 文档：

  • https://your-domain/_docs/openapi.json — 机器可读的 OpenAPI
  • https://your-domain/_docs/scalar — 更友好的界面
  • https://your-domain/_docs/swagger — 经典 Swagger 界面

请用你自己的域名。公开演示：https://sink.cool/_docs/scalar。

身份认证

在请求头里发送站点密码：

Authorization: Bearer YOUR_SITE_TOKEN

（Bearer 的意思是「后面是令牌」。）在单用户模式下，它必须与 NUXT_SITE_TOKEN 完全一致（至少 8 个字符）。在 OIDC 多用户模式下，受保护的 API 必须使用浏览器的 OIDC Session，并拒绝站点令牌。OIDC access token 和 ID token 始终保留在服务端，不会存入浏览器。

CORS

可选。构建时设置 NUXT_API_CORS=true，允许其他网站的浏览器调用 /api/**。仍需要登录。见配置参考。

调用链接 API 前

::: warning 存储必须就绪 部署后若还没打开过 Dashboard → Links，大多数 /api/link/** 会失败，并提示 「存储未就绪」（HTTP 423）。见存储初始化。 :::

  • upsert 空闲时创建；短链码已存在则返回已有记录且 status: "existing"（不覆盖）
  • search 匹配短链码、URL、备注和标签
  • check 从服务端探测目标 URL
  • verify 检查当前如何登录
  • location 在 Cloudflare 提供时返回大致坐标
  • 图片上传需要 R2（JPEG/PNG/WebP/GIF，最大 5 MB）

端点分组

完整请求/响应请看 OpenAPI 界面。

分组 路由
链接 /api/link/create、edit、upsert、delete、query、search、list、check、tags
导入/导出 /api/link/import、/api/link/export — 导入/导出
存储初始化 /api/link/migration/status、/api/link/migration/run — 存储初始化
AI /api/link/ai、/api/link/og-ai — Workers AI
访问分析 /api/stats/**、/api/logs/** — 访问分析
实用工具 /api/verify、/api/location、/api/upload/image、/api/backup