배포 API

배포 표면에는 미리 보기 빌드, 프로덕션 게시 및 파이프라인 이벤트 스트림이 포함됩니다. 경로는 접두사가 없고 루트는 https://api.showly.ai입니다(버전 접두사는 없습니다).

배포 생성

POST /sites/{siteId}/deploy
Authorization: Bearer <token>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "environment": "preview",
  "commitSha": "abc123...",
  "branch": "main"
}

이는 배포를 생성하는 유일한 경로입니다(siteId가 경로에 있고 POST /deployments가 없음). Idempotency-Key 헤더가 필요합니다. 누락된 키는 428를 반환하고, 충돌하는 재생된 키는 409를 반환합니다. 202 + queued 상태의 배포 기록을 반환합니다. 빌드는 비동기적으로 실행됩니다. 이벤트를 구독하거나 배포 기록을 폴링하세요.

{
  "ok": true,
  "data": {
    "id": "8c9d3e2a-4f1b-4c6d-9a2e-1f0b3c4d5e6f",
    "siteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "target": "preview",
    "status": "queued",
    "createdAt": "2026-05-14T15:00:00Z"
  }
}

배포 레코드의 환경 필드 이름은 target이며 preview, staging 또는 production 중 하나입니다.

프로덕션에 게시

프로덕션 게시에서는 승격되는 이미 빌드된 ready 미리 보기의 이름을 지정하는 environment: "production" 및 sourceDeploymentId와 동일한 엔드포인트를 사용합니다.

POST /sites/{siteId}/deploy
Authorization: Bearer <token>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "environment": "production",
  "sourceDeploymentId": "dep_01HZX..."
}

프로덕션 게시에는 OTP 또는 MFA 등록이 필요하지 않습니다. 여전히 명시적인 게시 작업 및 작업공간에 approvalWorkflows이 있는 경우 활성화됨, 2인칭 승인. 에이전트는 다음과 같은 경우 request_publish를 사용합니다. 정책이 활성화되어 있지 않으면 2단계 publish_site 확인이 필요합니다.

배포 받기

GET /deployments/{deploymentId}

배포 상태는 정확히 다음 다섯 가지 값 중 하나입니다.

queued → building → ready
                  ↘ failed
                  ↘ canceled

ready는 미리 보기 및 프로덕션 배포 모두에 대한 최종 성공 상태입니다. failed 및 canceled는 최종 실패 상태입니다. built 또는 live 상태가 없습니다. ready 미리 보기 배포는 url 필드에 해당 주소를 전달합니다. a ready 프로덕션 배포는 사이트의 프로덕션 경로를 제공합니다.

스트림 빌드 진행

미리 보기 화면에서 SSE를 통해 라이브 빌드 진행 상황이 스트리밍됩니다.

GET /previews/{deploymentId}/stream
Accept: text/event-stream

스트림은 상태 전환을 내보내고 배포가 최종 상태에 도달하면 닫힙니다. 사후 읽기의 경우 두 개의 일반 엔드포인트가 대부분의 요구 사항을 충족합니다.

• GET /deployments/{deploymentId}/log?lineCount=200 — 캡처된 빌드 로그 테일.
• GET /deployments/{deploymentId}/diagnostics — 에이전트 자체 디버깅을 위해 설계된 구조화된 실패 번들(단계, 오류 코드, 로그 테일, 순위 가설)입니다.

프로덕션 게시 요청 승인/거부

POST /approvals/{requestId}/decision
Content-Type: application/json

{
  "decision": "approve" | "reject",
  "notes": "looks good"
}

승인 역할이 허용된 활성 사용자 멤버십이 필요합니다. 발신 행위자는 자신의 요청을 승인하는 것이 금지됩니다(업무 분리).

롤백

롤백 REST 엔드포인트가 없습니다. 이전 배포로 되돌리는 것은 웹 UI 작업에만 해당됩니다. 이전 ready 미리보기를 다시 게시하려면 environment: "production"로 POST /sites/{siteId}/deploy를 호출하고 해당 배포 ID는 sourceDeploymentId로 지정하세요. 일반 승인, 할당량, 보안 게이트는 여전히 적용되지만 OTP 등록은 필요하지 않습니다.

배포 나열

GET /deployments

작업공간의 전체 배포 목록을 일반 배열로 반환합니다. 아직 필터나 페이지 매기기 매개변수가 없습니다. 단일 사이트의 기록을 보려면 GET /sites/{siteId}/deployments를 사용하세요.

배포 관련 오류

월별 배포 할당량을 소진하면 할당량 오류와 함께 402가 반환됩니다. 계획을 업그레이드하거나 월별 재설정을 기다리세요.

패턴

배포가 완료될 때까지 기다립니다(CI):

DEP=$(curl ... | jq -r .data.id)
while :; do
  S=$(curl -sS .../deployments/$DEP | jq -r .data.status)
  [ "$S" = "ready" ] && break
  { [ "$S" = "failed" ] || [ "$S" = "canceled" ]; } && exit 1
  sleep 10
done

빌드 로그 읽기:

curl -sS ".../deployments/$DEP/log?lineCount=500" \
  | jq -r '.data.lines[]' | tee build.log

대부분의 자동화에서는 MCP create_preview 도구가 더 간단합니다. REST API는 MCP가 맞지 않는 경우에 존재합니다.