수집과 API
HTTP API
자격증명 종류, 공개 HTTP API 묶음, 요청 한도, OpenAPI 문서를 정리합니다.
리옵트 데이터의 기능은 SDK와 CLI 없이 HTTP로도 쓸 수 있습니다.
요청과 응답의 정확한 스키마는 /openapi.json이 기준입니다. 이 문서는 어떤 자격증명으로 무엇을 할 수 있는지만 정리합니다.
자격증명
엔드포인트마다 받는 자격증명이 다릅니다. 자격증명 하나로 다른 일까지 할 수 없도록 나눠 두었습니다.
| 자격증명 | 전달 방식 | 할 수 있는 일 |
|---|---|---|
| write key | reopt-write-key 헤더 | 브라우저 수집, 세션 리플레이 수집 |
| client id + client secret | reopt-client-id, reopt-client-secret 헤더 | 서버 수집, 분석 조회 |
| 조직 키 | reopt-org-key 헤더 | 조직 안의 프로젝트, 카탈로그, 에러 규칙, 알림, 소스맵 관리 |
- write key는 브라우저 번들에 들어가는 공개 값입니다. 분석 조회에는 쓸 수 없습니다.
- client secret과 조직 키는 서버와 CI에서만 쓰세요. 값은 발급될 때 한 번만 보이고, 잃어버리면 다시 발급(회전)해야 합니다.
- 브라우저용 write key는 프로젝트 홈의 SDK Integration에서 확인합니다.
- 서버용 client ID와 secret은 콘솔에서 프로젝트를 만든 직후의 창에 한 번 표시됩니다. 자세한 내용은 조직과 프로젝트를 보세요.
- 조직 키는 콘솔에서 발급하지 않습니다. 필요하면 문의 창구로 요청하세요.
수집
| 엔드포인트 | 자격증명 | 내용 |
|---|---|---|
POST /api/track | write key 또는 client id+secret | 이벤트 수집 |
요청 형식, 응답, 오류 코드는 데이터 수집과 거버넌스에 있습니다.
분석 조회
서버 자격증명(client id + secret)으로 분석 결과를 읽습니다. 자격증명이 속한 프로젝트만 읽을 수 있습니다.
/api/v1/query/*와 /api/v1/segments/preview는 POST이고, 세그먼트 목록과 단건 조회는 GET입니다.
| 엔드포인트 | 내용 |
|---|---|
/api/v1/query/events/catalog | 이벤트 목록과 수신 현황 |
/api/v1/query/events/timeseries | 이벤트 수 시계열 |
/api/v1/query/traffic/overview, /api/v1/query/traffic/sources | 방문·세션 요약과 유입 소스 |
/api/v1/query/funnel | 퍼널 전환 |
/api/v1/query/retention | 리텐션 |
/api/v1/segments, /api/v1/segments/{id}, /api/v1/segments/preview | 저장된 세그먼트 읽기와 인원 미리보기 |
- 다른 프로젝트 id를 보내면
403 project_scope_mismatch가 돌아옵니다. - 삭제 중인 프로젝트는
410 project_purging으로 응답합니다. /api/v1/query/*의 계산 결과는 5분 동안 캐시됩니다. 같은 요청을 반복해도 그동안은 같은 답이 돌아옵니다. 요청에Cache-Control: no-cache를 보내면 캐시를 건너뜁니다. 세그먼트 API는 캐시하지 않습니다.- 세그먼트 API는 읽기 전용입니다. 세그먼트는 콘솔에서 만듭니다.
CLI의 reopt-data query와 reopt-data segment가 같은 API를 씁니다. CLI 사용하기를 보세요.
프로젝트 설정을 코드로 관리하기
조직 키로 프로젝트와 그 설정을 다룹니다.
| 경로 | 내용 |
|---|---|
/api/v1/projects, /api/v1/projects/{id} | 프로젝트 생성·목록·조회·설정 변경·삭제 |
/api/v1/projects/{id}/clients/{clientId}/rotate | 서버 client secret 회전 |
/api/v1/projects/{id}/events, …/properties | 이벤트·속성 카탈로그 읽기와 배치 쓰기 |
/api/v1/projects/{id}/error-rules, …/alerts, …/definition | 에러 규칙, 알림, 프로젝트 정의 |
/api/v1/projects/{id}/symbol-sets | 소스맵 조회, 업로드, 삭제 |
- 카탈로그 배치 쓰기는
expectedUpdatedAt으로 동시 수정을 감지합니다. 한 건이라도 충돌하면 배치 전체가409로 거절되고 아무것도 적용되지 않습니다. - 소스맵 엔드포인트는 조직 키를
reopt-org-key가 아니라Authorization: Bearer로 받습니다. 업로드는action=start로 올릴 대상을 정하고action=finish로 마무리하는 두 단계입니다. 한 요청에 100개까지, 맵 하나는 50MB까지 받습니다.
이 API를 직접 부르기보다 CLI로 쓰는 편이 쉽습니다. CLI 사용하기와 프로젝트를 코드로 관리하기를 보세요.
요청 한도
모두 1분 단위로 셉니다. 한도를 넘으면 429와 Retry-After 헤더가 돌아옵니다.
| 대상 | 기준 | 분당 한도 |
|---|---|---|
POST /api/track | 프로젝트 | 1,000 |
| 분석 조회, 세그먼트 | client | 60 |
| 프로젝트·카탈로그·규칙 관리 | 조직 키 | 30 |
| 소스맵 업로드 | 조직 키 | 300 |
분당 요청 한도는 월 데이터 포인트 한도와 별개입니다. 데이터 포인트는 비용과 보존 정책을 보세요.
공통 규칙
- 수집, 분석 조회, 프로젝트 관리 API의 오류 본문에는
code가 있습니다.code로 분기하세요. 사람이 읽는 문구는 바뀔 수 있습니다. - 소스맵 엔드포인트의 오류와, 일치하는 경로가 없을 때의
404에는code없이error문구만 있습니다. 이때는 상태 코드로 판단하세요. /api/*아래에서 일치하는 경로가 없으면 HTML이 아니라 JSON404를 돌려줍니다.- 수집 응답에는
x-request-id헤더가 붙습니다. 문의할 때 함께 알려 주세요.
에이전트와 도구가 읽는 형식
/openapi.json: 공개 HTTP API의 OpenAPI 3.1 문서/llms.txt,/llms-full.txt: 문서 목록과 전체 본문- 문서 페이지는
Accept: text/markdown요청이나.md접미사에 Markdown으로 응답합니다.
다음 단계
- 수집 요청의 형식과 오류는 데이터 수집과 거버넌스
- 터미널과 CI에서 쓰려면 CLI 사용하기
- 수집한 데이터가 화면에 보이기까지의 흐름은 데이터가 처리되는 방식