研究仓库

GET /api/repositories 检索列表与快照,POST /api/repositories 上传 PDF 或从 arXiv / URL 索引论文。

研究仓库是 CiteArk 的基本对象,对应一篇论文及其 Claims、实验、运行记录与证据。GET /api/repositories 提供公开列表与单个仓库快照,POST /api/repositories 用于提交新论文。

Agent 应优先使用 GET /api/v1/repositories 与 GET /api/v1/repositories/{id}。它们支持游标分页、fields、按需 include、稳定 ID 查询、ETag 重验证，并具有更小的默认响应，详见 Agent API。下文接口是旧版完整快照兼容接口。

鉴权

GET 公开,无需鉴权。
POST 需要浏览器会话或 x-api-key,且账号具备 write 权限。

GET /api/repositories

请求

参数	类型	必填	说明
owner	string	否	仓库所有者。与 slug 同时提供时返回单个仓库快照
slug	string	否	仓库名。与 owner 同时提供时返回单个仓库快照

不带参数时返回公开仓库列表,按 updatedAt 倒序,最多 50 条,没有分页参数。

示例

# 公开仓库列表
curl https://citeark.com/api/repositories

# 单个仓库快照
curl "https://citeark.com/api/repositories?owner=<所有者>&slug=<仓库名>"

响应

列表返回 { "repositories": [...] },每个条目为 RepositorySummary:

字段	类型	说明
id	string	仓库 ID
owner	string	所有者命名空间
slug	string	仓库名
title	string	论文标题
description	string	简介
topics	string[]	主题标签
headId	string	当前版本 commit 摘要(`sha256:` 前缀)
claimCount	number	Claim 总数
verifiedClaimCount	number	已验证 Claim 数
runCount	number	运行记录数
forkCount	number	Fork 数
updatedAt	string	最近更新时间(ISO 8601)

单个仓库返回 { "repository": { ... } },为完整快照(顶层结构见核心概念)。私有仓库仅 owner / 组织成员可读,其他人得到 404 {"error": "论文仓库不存在"};非 owner 读取公开仓库时得到脱敏投影。

POST /api/repositories

按 Content-Type 分为两种模式。

模式一:JSON 索引(application/json,推荐 Agent)

提交一个 arXiv 链接/编号或 HTTPS PDF 直链,由服务端完成抓取与索引,无需上传文件。

参数	类型	必填	说明
input	string	是	1–300 字符。arXiv 链接/编号(如 `2401.12345`、`https://arxiv.org/abs/...`、`https://arxiv.org/pdf/...`),或 HTTPS PDF 直链
title	string	否	3–240 字符,仅 PDF 直链模式有意义(缺省取文件名)
owner	string	否	目标命名空间:个人或有权限的组织 slug,须匹配 `^[a-z0-9-]+$`,≤64 字符
slug	string	否	≤96 字符,缺省时自动派生
githubUrl	string	否	必须是 github.com 上的仓库 HTTPS 链接
visibility	string	否	`public` / `private`,默认 `public`

行为:arXiv 模式下服务端抓取标题、摘要、许可并下载 PDF;License Gate 为 green 时把 PDF 存入对象存储,否则只保存元数据并链接原始来源。创建后自动进入处理流水线,可用处理状态轮询进度。

模式二:multipart 直传(multipart/form-data)

直接上传论文 PDF 文件。

字段	类型	必填	说明
paper	file	是	PDF 文件,≤25 MB,服务端校验 `%PDF` 头
title	string	是	3–240 字符
slug	string	是	≤96 字符,须匹配 `^[a-z0-9-]+$`
owner	string	否	目标命名空间:个人或有权限的组织 slug,≤64 字符
description	string	否	≤1000 字符
githubUrl	string	否	必须是 github.com 上的仓库 HTTPS 链接
sourceUrl	string	否	原始来源 HTTPS 地址
paperLicense	string	否	枚举:`CC0-1.0`、`CC-BY-4.0`、`CC-BY-SA-4.0`、`MIT`、`Apache-2.0`、`arXiv-default`、`publisher-restricted`、`unknown`,默认 `unknown`
codeLicense	string	否	枚举:`MIT`、`Apache-2.0`、`BSD-2-Clause`、`BSD-3-Clause`、`ISC`、`MPL-2.0`、`GPL-3.0-only`、`no-code`、`unknown`,默认 `unknown`
submitterAttested	string	是	必须为字符串 `"true"`,声明你有权提交该论文
visibility	string	否	`public` / `private`,默认 `public`

示例

# 模式一:从 arXiv 索引
curl -X POST https://citeark.com/api/repositories \
  -H "x-api-key: $CITEARK_API_KEY" \
  -H "content-type: application/json" \
  -d '{"input": "https://arxiv.org/abs/2401.00001"}'

# 模式二:上传 PDF
curl -X POST https://citeark.com/api/repositories \
  -H "x-api-key: $CITEARK_API_KEY" \
  -F "paper=@paper.pdf" \
  -F "title=论文标题" \
  -F "slug=your-paper-slug" \
  -F "submitterAttested=true"

响应

成功返回 201:

{
  "repository": { "id": "…", "owner": "<所有者>", "slug": "<仓库名>", "title": "…" },
  "url": "/r/<所有者>/<仓库名>"
}

错误

状态码	含义
400	输入无法识别或字段校验失败
404	arXiv 上未找到这篇论文
409	这篇论文已经在 CiteArk 上了(响应带 `url` 字段指向已有页面)
413	PDF 超过 25 MB
429	超出限流或月度额度

限流与备注

POST 限流为每账号 5 次/小时。
上传与索引另受每账号每月 25 次上传额度约束,耗尽时返回 429 并携带 X-Quota-* 响应头。

本页目录