공개 API 개요

CLI가 하는 일은 모두 REST API로도 할 수 있습니다. 직접 자동화를 만들거나 다른 시스템과 연결할 때 사용하세요.

첫 요청제목 링크 복사

API 주소는 https://api.nitroship.co이고, 요청에는 접속 토큰이 필요합니다. ntro token으로 받을 수 있으며, ntro_ API 토큰을 그대로 보내면 거부됩니다. 자세한 방법은 API 인증에 있습니다.

export NITROSHIP_ACCESS_TOKEN="$(ntro token)"
curl -H "Authorization: Bearer $NITROSHIP_ACCESS_TOKEN" \
  https://api.nitroship.co/v1/me

가격 조회 같은 일부 엔드포인트는 로그인 없이도 쓸 수 있습니다.

경로 구성제목 링크 복사

모든 요청은 같은 주소(https://api.nitroship.co)로 보냅니다. 경로는 영역별로 나뉩니다.

앱·사용량 경로의 요청·응답 형식은 API 레퍼런스에 있습니다.

공개 가격제목 링크 복사

GET /v1/pricing?currency=KRW는 인증 없이 호출할 수 있습니다. 1크레딧 = 1 USD(미국 달러)입니다. 사용량 단가, 포함량, 플랜의 월 크레딧, 좌석 가격, Flat Rate CDN 단계 요금은 통화와 무관한 하나의 요금 카탈로그에 정의하며 적용 시작일별로 버전을 관리합니다. 별도로 관리하는 통화별 가격 버전에는 운영자가 정한 1크레딧의 고정 가격과 직접 입력한 월 플랫폼 요금이 들어갑니다. 실시간 환율을 적용하지 않습니다.

응답의 바깥쪽 JSON 키 price_book은 의도적으로 유지합니다. 이 객체에는 요청한 통화로 계산한 가격과 크레딧 기준 필드가 함께 들어갑니다. 통화마다 별도의 카탈로그가 있다는 뜻은 아닙니다.

가격의 소수 문자열은 지수 표기를 쓰지 않으며 소수부 끝의 불필요한 0을 생략합니다. 통화가 올바르지 않으면 400, 유효한 카탈로그나 통화별 가격이 없으면 404를 반환합니다. 등록·활성화된 통화에 유효한 카탈로그와 통화별 가격이 모두 있어야 청구에 사용할 수 있습니다. 청구 주기에는 주기 시작 시점에 유효한 버전을 적용합니다. 사용 내역서 항목, 청구서 금액, budget_minor는 계속 청구 통화의 금액입니다.

운영자의 요금 관리는 GET/POST /v1/operator/pricing-catalogs와 GET/POST /v1/operator/currency-prices를 사용합니다. 관리자 토큰을 쓰는 경우에는 같은 경로의 /admin 버전을 사용합니다. 이전 운영자 요금 경로는 제거되며 호환용 별칭은 없습니다. 팀 사용량 응답에서 요금을 계산할 수 없는 경우의 사유는 no_effective_pricing입니다.

운영자가 지급한 팀 크레딧은 특정 통화에 묶이지 않으며 어떤 통화의 청구서에서도 먼저 지급한 순서대로 총액에서 차감합니다(선입선출, FIFO). Billing의 운영자 지급 API는 통화나 최소 단위 금액 대신 amountCredits를 받습니다. 잔액은 소수 문자열 creditBalance, 이력은 amountCredits와 remainingCredits를 사용합니다. 플랜의 월 크레딧과는 별개입니다. 자세한 내용은 사용량과 청구 문서를 참고하세요.

총액이 0보다 큰 청구서의 결제가 완료되면 팀 청구 이메일로 영수증을 보냅니다. 제품 웹훅 이벤트로 발행하지는 않습니다. 자세한 내용은 결제 영수증 이메일 문서를 참고하세요.

공통 규칙제목 링크 복사

ID제목 링크 복사

• 앱·팀·사용자·배포·도메인 등의 ID는 API가 돌려준 공개 ID를 그대로 쓰세요. 형식이 틀린 ID는 400 invalid_id를 받습니다.
• 배포의 shortId(리비전 주소에 보이는 짧은 ID)는 CLI에서 쓰는 별도 값입니다. 경로의 {deploymentId}에는 공개 ID를 넣어야 합니다.

페이지 나누기제목 링크 복사

• 앱·배포·도메인·purge·활동 목록은 limit(1~100, 기본 50)과 cursor를 씁니다.
• 응답의 nextCursor를 그대로 다음 요청의 cursor로 넘기세요. nextCursor가 null이면 마지막 페이지입니다.
• 배포 이벤트 목록만 다르게 after/nextAfter와 limit(1~1000, 기본 100)을 씁니다.
• 팀·토큰·청구서 목록은 이 규칙을 따르지 않습니다.

요청 본문제목 링크 복사

• JSON은 Content-Type: application/json으로 보냅니다.
• 모르는 필드가 있으면 거부합니다. 오타를 조심하세요.
• 본문은 보통 최대 64 KiB이며, 일부 엔드포인트는 따로 한도가 있습니다.

오류제목 링크 복사

오류 응답은 이런 형태입니다.

{"error": {"code": "email_verification_required", "message": "..."}}

요청 한도제목 링크 복사

앱·사용량 API는 IP별로 요청 수를 제한하며, 넘으면 429를 받습니다. 응답에 X-Retry-After가 있으면 그 초만큼 기다린 뒤 다시 시도하세요. 가입과 로그인에는 별도 한도가 있습니다.

요청 ID제목 링크 복사

문제를 문의할 때는 응답의 X-Request-Id를 함께 알려 주세요. ntro --verbose로 실행하면 CLI가 보낸 요청의 ID도 볼 수 있습니다.

앱 도메인 목록제목 링크 복사

GET /v1/apps/{appId}/domains는 기본으로 앱의 프로덕션 주소와 커스텀 도메인만 돌려주고, 배포별 리비전·브랜치 주소는 뺍니다. 포함하려면 includeRevisions=true를 붙이세요. 결과는 등록한 순서(오래된 것부터)로 정렬되므로, 앱을 만들 때 생긴 ntro.run 주소가 맨 앞에 옵니다.

컴퓨트 설정 API제목 링크 복사

• cpuMillicores는 1000분의 1 vCPU 단위입니다. 1000이 vCPU 1개이며, 1000~64000 사이의 1000 배수입니다.
• compute-settings의 필드는 regions, tier, minInstances, maxInstances, port입니다. null이거나 빠진 필드는 "설정 안 함"입니다. 응답에는 마지막 수정 시각 updatedAt과 현재 프로덕션의 값 출처 productionSources도 들어 있습니다(둘 다 없을 수 있음).
• 배포 상세의 compute에는 실제 적용된 port와 값 출처 sources가 있습니다.
• applyComputeSettings: true는 다시 빌드하지 않고 프로덕션을 재배포합니다. 앱 설정의 null이 아닌 값은 nitroship.json이나 CLI 플래그에서 온 값까지 바꾸며, 출처는 app이 됩니다. 앱 설정에 없는 항목은 이전 배포의 값을 유지합니다. 출처 기록이 없는 오래된 배포는 409를 받으니 먼저 다시 빌드하세요. 자세한 내용은 배포 관리 문서를 참고하세요.

프로덕션이 nitroship.json이나 CLI 플래그의 값을 쓰더라도 콘솔·API에서 컴퓨트 설정을 언제든 수정할 수 있습니다. 저장만으로 실행 중인 배포는 바뀌지 않으며, 지금 적용(또는 applyComputeSettings: true)으로 콘솔·API 값을 적용합니다. 일반 배포를 할 때마다 nitroship.json에 선언한 항목(regions, tier, minInstances, maxInstances, port)은 다시 콘솔·API 설정보다 우선합니다. 지원되는 CLI 플래그는 여전히 파일보다 우선합니다.

크론 작업 API제목 링크 복사

두 요청 모두 crons, source, configDeclared를 돌려줍니다.

• crons는 실제 적용된 작업을 선언 순서대로 나열합니다. 각 항목에는 path, schedule, nextRunAt, lastRun이 있습니다.
• source는 "config"(프로덕션 배포 설정), "console"(저장된 콘솔·API 설정), "none"(둘 다 없음) 중 하나입니다.
• configDeclared는 현재 준비된 프로덕션 배포에 crons가 선언되어 있으면 true입니다. 빈 배열도 선언으로 봅니다. 콘솔·API에서 수정해도 true로 남으며, 다음에 crons를 선언한 프로덕션 배포가 그 수정을 덮어씁니다.

{"crons": [{"path": "/api/cleanup", "schedule": "0 5 * * *"}]}로 콘솔 작업 전체를 교체하거나, {"crons": []}로 모두 삭제하세요. 배포 없이 즉시 적용되며, 경로·일정이 그대로인 작업은 실행 상태를 유지합니다. 준비된 프로덕션 배포가 있을 때만 작업이 실행됩니다.

curl -X PUT \
  -H "Authorization: Bearer $NITROSHIP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"crons":[{"path":"/api/cleanup","schedule":"0 5 * * *"}]}' \
  "https://api.nitroship.co/v1/apps/$NITROSHIP_APP_ID/crons"

검증 규칙은 배포 설정과 같습니다. 최대 100개이며, path는 /로 시작하고 512바이트 이하여야 합니다. 프래그먼트(#), 공백, 제어 문자는 쓸 수 없습니다. 쿼리 문자열은 허용됩니다. 일정은 지원되는 UTC 5칸 형식이어야 하며, 같은 경로·일정 조합을 중복 등록할 수 없습니다. 자세한 내용은 일정 쓰는 법 문서를 참고하세요.

잘못된 작업은 400 invalid_crons, 존재하지 않거나 관리할 수 없는 앱은 404 not_found를 반환합니다.

nitroship.json에 크론이 있어도 콘솔·API 수정은 언제든 가능합니다. 수정한 목록은 현재 프로덕션 설정보다 우선하지만, 다음에 crons를 선언한 프로덕션 배포(재배포·승격·롤백 포함)가 덮어씁니다. 명시적인 "crons": []도 작업이 없다는 선언이므로 콘솔 목록보다 우선합니다. crons를 선언하지 않은 배포는 저장된 콘솔 목록을 사용합니다. 콘솔에서 계속 관리하려면 nitroship.json의 crons 키를 지우고 배포하세요. vercel.json의 크론 선언도 같은 규칙을 따릅니다.