§ API 指引

使用概述

开放平台以标准 HTTP 接口对外提供能力。所有业务端点均在统一基址下，使用 client_credentials 两步鉴权，无需安装 SDK。

灵犀光年开放平台提供标准的 HTTP API，覆盖量表、认知评估、认知训练三类临床级能力。典型用法：发现机构已授权的能力 → 为终端用户创建一次执行 → 签发免登作答入口 → 轮询完成后获取 PII-safe 报告。完整端点契约以控制台内「API 文档」为准。

§ 1

API 端点

ENDPOINT

开放平台业务端点的统一基址如下，下文所有路径均相对此基址：

https://api.lingxiguangnian.com/api/open/v1

调用前提：需先在控制台「密钥申请」创建应用、勾选所需 scope，并经渠道审核通过，获取 app_key 与 api_secret（secret 仅在创建时展示一次）。

§ 2

身份验证

AUTHENTICATION

鉴权分两步。第一步用 api_secret 换取短期 access_token（有效 2 小时）；此后所有业务端点只认 access_token。

换 token 时凭据放在请求头（x-app-id + Authorization: Bearer <api_secret>），业务端点则携带 access_token：

Authorization: Bearer <access_token>

api_secret 只在服务端用于换 token，绝不进入前端、作答页面、URL、查询参数或日志；误用 api_secret 直连业务端点会返回 401。access_token 临近过期前再换取，服务端缓存复用。

§ 3

权限 Scope

SCOPE

应用按需申请 scope，实际授予为 申请 ∩ 渠道允许；token 仅携带已授予的 scope，端点超出授予范围返回 403。

Scope	说明
`capabilities:read`	查询本机构可调用能力目录。
`executions:read`	查询执行记录。
`executions:write`	创建执行。
`reports:read`	读报告状态 / 签发报告免登 token。
`runtime:launch:write`	签发免登 runtime launch token（终端用户作答）。
`usage:read`	读侧用量对账。
`webhook:manage`	自管理 webhook 订阅 + 查事件投递。

§ 4

接入流程

QUICKSTART

一次完整的「能力发现 → 创建执行 → 免登作答 → 获取报告」接入，按以下七步推进：

1创建应用 + 获取凭据
在控制台「密钥申请」创建 APP、勾选申请 scope；渠道审核通过后签发 api_secret（仅展示一次）。
2服务端换 access_token
POST /token（x-app-id + Bearer secret，grant_type=client_credentials）→ access_token（有效 2 小时）。secret 仅此处使用。
3发现能力
GET /capabilities → 选择能力；launchable=true 的能力带 task_code + groups，可驱动终端用户免登作答。
4创建执行
POST /executions（cu_id + external_user_id + Idempotency-Key）→ execution_id，同时冻结额度。
5终端用户免登作答
POST /runtime/launch-tokens（execution_id + task_code + group）→ entry_url；将终端用户重定向至 entry_url 完成作答。
6轮询执行 + 报告状态
GET /executions/{id} 轮询至 COMPLETED；GET /executions/{id}/report 轮询至 READY。
7获取报告
POST /executions/{id}/report-access 签发报告免登 token → GET /report-access/session 取 PII-safe 报告投影。

§ 5

调用示例

EXAMPLES

下例展示鉴权两步（换 token → 用 token 查询能力目录）。点击右上角可复制代码：

QUICKSTART · token → capabilities

# 1. 服务端用 api_secret 换 access_token（secret 仅出现在这里）
curl -X POST "https://api.lingxiguangnian.com/api/open/v1/token" \
  -H "x-app-id: app_xxxxxxxx" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "client_credentials" }'

# 响应
# {
#   "success": true,
#   "data": {
#     "access_token": "oat_xxxxxxxxxxxxxxxxxxxxxxxx",
#     "token_type": "Bearer",
#     "expires_in": 7200,
#     "scope": "capabilities:read executions:write reports:read runtime:launch:write"
#   }
# }

# 2. 用 access_token（不是 secret）查询能力目录
curl "https://api.lingxiguangnian.com/api/open/v1/capabilities" \
  -H "Authorization: Bearer oat_xxxxxxxxxxxxxxxxxxxxxxxx"

创建执行、签发免登入口、获取报告等完整端点契约（请求/响应字段、错误码、幂等与限流规则），以登录控制台后的「API 文档」为准。