API 개요

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

이 문서는 Capgo 클라우드의 공개 API에 대한 설명입니다. API를 사용하면 조직, 기기, 채널, 번들 등 Capgo 리소스를 프로그래매틱으로 관리할 수 있습니다. 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)을 통해 키를 받을 수 있습니다. issuer는 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. 버전 내 변경 사항은 추가적입니다: 새로운 엔드포인트, 새로운 선택 파라미터, 새로운 응답 필드입니다. 깨지는 변경 사항은 새로운 날짜 버전으로 배포되며, 이전 날짜에 고정된 클라이언트는 기존 동작을 유지합니다. 알 수 없거나 잘못된 버전은 400 unsupported_capgo_api_version 또는 400 invalid_capgo_api_version.

작업 또는 필드를 제거하는 것은 깨지는 변경 사항이므로, 새로운 날짜 버전에서만 발생합니다. 현재 비활성화된 항목은 없습니다. 비활성화될 경우, 해당 작업은 deprecated: true 플러그인의 OpenAPI 명세로 표시되고, 응답에는 Deprecation 헤더(RFC 9745)와 Sunset 헤더(RFC 8594)가 포함되며, 기존 동작이 종료되는 날짜가 명시되고, 해당 변경 사항은 릴리스 노트.

요청 제한

API은 공정한 사용을 보장하기 위해 레이트 리미팅을 구현합니다. 현재 한도는 다음과 같습니다:

API 키당 분당 2,000회 요청
번들 업로드 라우트에서 API 키당 분당 20,000회 요청
IP 주소당 15분 내 20회 잘못된 API 키 사용 시 해당 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 키 API 키 생성, 목록 조회 및 폐기하여 Capgo API에 대한 안전한 액세스 관리

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

통계 앱 사용량, 저장소, 대역폭 소비에 대한 상세 분석을 확인하세요

채널 앱 업데이트 채널, 번들(버전), 업데이트 정책을 관리하세요

기기 앱을 실행 중인 기기를 추적 및 관리하며, 번들(버전) 및 채널 할당을 처리하세요

번들 앱 번들을 처리하며, 번들(버전) 업로드, 목록 조회 및 관리를 수행하세요

모범 사례

에러 핸들링: 항상 오류 응답을 확인하고 적절히 처리하세요
요청 제한: 레이트 리밋에 걸리면 지수 백오프를 구현하세요
캐싱: 적절한 경우 응답을 캐싱해 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단계 인증(Two-factor authentication)의 구현 세부 사항은, SSO (기업용) SSO (Enterprise)의 구현 세부 사항은.

릴리스 상태, 오류 및 네이티브 빌드

트레이드오프를 평가하려면 API 모니터링 네이티브 및 업데이트 진단, 메타데이터가 포함된 로그, 라이브 릴리스 대시보드 통계, 네이티브 빌드 상태 및 로그 스냅샷을 조회합니다. 이러한 읽기 작업은 두 계정 MCP 서버 모두에서 노출됩니다.