API Key 与外部 API#

API Key 用于让外部程序调用 OctoRill 的用户态业务接口，例如读取 feed、Release、通知、日报，或触发同步、翻译与 reaction 刷新。它和网页登录态绑定到同一个用户数据范围，不提供管理员接口、登录接口或 API Key 管理接口本身。

如果只需要展示公开 GitHub 仓库 Releases，不需要登录用户数据，请使用 公开 Release 接入。

创建与使用#

API Key 在已登录的用户设置页创建，格式以 orill_ak_ 开头。当前管理响应会返回完整 api_key 与 masked_key，因此这些 session-only 管理接口的响应也必须按敏感数据处理。

所有外部请求都使用 Bearer 认证：

curl "$OCTORILL_ORIGIN/api/feed?scope=mine&limit=20" \
  -H "Authorization: Bearer orill_ak_xxx"

浏览器端程序只有在页面 origin 等于 OctoRill 配置的 public_base_url origin 时，才能通过 CORS 携带 Authorization header 访问；后端允许常见 HTTP method 与 Content-Type、Authorization header，但不会放开任意第三方 origin。其它外部程序应从服务端、CLI 或同源前端调用。

API Key 被撤销后会立即失效。用户账号被禁用后，即使 API Key 仍存在，也会返回 403 account_disabled。

管理接口边界#

API Key 管理接口只能用网页登录态调用，不能用 API Key 调用：

ApiKeySummary 字段：

可调用接口目录#

以下接口都支持 Authorization: Bearer orill_ak_...：

这些接口不属于 API Key 可调用范围：/api/me*、/api/reaction-token*、/api/auth*、/api/admin*、/auth*。

Focus 页面对应的 API#

/focus/* 页面对应同一个 feed API，通过 query 参数表达 scope：

示例：

curl "$OCTORILL_ORIGIN/api/feed?scope=repo&items=IvanLi-CN/octo-rill&types=releases&limit=30" \
  -H "Authorization: Bearer orill_ak_xxx"

curl "$OCTORILL_ORIGIN/api/feed?scope=repos&items=owner/a,owner/b&cursor=$CURSOR" \
  -H "Authorization: Bearer orill_ak_xxx"

curl "$OCTORILL_ORIGIN/api/feed?scope=org&org=IvanLi-CN" \
  -H "Authorization: Bearer orill_ak_xxx"

curl "$OCTORILL_ORIGIN/api/feed?scope=mine" \
  -H "Authorization: Bearer orill_ak_xxx"

scope=repos 最多接受 12 个仓库，重复项会按大小写无关规则去重。limit 默认 30，范围会被限制在 1..100；响应里的 next_cursor 可作为下一页 cursor。

types 可选 all、releases、stars、followers。scoped focus feed 不返回 follower-only 内容。

Feed#

GET /api/feed

Query：

响应 FeedResponse：

FeedItem 是按 kind 区分的 union：

Release、通知、日报#

读取接口：

主要字段：

Dashboard updates#

GET /api/dashboard/updates

用于外部程序轮询“列表是否变化”，不会返回完整列表内容。

Query：

响应：

Reaction#

POST /api/feed/reactions/refresh

{ "release_ids": ["123", "456"] }

release_ids 最多 100 个，必须是当前用户可见 Release。响应：

{
  "items": [
    {
      "release_id": "123",
      "reactions": {
        "counts": { "plus1": 0, "laugh": 0, "heart": 0, "hooray": 0, "rocket": 0, "eyes": 0 },
        "viewer": { "plus1": false, "laugh": false, "heart": false, "hooray": false, "rocket": false, "eyes": false },
        "status": "ready"
      }
    }
  ]
}

POST /api/release/reactions/toggle

{ "release_id": "123", "content": "heart" }

content 可选 plus1、laugh、heart、hooray、rocket、eyes。该接口需要用户配置有效 GitHub PAT；未配置时返回 403 pat_required。

同步、日报生成与任务流#

这些接口支持 query 参数 return_mode：

TaskAcceptedResponse：

可调用接口：

POST /api/briefs/generate body 可省略；如指定日期：

{ "date": "2026-07-06" }

BriefGenerateResponse 字段：id、date、window_start、window_end、effective_time_zone、effective_local_boundary、release_count、release_ids、content_markdown。

任务 SSE 可通过 GET /api/tasks/{task_id}/events 读取。这个接口同样支持 API Key，适合配合 return_mode=task_id 使用。

翻译接口#

推荐使用通用翻译请求接口。

POST /api/translate/requests

Body：

item 与 items 互斥。kind 只支持 release_summary、release_smart、release_detail、notification；target_lang 只支持 zh-CN。

TranslationRequestItemInput：

单个请求响应 TranslationRequestResponse：

批量提交响应：

结果查询：

PublicTranslationResultItem 字段：producer_ref、entity_id、kind、variant、status、title_zh、summary_md、body_md、error、work_item_id、batch_id、error_code、error_summary、error_detail。

旧版快捷接口仍可调用：

TranslateResponse 字段：lang、status、title、summary。TranslateBatchResponse 字段：items；每个 item 包含 id、lang、status、title、summary、error。

通用字段#

RepoVisual：

TranslatedItem 与 SmartItem：

ReleaseReactions：

错误码#

错误响应通常包含 code 与 message。常见状态：