API 개요

이 플러그인의 설치 단계와 전체 markdown 가이드가 포함된 설정 프롬프트를 복사하세요.

Capgo cloud의 API 공개 API 문서입니다. API를 사용하면 조직, 디바이스, 채널, 번들을 포함한 Capgo 리소스를 프로그래밍 방식으로 관리할 수 있습니다. 이 API는 RESTful 방식으로 설계되었으며 표준 HTTP 메서드를 사용합니다.

인증

모든 API 엔드포인트는 인증이 필요합니다. 요청을 인증하려면 API 키를 x-api-key 헤더에 추가하거나, Authorization: Bearer YOUR_API_KEY.

예시:

curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/

API 키 가져오기 Capgo 대시보드에서 API 키를 생성하세요

이 authorization 헤더에 raw 키를(prefix 없이) 사용하는 방식은 기존 통합을 위해 여전히 지원되지만, Bearer 헤더에 x-api-key 보안 해시 키를 포함한 모든 키 유형에 권장되는 헤더입니다.

AI 에이전트 및 기타 OAuth 클라이언트는 OAuth 2.0(PKCE 및 dynamic client registration을 통한 authorization code)을 통해 키를 받을 수 있습니다. 발행자는 https://capgo.app, 메타데이터 위치: https://capgo.app/.well-known/oauth-authorization-server. 사용자가 권한을 부여할 조직을 선택하면, 액세스 토큰은 Bearer 토큰으로 전송되는 Capgo API 키입니다.

버전 관리

API은 날짜별로 버전이 관리됩니다. 버전을 고정하려면 다음 capgo_api 요청 헤더를 사용하세요:

curl -H "x-api-key: YOUR_API_KEY" -H "capgo_api: 2025-10-01" https://api.capgo.app/organization/

헤더가 없으면 기본 버전이 적용되며, 현재 기본 버전은 2025-10-01. 버전 내 변경 사항은 추가 방식(additive)입니다: 새 엔드포인트, 새 선택적 파라미터, 새 응답 필드. Breaking change는 새 날짜 버전으로 배포되며, 이전 날짜에 고정된 클라이언트는 기존 동작을 유지합니다. 알 수 없거나 잘못된 형식의 버전은 400 unsupported_capgo_api_version 또는 400 invalid_capgo_api_version.

작업(operation)이나 필드를 삭제하는 것은 breaking change이므로 새 날짜 버전에서만 이루어집니다. 현재 deprecated된 항목은 없습니다. 향후 deprecated되는 항목이 생기면 해당 작업에 표시됩니다. deprecated: true 안에 OpenAPI 명세, 응답에는 다음이 포함됩니다: Deprecation 헤더 (RFC 9745) 및 Sunset 헤더 (RFC 8594)가 포함되며, 기존 동작의 종료 날짜가 명시됩니다. 변경 사항은 릴리스 노트.

Rate Limiting

API는 공정한 사용을 보장하기 위해 rate limiting을 구현합니다. 현재 제한 사항은 다음과 같습니다:

API 키당 분당 2,000회 요청
bundle upload 라우트에서 API 키당 분당 20,000회 요청
15분 내 IP 주소당 잘못된 API 키가 20개 확인되면 해당 IP는 15분간 차단됩니다

모든 응답은 다음을 통해 할당량을 보고합니다: RateLimit-Policy 및 RateLimit 헤더 (IETF 초안):

RateLimit-Policy: "apikey";q=2000;w=60
RateLimit: "apikey";r=1995;t=42

q 는 할당량, w 는 초 단위 윈도우, r 는 남은 요청 수이고, t 는 윈도우가 초기화될 때까지 남은 초입니다. 제한을 초과하면 429 (Too Many Requests) 응답과 함께 Retry-After 초 단위 헤더입니다.

디바이스 채널 변경됨

Device channel changes는 API 플러그인을 사용하며, 체험판을 포함한 모든 플랜에 적용되는 별도의 어뷰징 방지 제한 사항이 있습니다:

디바이스는 각 채널 작업당 초당 최대 5회까지 요청할 수 있습니다(set, get, delete, 또는 list). 이 제한은 앱, 디바이스 및 작업 단위로 적용됩니다.
60초 이내에 동일한 디바이스를 동일한 채널로 두 번 이상 설정하려고 하면 429 응답이 반환됩니다. 초당 제한이 초기화된 후에는 다른 채널로 전환할 수 있습니다.
각 앱 및 IP 주소에는 분당 1,000회의 채널 요청 제한이 추가로 적용됩니다.

이 제한은 계정 전체에 적용되지 않습니다. 채널 스위처가 최근에 선택한 채널로 다시 돌아가야 하는 경우, 429 응답에 포함된 retryAfterSeconds 시간만큼 기다린 후 다시 시도하세요.

응답 형식

모든 응답은 JSON 형식입니다. 성공 응답에는 보통 data 객체 또는 status 필드가 포함됩니다. 에러 응답에는 기계가 읽을 수 있는 error code, 사람이 읽을 수 있는 메시지 message, 그리고 선택적 moreInfo 세부 정보가 포함됩니다.

성공 응답 예시:

{
  "status": "ok",
  "data": { ... }
}

에러 응답 예시:

{
  "error": "invalid_apikey",
  "message": "Invalid apikey",
  "moreInfo": {}
}

사용 가능한 엔드포인트

조직 조직 생성 및 관리, 설정 업데이트, 조직 수준 구성 관리

API 키 Capgo API에 안전하게 액세스하기 위한 API 키 생성, 목록 조회 및 취소

멤버 조직 멤버, 역할 및 권한 관리

통계 앱 사용량, 스토리지 및 대역폭 사용량에 대한 상세 분석 확인

채널 앱 업데이트 채널, 번들(버전) 및 업데이트 정책 제어

디바이스 번들(버전) 및 채널 할당을 포함해 앱을 실행 중인 디바이스를 추적하고 관리합니다.

번들 앱 번들 업로드, 목록 조회, 번들(버전) 관리를 포함해 앱 번들을 처리합니다.

모범 사례

에러 핸들링: 항상 에러 응답을 확인하고 적절히 처리하세요.
속도 제한: 속도 제한에 도달하면 exponential backoff를 구현하세요.
캐싱: API 호출을 줄이려면 필요할 때 응답을 캐시하세요.
버전 관리changelog를 통해 API 변경 사항을 확인하세요

API Overview에서 계속하기

사용 중인 경우 API 개요 인증 및 계정 흐름을 계획하려면, 이를 다음 항목과 연결하세요 @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 사항, @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 사항, @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric의 구현 세부 사항은 2단계 인증 2단계 인증의 구현 세부 사항은 SSO (기업용) SSO (Enterprise)의 구현 세부 사항은