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 金鑰 撤銷金鑰 —— 使用它的整合會立即失去存取權限。

本頁目錄