REST API

RooQuiz는 작은 읽기 전용 REST API를 제공하므로 팀의 퀴즈 데이터를 스크립트, 자동화(Zapier, Make, n8n), 또는 자체 대시보드로 가져올 수 있습니다. 제목, 필드, 설정, 리포트 구성 같은 퀴즈 정의와 각 퀴즈가 수집한 제출 내역을 일반 JSON으로 반환합니다.

REST API는 계정 단위로, 개별 구성원이 아니라 팀으로 인증합니다. 자연어로 퀴즈를 다루는 AI 클라이언트를 원한다면 MCP 연동을 참고하세요.

동작 방식

팀에 속한 계정 API 키(접두사 rqp_acct_)로 인증합니다.
키는 해당 팀의 모든 퀴즈를 읽을 수 있습니다. 특정 사람에게 묶여 있지 않으므로 구성원이 바뀌어도 계속 동작합니다.
계정 API 키는 팀 소유자만 생성, 조회, 취소할 수 있습니다.
API는 읽기 전용입니다. 퀴즈 정의와 제출 내역을 반환하지만 생성, 수정, 삭제는 할 수 없습니다.

API 키 발급

설정 → API 키(팀 소유자에게만 표시)로 이동해 "API 키 생성"을 클릭합니다.

알아보기 쉬운 이름을 지정합니다(예: Zapier - Production).
생성이 끝나면 rqp_acct_로 시작하는 평문 키가 표시됩니다.

평문 키는 단 한 번만 표시됩니다. 페이지를 떠나면 다시 확인할 수 없습니다. 바로 복사하세요. 분실했다면 키를 취소하고 새로 만들어야 합니다.

팀마다 키는 최대 10개(취소된 키 포함)까지 보유할 수 있습니다. 더 만들려면 하나를 삭제해 자리를 비우세요("취소"는 비활성화만 할 뿐 자리를 비우지 않습니다). 키는 비밀번호처럼 다루고 절대 소스 코드 저장소에 커밋하지 마세요.

인증

모든 요청에 키를 Bearer 토큰으로 보냅니다.

Authorization: Bearer rqp_acct_xxx...

개인 MCP 토큰(rqp_live_)은 REST API에서 동작하지 않으며 401을 반환합니다. 계정 API 키(rqp_acct_)를 사용하세요.

엔드포인트

기본 URL은 https://your-domain/api/v1 형태입니다.

퀴즈 목록

GET /api/v1/forms

키가 속한 팀의 모든 퀴즈를 최신순으로 나열합니다.

쿼리 매개변수	유형	기본값	설명
`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": "Personality Quiz",
      "scene": "outcome_quiz",
      "language": "en_US",
      "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": "Personality Quiz",
  "scene": "outcome_quiz",
  "language": "en_US",
  "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": [ /* questions & page breaks */ ],
  "report": { /* report / dimension config */ }
}

제출 내역

팀의 퀴즈가 수집한 응답(리드, 답변, 점수, 리포트 결과, UTM 유입 경로)을 읽습니다. CRM 동기화, 맞춤 대시보드, 자동화에 적합합니다.

제출 내역에는 응답자의 개인 식별 정보(이메일, 이름, IP)가 포함됩니다. 책임감 있게 다루고 보관하세요.

제출 내역 목록

GET /api/v1/records

팀 전체의 제출 내역을 최신순으로 나열합니다.

쿼리 매개변수	유형	기본값	설명
`formId`	string	—	이 퀴즈의 제출 내역만.
`status`	string	—	리포트 상태: `pending`, `processing`, `completed`, `failed`.
`since`	ISO date	—	이 시각 이후(포함)에 생성된 제출 내역만(증분 동기화).
`until`	ISO date	—	이 시각 이전(포함)에 생성된 제출 내역만.
`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": "Good", "outcomeCode": null, "outcomeName": null
      }
    }
  ]
}

data는 각 퀴즈 필드의 code를 키로 사용합니다(퀴즈 엔드포인트에서 퀴즈의 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": { /* answers keyed by field code */ },
  "reportResult": {
    "status": "completed",
    "overallAnalysis": { "score": 2, "maxScore": 4, "level": "Good", "summary": "...", "suggestions": "..." },
    "dimensionAnalysis": { "title": "...", "radar": [], "items": [] },
    "outcome": { "code": null, "name": null, "ranking": null },
    "aiSuggestion": { "status": "completed", "content": "..." }
  }
}

오류

오류는 { "error": { "code": "...", "message": "..." } } 형태의 JSON 본문을 반환합니다.

상태	코드	발생 조건
`401`	`unauthorized`	키가 없거나, 유효하지 않거나, 만료되었거나, 취소된 경우(또는 계정 토큰이 아닌 경우).
`404`	`not_found`	퀴즈가 존재하지 않거나 이 키의 팀에 속하지 않는 경우.
`400`	`bad_request`	잘못된 매개변수(예: 알 수 없는 `scene`).
`429`	`rate_limited`	요청 속도 제한을 초과한 경우.

요청 속도 제한

키마다 분당 120회 요청으로 제한되며, 초과하면 429를 반환합니다. 더 이상 필요 없는 키는 설정 → API 키에서 취소하세요. 해당 키를 사용하던 모든 연동은 즉시 접근 권한을 잃습니다.

이 페이지의 내용