Control API 개요

Control API의 기본 주소는 https://api.nitroship.co이며 공개 리소스 경로는 /v1/*입니다. 인증에는 Identity access JWT 또는 ntro_ API 토큰을 사용합니다. 일부 가격 조회 경로는 로그인 없이 사용할 수 있습니다. 요청과 응답의 구체적인 형태는 API 레퍼런스를 확인합니다.

공통 규칙제목 링크 복사

• 식별자: 앱·팀·사용자·배포·도메인 등의 공개 ID는 UUID를 canonical base62로 인코딩한 값입니다. 데이터베이스 UUID 문자열 대신 반환된 공개 ID를 사용합니다. 배포의 shortId는 CLI에서 조회할 수 있는 별도 값이고 {deploymentId} 경로에는 공개 ID를 사용합니다. 잘못된 ID에는 400 invalid_id가 반환됩니다.
• 페이지네이션: 앱·배포·도메인·Purge·활동 목록은 limit=1..100(기본 50), 불투명 cursor를 사용합니다. 응답의 nextCursor가 null이면 마지막 페이지입니다. 다음 페이지 요청에는 반환된 값을 그대로 전달합니다. 배포 이벤트 목록은 별도로 after/nextAfter, limit=1..1000(기본 100)을 사용합니다. 팀·토큰·청구서 목록에는 이 공통 커서 계약을 적용하지 않습니다.
• JSON 요청: 일반 JSON 입력은 Content-Type: application/json을 사용합니다. 알 수 없는 필드는 거부되며 일반 본문 최대 크기는 64 KiB입니다. 일부 엔드포인트에는 별도 제한이 있습니다.
• 오류: 일반적인 오류 응답은 {"error":{"code":"...","message":"..."}}입니다. 인증 실패는 401, 인증된 이메일이 필요한 쓰기는 403 email_verification_required, 권한이 없는 팀 리소스는 403 또는 숨겨진 404일 수 있습니다. 제한에 걸린 요청의 응답에는 재시도 시간 X-Retry-After가 포함될 수 있습니다.
• 요청 제한: Control REST 요청에는 IP별 요청 제한이 적용될 수 있으며 초과 시 429 응답을 받습니다. X-Retry-After가 있으면 해당 초 이후 다시 시도합니다. 가입·로그인·기기 승인 등 Identity 요청에는 별도의 제한이 적용됩니다.
• 요청 ID: 응답의 X-Request-Id를 문제를 보고할 때 함께 전달합니다. ntro --verbose를 사용하면 각 HTTP 응답의 request ID를 표시합니다.

Control과 Identity의 경계가 다릅니다. 사용자 가입·로그인·기기 승인은 Control API가 아닌 Identity에서 처리합니다. 인증 안내를 참고합니다.