API 문서

시작하기

1. 키 발급프로젝트의 API 탭에서 OWNER가 필요한 scope를 선택해 키를 만듭니다.
2. 키 보관전체 키는 발급 직후 한 번만 표시됩니다. 서버의 secret 저장소에 보관하세요.
3. 요청 전송Authorization: Bearer srrrg_pk_... 헤더를 모든 /api/v1/** 요청에 넣습니다.

첫 요청

curl -H "Authorization: Bearer srrrg_pk_..." \
  "https://srrrg.link/api/v1/projects/{projectId}/links?limit=20"

인증과 권한

API 키는 하나의 프로젝트에 속합니다. URL의 projectId와 키의 프로젝트가 다르면 요청이 거부됩니다.

공통 규칙

Idempotency-Key

단일 링크 생성에는 권장하며, JSON batch에는 필수입니다. 같은 작업의 재시도에는 같은 값을 사용하세요.

페이지네이션

목록은 cursor와 limit를 사용합니다. 응답의 다음 cursor를 그대로 전달하세요.

날짜와 시각

날짜는 YYYY-MM-DD, 시각은 ISO 8601 UTC 형식(예: 2026-08-16T03:00:00Z)을 사용합니다.

개인정보

externalId와 UTM 값에 이메일, 이름, 전화번호 같은 개인정보를 넣지 마세요.

엔드포인트

요청·응답 필드와 전체 schema는 OpenAPI JSON이 기준입니다.

익명 링크

프로젝트 링크와 통계

캠페인

UTM 템플릿

캠페인 링크와 CSV

오류

/api/v1/**의 인증·권한·요청 제한 오류는 application/problem+json이며 응답 헤더에 X-Request-Id가 포함됩니다.

{
  "title": "Forbidden",
  "status": 403,
  "detail": "필요한 API key scope가 없습니다.",
  "code": "INSUFFICIENT_SCOPE",
  "requestId": "..."
}

익명 링크 API와 일부 통계 도메인 오류는 현재 {"code":"...","message":"..."} 형식입니다. 클라이언트는 HTTP 상태를 먼저 판단하고 code를 분기 기준으로 사용하세요.

요청 한도

초과 시 429 Too Many Requests와 Retry-After 헤더를 반환합니다.