# Devnors数据

为 AI Agent 而建的高质量数据 API：一个 API Key 调用官方权威数据，出处可回溯。
用户只需在 SDK/MCP 填入 API Key，其余由 Agent 自发现、自调用、自纠错。

## 统一数据 API（网关）
- 端点：POST https://data.devnors.com/v1/data/query
- 鉴权：Authorization: Bearer devnors_sk_...（在 /console 创建 API Key）
- 请求体：{domain, type, query, filters, top_k(1-200,默认20)}；分页用 filters.offset
- 计费：按次调用扣 units（1 元 = 50000 tokens）；per-key 限流，429 时按 Retry-After 退避
- 机器可读能力全量真源：https://data.devnors.com/capabilities.json（能调什么/字段/示例/错误码）
- 已接入官方数据源清单：https://data.devnors.com/data-sources.json

## 能力（domain/type，live=已上线，planned=规划中）
- [live] domain=legal type=case（裁判文书）：检索中国裁判文书(官方公开,出处可回溯)。自然语言 query + 可选结构化 filters。 常用 filters：cause、case_type、court_level、trial_procedure、province、city、region、case_level、year_start、year_end
- [live] domain=legal type=law_article（法律法规条文）：检索中国现行法律法规条文(回源官方语料 + 语义召回)。 常用 filters：law_name、law_level、jurisdiction_scope
- [live] domain=legal type=law_catalog（法律法规目录）：按名称/位阶/地域检索法律法规(目录级)。 常用 filters：law_name、law_level、jurisdiction_scope
- [planned] domain=content（内容）：规划中，当前不可调用
- [planned] domain=enterprise（企业）：规划中，当前不可调用
- [planned] domain=research（研究）：规划中，当前不可调用
- [planned] domain=cloud（云服务 API）：规划中，当前不可调用

## 错误码（结构化：code + retryable + next_action，响应体附带）
- 401 unauthorized（retryable=否）：提供有效的 Authorization: Bearer devnors_sk_ 密钥（在 /console 创建）
- 402 insufficient_balance（retryable=否）：余额不足;充值入口 /console（充值后可重试）
- 400 invalid_capability（retryable=否）：domain/type 无效;可用组合见 /capabilities.json
- 429 rate_limited（retryable=是）：已限流;按响应头 Retry-After 秒退避后重试
- 501 not_implemented（retryable=否）：该数据域规划中;当前可用（live）域见 /capabilities.json
- 503 unavailable（retryable=是）：上游暂不可用;可短暂退避后重试
- 502 upstream_error（retryable=是）：数据检索失败，费用已退回;可重试

## 接入
- Python SDK：pip install devnors-data
- MCP Server：pip install devnors-mcp（Claude/Cursor 一行接入）

## Datasets（公开浏览面，可收录）
- 裁判文书 (cases): https://data.devnors.com/cases — 详情 JSON https://data.devnors.com/cases/{key}.json