HJS API 文档

责任追溯协议 · 实现层服务

🔑 认证方式

所有 API 请求都需要在 Header 中携带 API Key：

X-API-Key: your-api-key-here

在开发者控制台可以生成和管理 API Key。

POST /judgments

记录一条判断事件，返回唯一的记录 ID。

请求头

Content-Type: application/json
X-API-Key: your-api-key

请求体

{
  "entity": "alice@bank.com",  // 必填，做出判断的实体
  "action": "loan_approved",   // 必填，被判断的行为
  "scope": {"amount": 100000}, // 可选，判断的作用域
  "timestamp": "2026-02-17T..." // 可选，判断时间，默认服务器时间
}

响应示例

{
  "id": "jgd_1742318412345_abc1",
  "status": "recorded",
  "protocol": "HJS/1.0",
  "timestamp": "2026-02-17T09:30:15.123Z"
}

GET /judgments/{id}

根据 ID 查询完整的判断记录。

请求头

X-API-Key: your-api-key

响应示例

{
  "id": "jgd_1742318412345_abc1",
  "entity": "alice@bank.com",
  "action": "loan_approved",
  "scope": {"amount": 100000},
  "timestamp": "2026-02-17T09:30:15.083Z",
  "recorded_at": "2026-02-17T09:30:15.123Z",
  "ots_proof": null,
  "ots_verified": false
}

GET /judgments/{id}?format=json

下载 JSON 格式的记录文件。

请求头

X-API-Key: your-api-key

GET /judgments/{id}?format=pdf

下载带二维码的 PDF 格式记录文件，适合打印和存档。

请求头

X-API-Key: your-api-key

GET /judgments?entity=xxx&from=...&to=...&page=1&limit=20

分页查询记录列表，支持按实体和时间筛选。

请求头

X-API-Key: your-api-key

查询参数

`entity`	按实体筛选
`from`	开始时间 (ISO 8601)
`to`	结束时间 (ISO 8601)
`page`	页码，默认 1
`limit`	每页条数，默认 20，最大 100

GET /judgments?format=json&entity=...

下载筛选后的记录列表为 JSON 文件。

请求头

X-API-Key: your-api-key

GET /judgments/{id}/proof

下载 OpenTimestamps 证明文件（.ots），可用于独立验证。

请求头

X-API-Key: your-api-key

🔧 开发者密钥管理

POST /developer/keys

生成新 API 密钥

{
  "email": "user@example.com",
  "name": "production-key"
}

GET /developer/keys?email=...

查询某邮箱下的所有密钥

DELETE /developer/keys/{key}?email=...

吊销指定密钥

⚠️ 错误码

`400`	缺少必填字段
`401`	缺少或无效的 API Key
`404`	记录不存在
`429`	请求过于频繁，超出限制
`500`	服务器错误

⏱️ 速率限制

每个 API Key 每 15 分钟最多 100 次请求。

🔐 记录验证

每条记录的 OTS 证明可用以下方式验证：

# 安装 OTS 客户端
pip3 install opentimestamps-client

# 验证证明
ots verify record.json.ots

# 查看证明信息
ots info record.json.ots

首页控制台查询 GitHub