# REST API

Source: https://docs.rooquiz.com/ko/integrations/rest-api

> 팀의 퀴즈 정의(제목, 필드, 설정, 리포트 구성)와 제출 내역을 JSON으로 반환하는 작은 읽기 전용 REST API입니다. 스크립트, Zapier·Make·n8n 자동화, 자체 대시보드에서 활용할 수 있으며 API 키 발급, 인증 방식, 엔드포인트와 매개변수, 오류 코드, 요청 속도 제한을 설명합니다.

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

<Callout type="info">
  REST API는 **계정 단위**로, 개별 구성원이 아니라 팀으로 인증합니다. 자연어로 퀴즈를 다루는 **AI 클라이언트**를 원한다면 [MCP 연동](https://docs.rooquiz.com/ko/integrations/mcp)을 참고하세요.
</Callout>

## 동작 방식

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

## API 키 발급

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

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

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

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

## 인증

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

```bash
Authorization: Bearer rqp_acct_xxx...
```

<Callout type="info">
  개인 MCP 토큰(`rqp_live_`)은 REST API에서 **동작하지 않으며** `401`을 반환합니다. 계정 API 키(`rqp_acct_`)를 사용하세요.
</Callout>

## 엔드포인트

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

### OpenAPI 명세

모든 엔드포인트를 기계가 읽을 수 있게 기술한 전체 문서가 **OpenAPI 3.1** 형식으로 다음 주소에 공개되어 있습니다.

```bash
GET /api/v1/openapi.json
```

API 키가 필요 없고 비밀 정보도 들어 있지 않으므로 Postman, Insomnia, 클라이언트 생성기에 바로 불러올 수 있습니다. 팀 소유자는 **API 키** 페이지에서 **API 디버거 열기**를 클릭해 브라우저에서 엔드포인트를 직접 시험해 볼 수도 있습니다.

### 퀴즈 목록

```bash
GET /api/v1/forms
```

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

| 쿼리 매개변수         | 유형     | 기본값  | 설명                                                          |
| --------------- | ------ | ---- | ----------------------------------------------------------- |
| `scene`         | string | —    | 시나리오로 필터링: `knowledge_quiz`, `scored_quiz`, `outcome_quiz`. |
| `titleContains` | string | —    | 제목 유사 검색.                                                   |
| `limit`         | number | `20` | 페이지당 항목 수(최대 `100`).                                        |
| `page`          | number | `1`  | 페이지 번호.                                                     |

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

```json
{
  "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"
    }
  ]
}
```

### 퀴즈 조회

```bash
GET /api/v1/forms/{id}
```

퀴즈 하나의 정의를 반환합니다.

| 쿼리 매개변수         | 유형      | 기본값    | 설명                                                               |
| --------------- | ------- | ------ | ---------------------------------------------------------------- |
| `includeFields` | boolean | `true` | `fields[]` 배열(문항 / 페이지 나누기)을 포함합니다. 큰 퀴즈에서 생략하려면 `false`를 전달하세요. |
| `includeReport` | boolean | `true` | 리포트 / 차원 분석 구성을 포함합니다.                                           |

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

```json
{
  "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 동기화, 맞춤 대시보드, 자동화에 적합합니다.

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

### 제출 내역 목록

```bash
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`  | 페이지 번호.                                                 |

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

```json
{
  "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": "lead@example.com", "name": "Jane", "customData": null
      },
      "metadata": {
        "utmSource": "newsletter", "utmMedium": "email",
        "utmCampaign": null, "utmTerm": null, "utmContent": null,
        "referrer": "https://..."
      },
      "data": { "q_email": "lead@example.com", "q_rating": 5 },
      "result": {
        "status": "completed", "score": 2, "maxScore": 4,
        "level": "Good", "outcomeCode": null, "outcomeName": null
      }
    }
  ]
}
```

`data`는 각 퀴즈 필드의 `code`를 키로 사용합니다(퀴즈 엔드포인트에서 퀴즈의 `fields[]` 참고). 익명 제출이면 `examinee`는 `null`입니다. `result`는 간단한 요약이며, 전체 리포트는 상세 엔드포인트에서 확인합니다.

### 제출 내역 조회

```bash
GET /api/v1/records/{id}
```

제출 하나를 전체 리포트 결과(`reportResult`) 및 `metadata.ip` / `metadata.userAgent`와 함께 반환합니다.

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

```json
{
  "id": "...",
  "serialNumber": 11,
  "formId": "d983d8d9-...",
  "shareToken": "v2hrpv6d",
  "reportUrl": "https://your-cairo-domain/a/md8682rx/records/v2hrpv6d",
  "submittedAt": "...",
  "updatedAt": "...",
  "examinee": { "id": "...", "email": "lead@example.com", "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 }
  }
}
```

## 오류

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

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

## 요청 속도 제한

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