REST API

查询参数	类型	默认	说明
`scene`	string	—	按场景过滤：`knowledge_quiz`、`random_knowledge_quiz`、`scored_quiz`、`outcome_quiz`。
`titleContains`	string	—	标题模糊匹配。
`limit`	number	`20`	每页条数（最大 `100`）。
`page`	number	`1`	页码。

curl -H "Authorization: Bearer rqp_acct_xxx..." \
  "https://your-domain/api/v1/forms?scene=knowledge_quiz&limit=20"

{
  "totalDocs": 12,
  "page": 1,
  "limit": 20,
  "items": [
    {
      "id": "d983d8d9-...",
      "title": "性格测试",
      "scene": "outcome_quiz",
      "language": "zh_CN",
      "publicToken": "h7sbps67",
      "shareUrl": "https://your-cairo-domain/a/h7sbps67",
      "localization": null,
      "isActive": true,
      "createdAt": "2026-06-18T11:35:11.468Z",
      "updatedAt": "2026-06-18T12:59:42.649Z"
    }
  ]
}

获取单个表单

GET /api/v1/forms/{id}

返回单个表单的定义。

查询参数	类型	默认	说明
`includeFields`	boolean	`true`	是否包含 `fields[]`（题目 / 分页符）。大表单可传 `false` 跳过。
`includeReport`	boolean	`true`	是否包含报告 / 维度分析配置。

curl -H "Authorization: Bearer rqp_acct_xxx..." \
  "https://your-domain/api/v1/forms/d983d8d9-..."

{
  "id": "d983d8d9-...",
  "title": "性格测试",
  "scene": "outcome_quiz",
  "language": "zh_CN",
  "description": null,
  "isActive": true,
  "publicToken": "h7sbps67",
  "shareUrl": "https://your-cairo-domain/a/h7sbps67",
  "layout": "card",
  "localization": null,
  "systemText": null,
  "createdAt": "2026-06-18T11:35:11.468Z",
  "updatedAt": "2026-06-18T12:59:42.649Z",
  "fields": [ /* 题目与分页符 */ ],
  "report": { /* 报告 / 维度配置 */ }
}

提交记录

读取团队表单收集到的作答 —— 线索、答案、得分、报告结果与 UTM 归因。适合 CRM 同步、自建看板、自动化。

提交记录包含作答者 PII（邮箱、姓名、IP），请妥善处理与存储。

列出提交记录

GET /api/v1/records

按创建时间倒序列出该账号的全部提交记录。

查询参数	类型	默认	说明
`formId`	string	—	只看某个表单的提交。
`status`	string	—	报告状态：`pending`、`processing`、`completed`、`failed`。
`since`	ISO 时间	—	只看该时间（含）之后创建的提交（增量同步）。
`until`	ISO 时间	—	只看该时间（含）之前创建的提交。
`limit`	number	`20`	每页条数（最大 `100`）。
`page`	number	`1`	页码。

curl -H "Authorization: Bearer rqp_acct_xxx..." \
  "https://your-domain/api/v1/records?since=2026-06-01&limit=50"

{
  "totalDocs": 1500,
  "page": 1,
  "limit": 50,
  "items": [
    {
      "id": "...",
      "serialNumber": 11,
      "formId": "d983d8d9-...",
      "shareToken": "v2hrpv6d",
      "reportUrl": "https://your-cairo-domain/a/md8682rx/records/v2hrpv6d",
      "submittedAt": "2026-06-18T12:00:00.000Z",
      "updatedAt": "2026-06-18T12:00:05.000Z",
      "examinee": {
        "id": "...", "examineeId": "TZ4730277148",
        "email": "[email protected]", "name": "Jane", "customData": null
      },
      "metadata": {
        "utmSource": "newsletter", "utmMedium": "email",
        "utmCampaign": null, "utmTerm": null, "utmContent": null,
        "referrer": "https://..."
      },
      "data": { "q_email": "[email protected]", "q_rating": 5 },
      "result": {
        "status": "completed", "score": 2, "maxScore": 4,
        "level": "良好", "outcomeCode": null, "outcomeName": null
      }
    }
  ]
}

data 以每个表单字段的 code 为 key（可通过表单端点的 fields[] 查看）。匿名提交时 examinee 为 null。result 是紧凑摘要；完整报告在详情端点。

获取单条提交记录

GET /api/v1/records/{id}

返回单条提交，含完整报告结果 reportResult 以及 metadata.ip / metadata.userAgent。

curl -H "Authorization: Bearer rqp_acct_xxx..." \
  "https://your-domain/api/v1/records/..."

{
  "id": "...",
  "serialNumber": 11,
  "formId": "d983d8d9-...",
  "shareToken": "v2hrpv6d",
  "reportUrl": "https://your-cairo-domain/a/md8682rx/records/v2hrpv6d",
  "submittedAt": "...",
  "updatedAt": "...",
  "examinee": { "id": "...", "email": "[email protected]", "name": "Jane" },
  "metadata": { "ip": "203.0.113.4", "userAgent": "...", "utmSource": "newsletter" },
  "data": { /* 按字段 code 的作答 */ },
  "reportResult": {
    "status": "completed",
    "overallAnalysis": { "score": 2, "maxScore": 4, "level": "良好", "summary": "...", "suggestions": "..." },
    "dimensionAnalysis": { "title": "...", "radar": [], "items": [] },
    "outcome": { "code": null, "name": null, "ranking": null },
    "aiSuggestion": { "status": "completed", "content": "..." }
  }
}

错误

错误以 { "error": { "code": "...", "message": "..." } } 的形式返回。

状态码	code	场景
`401`	`unauthorized`	缺失 / 无效 / 已过期 / 已吊销的密钥（或传了非账号级令牌）。
`404`	`not_found`	表单不存在，或不属于该密钥所在团队。
`400`	`bad_request`	参数非法（例如未知的 `scene`）。
`429`	`rate_limited`	超过限流。

限流

每个密钥限制为 120 次 / 分钟，超出返回 429。不再需要时，请在 设置 → API 密钥 吊销密钥 —— 使用它的集成会立即失去访问权限。

本页目录