统一数据查询 API 接入
一个 API Key，统一入口 POST /v1/data/query 调用所有数据域。填入 Key 后，Agent 可读机器可读能力清单自行编排调用。
1. 鉴权
在 控制台 · API 令牌 创建 Key（形如 devnors_sk_live_…，仅展示一次），每次请求在请求头带上：
账号与余额沿用 Devnors 主站；一把 Key 即可调用所有已开放数据域。
2. 统一查询接口
POST https://data.devnors.com/v1/data/query，请求体与响应均为 JSON。
请求示例
curl -X POST https://data.devnors.com/v1/data/query \
-H "Authorization: Bearer devnors_sk_live_xxxx" \
-H "Content-Type: application/json" \
-d '{"domain":"legal","type":"case","query":"民间借贷 利息","top_k":20}'请求体字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| domain | string | 是 | 数据域，如 legal |
| type | string | 是 | 数据类型，如 case / law_article / law_catalog |
| query | string | 否 | 自然语言检索词 |
| filters | object | 否 | 结构化过滤（见第 3 节）；翻页用 filters.offset（整数，默认 0） |
| top_k | integer | 否 | 返回条数，1–200，默认 20 |
响应示例（200）
{
"domain": "legal",
"type": "case",
"query": "民间借贷 利息",
"total": 20, // 本页返回条数
"total_hits": 3841, // 命中总数（用于翻页）
"units": 300, // 本次消耗 tokens
"request_id": "8f2c…e1",
"status": "ok",
"hits": [ { "case_no": "（2021）京0105民初12345号", "court_name": "北京市朝阳区人民法院", "…": "…" } ]
}响应头附带 X-Request-Id（与 request_id 一致），报障对账用。
3. 数据域与类型
| domain | type | 说明 | 常用 filters | 示例 query | 状态 |
|---|---|---|---|---|---|
| legal | case | 检索中国裁判文书(官方公开,出处可回溯)。自然语言 query + 可选结构化 filters。 | cause case_type court_level trial_procedure province city region case_level year_start year_end |
民间借贷 利息 | 已上线 |
| legal | law_article | 检索中国现行法律法规条文(回源官方语料 + 语义召回)。 | law_name law_level jurisdiction_scope |
合同解除 违约金 | 已上线 |
| legal | law_catalog | 按名称/位阶/地域检索法律法规(目录级)。 | law_name law_level jurisdiction_scope |
劳动合同法 | 已上线 |
| content / enterprise / research / cloud | — | 内容 / 企业 / 研究 / 云服务 API等更多数据域 | — | — | 规划中 |
规划中的域调用返回 501 且不计费。新域上线后同一个 API Key 直接可用，无需换密钥。
4. 返回字段
每个 hit 的结构随 type 而定，字段与 capabilities.json 完全一致：
legal/case · 裁判文书
| 字段 | 说明 |
|---|---|
| case_no | 案号 |
| court_name | 审理法院 |
| cause_of_action | 案由 |
| case_type | 案件类型 |
| judgment_date | 裁判日期 |
| judgment_result | 裁判结果 |
| summary | 案件摘要 |
| applied_laws | 引用法条(列表) |
| source | 数据来源标识 |
| score | 召回相关度 |
legal/law_article · 法律法规条文
| 字段 | 说明 |
|---|---|
| law_name | 所属法律名称 |
| article_no | 条号 |
| content | 条文正文 |
| law_level | 效力位阶 |
| source_url | 官方出处(可回溯) |
legal/law_catalog · 法律法规目录
| 字段 | 说明 |
|---|---|
| law_name | 所属法律名称 |
| article_no | 条号 |
| content | 条文正文 |
| law_level | 效力位阶 |
| source_url | 官方出处(可回溯) |
5. 错误码
错误响应保留 detail（文本），并附结构化 code / retryable / next_action / docs_url，供程序自纠。
| HTTP | code | 可重试 | 建议动作 |
|---|---|---|---|
| 401 | unauthorized | 否 | 提供有效的 Authorization: Bearer devnors_sk_ 密钥（在 /console 创建） |
| 402 | insufficient_balance | 否 | 余额不足;充值入口 /console（充值后可重试） |
| 400 | invalid_capability | 否 | domain/type 无效;可用组合见 /capabilities.json |
| 429 | rate_limited | 是 | 已限流;按响应头 Retry-After 秒退避后重试 |
| 501 | not_implemented | 否 | 该数据域规划中;当前可用（live）域见 /capabilities.json |
| 503 | unavailable | 是 | 上游暂不可用;可短暂退避后重试 |
| 502 | upstream_error | 是 | 数据检索失败，费用已退回;可重试 |
取数失败会自动幂等退款（费用已退回），可安全重试。可重试错误（429/5xx）建议按 Retry-After 或指数退避重试。
6. SDK 与 MCP
除直接 HTTP 调用外，官方提供 Python SDK 与 MCP Server，二者都读环境变量 DEVNORS_API_KEY。
Python SDK · pip install devnors-data
from devnors_data import DevnorsData
client = DevnorsData() # 读取环境变量 DEVNORS_API_KEY
res = client.legal_cases("民间借贷 利息", top_k=20)
for hit in res["hits"]:
print(hit["case_no"], hit["court_name"])
# 自动翻页（按 total_hits 判尽头）
for hit in client.paginate("legal", "case", "借款合同", page_size=50, max_items=500):
...异步用 AsyncDevnorsData（方法带 await）；429/5xx 自动有界退避重试，非重试错误（400/401/402/501）直接抛出。
MCP Server（Claude Desktop / Cursor）· pip install devnors-mcp
{
"mcpServers": {
"devnors-data": {
"command": "devnors-mcp",
"env": { "DEVNORS_API_KEY": "devnors_sk_live_把这里换成你的Key" }
}
}
}配置后，支持 MCP 的 AI 客户端即可直接调用统一数据查询能力。
7. 机器可读 / 面向 Agent
供程序与 AI Agent 自发现（无需人读本页）：
/capabilities.json— 能力清单单一真源（domain/type/filters/字段/示例/错误码）/openapi.json— OpenAPI schema/llms.txt— 面向大模型的站点清单