모든 요청에 X-API-Key를 전달하세요. 키는 서버 측 비밀 저장소에 보관하고 브라우저 코드나 공개 파일에 넣지 마세요. 예시를 사용하기 전에 콘솔에서 API Key를 만들고 PREVIEWSHIP_API_KEY 환경 변수를 설정하세요.
API Key는 서버에 보관하고 리소스는 키 소유 계정별로 분리됩니다. POST가 시간 초과되면 중복 생성을 막기 위해 재시도 전 배포 기록을 확인하세요.
응답 예시는 일부 필드만 표시하며 한도, ID와 시간은 예시입니다.
ID는 정수입니다. createdAt, updatedAt 등의 시간은 ISO 8601 UTC 문자열입니다. 필드 생략과 null은 다르며 자세한 내용은 각 API를 확인하세요. 예시의 도메인과 한도는 설명용입니다. 페이지 번호 page는 0부터 시작하고 size는 서버에서 1–100으로 정규화됩니다. current는 이 기록이 프로젝트의 latestDeploymentId가 가리키는 배포인지 여부, retained는 결과물 보존, canRollback은 상태·제공 방식·결과물에 따른 가능 여부, proOnly는 계정 권한 제한을 나타냅니다. 이 불리언 값들은 서로 독립적이며 작업 성공을 보장하지 않습니다.
주요 오류는 401 INVALID_API_KEY, 403 ACCOUNT_BLOCKED, 404 리소스 없음, 409 상태 충돌, 410 결과물 사용 불가, 413 업로드 초과 및 일별·월별 배포 한도 초과 시 402입니다. 애플리케이션의 비즈니스 오류에는 error.code와 error.message가 있으며 error.details는 생략될 수 있습니다. 게이트웨이 또는 프록시 오류는 형식이 다를 수 있습니다.
error.code →/v1/deployments배포 생성
브라우저에서 실행 가능한 결과물을 업로드하고 배포를 대기열에 넣습니다.
- 요청
- multipart/form-data: projectName과 zip 필수, source·visibility·password 선택. zip은 정적 ZIP 또는 단일 HTML, Markdown, PDF 파일입니다. projectName은 Unicode 코드 포인트 기준 최대 100개입니다. source는 통계용 출처이며 CONSOLE, CLI, MCP, EXTENSION, API, GUEST를 지정할 수 있습니다. API Key 요청에서 생략하거나 유효하지 않으면 API로 분류되며 인증에는 영향을 주지 않습니다. 새 비밀번호를 설정할 때 앞뒤 공백을 제거한 뒤 6–100자여야 하며, 기존 프로젝트는 저장된 비밀번호를 유지할 수 있습니다.
- 응답
- 201: deploymentId, status, deploymentSource, visibility, createdAt. visibility는 현재 접근 방식이며 요청한 변경은 활성화 성공 후 적용됩니다.
- 필드 값
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKED배포 수명 주기입니다. READY는 활성화 성공을 뜻하지만 이후 SUPERSEDED, EXPIRED 또는 BLOCKED로 바뀔 수 있습니다. 일부 BLOCKED 배포는 수정 후 복구될 수 있습니다. 어떤 상태도 영구적이라고 보장되지 않으며 status만으로 URL 접근 가능 여부를 판단할 수 없습니다.
visibility / projectVisibility:PUBLIC,PASSWORD,PRIVATE배포 및 PATCH 쓰기에는 PUBLIC과 PASSWORD만 허용됩니다. 과거 조회에는 PRIVATE가 나타날 수 있습니다.
source:CONSOLE,CLI,MCP,EXTENSION,API,GUEST선택 source는 기록용이며 인증을 제어하지 않습니다. API Key 요청에서 누락되거나 유효하지 않으면 API가 됩니다.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOY응답 source는 닫힌 열거형이 아니며 과거 또는 향후 값이 있을 수 있습니다. 대부분의 상세/목록은 과거 REDEPLOY를 CONSOLE로 표시하지만 버전 목록은 저장된 값을 반환할 수 있습니다.
- 제한 및 동작
- visibility 생략 시 새 프로젝트는 PUBLIC, 기존 프로젝트는 설정을 유지합니다. PASSWORD는 적격 요금제가 필요합니다. 할당량과 콘텐츠 검사가 적용되며 201은 완료를 뜻하지 않습니다.
- 필드 및 동작 상세
multipart의 projectName 필드는 반드시 있어야 합니다. 값이 공백이면 서버가 업로드 파일명에서 이름 추론을 시도합니다. HTTP 201은 대기열 등록만 뜻합니다. 반환된 visibility는 현재 접근 방식이며 요청한 변경은 활성화 성공 후 적용됩니다. 배포 업로드에서 새 비밀번호는 앞뒤 공백을 제거한 뒤 저장됩니다.
호출 예시
curl -X POST 'https://api.previewship.com/v1/deployments' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY" \
-F 'projectName=my-project' \
-F 'zip=@./site.zip'응답
{
"deploymentId": 42,
"status": "QUEUED",
"deploymentSource": "API",
"visibility": "PUBLIC",
"createdAt": "2026-11-13T10:00:00Z"
}/v1/deployments/{id}배포 조회
배포 상태와 미리보기 사용 가능 여부를 확인합니다.
- 요청
- 경로 id는 배포 ID이며 요청 본문은 없습니다.
- 응답
- 200: deploymentId, projectId, status, previewUrl, urlStatus, failureCode, errorMessage, contentRisk 및 재시도 가능 여부.
- 필드 값
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKED배포 수명 주기입니다. READY는 활성화 성공을 뜻하지만 이후 SUPERSEDED, EXPIRED 또는 BLOCKED로 바뀔 수 있습니다. 일부 BLOCKED 배포는 수정 후 복구될 수 있습니다. 어떤 상태도 영구적이라고 보장되지 않으며 status만으로 URL 접근 가능 여부를 판단할 수 없습니다.
urlStatus:READY,BLOCKED,EXPIRED,UNAVAILABLE백엔드 상태를 기준으로 계산한 URL 가용성이며 배포 상태와 함께 확인해야 합니다. READY여도 비밀번호 없이 또는 모든 방문자가 접근할 수 있다고 보장하지 않으며 접근 제어, 네트워크 및 호스팅 상태의 영향을 받습니다.
visibility / projectVisibility:PUBLIC,PASSWORD,PRIVATE배포 및 PATCH 쓰기에는 PUBLIC과 PASSWORD만 허용됩니다. 과거 조회에는 PRIVATE가 나타날 수 있습니다.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOY응답 source는 닫힌 열거형이 아니며 과거 또는 향후 값이 있을 수 있습니다. 대부분의 상세/목록은 과거 REDEPLOY를 CONSOLE로 표시하지만 버전 목록은 저장된 값을 반환할 수 있습니다.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLE계산된 호스팅 상태이며 호스팅 상태 서비스를 사용할 수 있을 때만 반환됩니다.
contentRisk.status:PENDING,CHECKING,RETRYING,COMPLETEDcontentRisk는 null일 수 있습니다. status는 검사 진행 상태이며 URL 가용성이 아닙니다.
contentRisk.notificationStatus:PENDING,RETRYING,ACCEPTED,FAILED,SKIPPED_NO_RECIPIENT,SKIPPED,SUPERSEDED알림 상태입니다. ACCEPTED는 메일 서비스가 접수한 것이며 전달 완료가 아닙니다. RUNNING은 PENDING으로 표시됩니다. 알려진 값이며 고정 목록이 아닙니다.
contentRisk.findings[].limit.scope:TOTAL_BYTES,FILE_BYTES,MARKUP_NODES,LINKED_SCRIPT_BYTES,AI_TAG_CHARS_AT_LEAST,AI_CONTEXT_CHARS,AI_CANDIDATES,AI_BATCHES,AI_INPUT_CHARS일부 finding에만 나타나며 현재 알려진 scope 문자열은 고정 목록이 아닙니다. actual과 maximum의 단위는 각 값을 참조하세요.
failureCode:UNBUILT_SOURCE,EMPTY_ARCHIVE,MISSING_ENTRY_FILE,MULTIPLE_BUILD_OUTPUTS,INVALID_PDF_FILE,INVALID_ARCHIVE_PATH,ARCHIVE_READ_FAILED,UPLOAD_ARTIFACT_MISSING,DEPLOYMENT_PROVIDER_FAILED,CONTENT_CHECK_UNAVAILABLE,CONTENT_RISK_HIGH,MULTIPLE_PDF_FILES,ZIP_TOO_LARGE,DEPLOYMENT_SUPERSEDED주요 비동기 배포 failureCode이며 고정 목록이 아닙니다. errorMessage와 재시도 가능 여부를 확인하세요.
- 제한 및 동작
- 키 소유 계정의 배포만 조회할 수 있습니다. 간격을 두고 최종 상태까지 조회하고 READY이며 URL이 사용 가능할 때 사용하세요.
- 필드 및 동작 상세
status는 배포 상태이고 urlStatus는 미리보기 사용 가능 여부이므로 격리나 만료 후 서로 다를 수 있습니다. contentRisk는 null일 수 있으며 attempt, maxAttempts, nextRetryAt은 생략될 수 있습니다. contentCheckRetryAvailable은 현재 접근 권한으로 재시도가 가능하다는 보장이 아닙니다. contentCheckRetryExpiresAt이 null이면 기존 재시도를 찾을 수 있다는 뜻일 수 있습니다. contentCheckUploadQuotaRestored는 보상 처리 표시이며 현재 기간의 카운터가 변경되었다는 증거는 아닙니다. hostingStatus, hostingUntil, paidThrough, autoRenews, restorable은 조건부 필드이며 hostingUntil과 paidThrough는 null일 수 있습니다. contentRisk.findings는 배열이며 reasonCode는 확장 가능한 문자열이고 limit은 생략될 수 있습니다. verifiedSafeRecheck=true는 완료된 PASS, 비어 있지 않은 모델 버전, 기록된 모델 판정 SAFE 및 신뢰도 HIGH를 요구하며 일반 PASS만으로는 충족되지 않습니다.
호출 예시
curl 'https://api.previewship.com/v1/deployments/42' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"응답
{
"deploymentId": 42,
"projectId": 7,
"projectName": "my-project",
"status": "READY",
"deploymentSource": "API",
"previewUrl": "https://example.previewship.net",
"urlStatus": "READY",
"contentRestricted": false,
"previewExpiresAt": null,
"errorMessage": null,
"failureCode": null,
"contentRisk": null,
"contentCheckArtifactExpiresAt": null,
"contentCheckUploadQuotaRestored": false,
"contentCheckRetryAvailable": false,
"contentCheckRetryExpiresAt": null,
"visibility": "PUBLIC",
"createdAt": "2026-11-13T10:00:00Z",
"updatedAt": "2026-11-13T10:01:00Z"
}/v1/deployments배포 목록
계정의 배포 기록을 검색합니다.
- 요청
- 선택 쿼리: page(기본 0), size(기본 20), status, q, days. status는 ALL 또는 QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED 중 단일 값입니다. q는 프로젝트 이름 또는 미리보기 URL을 부분 검색하고 days는 최근 N일을 필터링합니다.
- 응답
- 200: content, page, size, totalElements, totalPages, statusCounts. statusCounts는 q와 days의 영향을 받지만 status 필터의 영향은 받지 않습니다.
- 필드 값
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKED배포 수명 주기입니다. READY는 활성화 성공을 뜻하지만 이후 SUPERSEDED, EXPIRED 또는 BLOCKED로 바뀔 수 있습니다. 일부 BLOCKED 배포는 수정 후 복구될 수 있습니다. 어떤 상태도 영구적이라고 보장되지 않으며 status만으로 URL 접근 가능 여부를 판단할 수 없습니다.
urlStatus:READY,BLOCKED,EXPIRED,UNAVAILABLE백엔드 상태를 기준으로 계산한 URL 가용성이며 배포 상태와 함께 확인해야 합니다. READY여도 비밀번호 없이 또는 모든 방문자가 접근할 수 있다고 보장하지 않으며 접근 제어, 네트워크 및 호스팅 상태의 영향을 받습니다.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOY응답 source는 닫힌 열거형이 아니며 과거 또는 향후 값이 있을 수 있습니다. 대부분의 상세/목록은 과거 REDEPLOY를 CONSOLE로 표시하지만 버전 목록은 저장된 값을 반환할 수 있습니다.
- 제한 및 동작
- page는 0부터 시작하고 size는 1–100으로 제한됩니다. days는 최대 365이며 0 이하는 시간 필터가 없습니다. 잘못된 status는 400입니다.
호출 예시
curl -G 'https://api.previewship.com/v1/deployments' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY" \
--data-urlencode 'page=0' --data-urlencode 'size=20' \
--data-urlencode 'status=READY' --data-urlencode 'q=my-project' --data-urlencode 'days=30'응답
{
"content": [
{
"deploymentId": 42,
"projectId": 7,
"projectName": "my-project",
"status": "READY",
"deploymentSource": "API",
"previewUrl": "https://example.previewship.net",
"urlStatus": "READY",
"contentRestricted": false,
"previewExpiresAt": null,
"current": true,
"canRollback": true,
"createdAt": "2026-11-13T10:00:00Z"
}
],
"page": 0,
"size": 20,
"totalElements": 1,
"totalPages": 1,
"statusCounts": {
"all": 1,
"queued": 0,
"building": 0,
"ready": 1,
"superseded": 0,
"failed": 0,
"expired": 0,
"blocked": 0
}
}/v1/deployments/{id}/retry-content-check콘텐츠 검사 재시도
복구 가능한 콘텐츠 검사의 기술적 실패를 다시 업로드하지 않고 재시도합니다.
- 요청
- 경로 id는 실패한 배포 ID이며 요청 본문은 없습니다.
- 응답
- 201: 재시도 배포의 deploymentId, status, deploymentSource, visibility, createdAt.
- 필드 값
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKED배포 수명 주기입니다. READY는 활성화 성공을 뜻하지만 이후 SUPERSEDED, EXPIRED 또는 BLOCKED로 바뀔 수 있습니다. 일부 BLOCKED 배포는 수정 후 복구될 수 있습니다. 어떤 상태도 영구적이라고 보장되지 않으며 status만으로 URL 접근 가능 여부를 판단할 수 없습니다.
visibility / projectVisibility:PUBLIC,PASSWORD,PRIVATE배포 및 PATCH 쓰기에는 PUBLIC과 PASSWORD만 허용됩니다. 과거 조회에는 PRIVATE가 나타날 수 있습니다.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOY응답 source는 닫힌 열거형이 아니며 과거 또는 향후 값이 있을 수 있습니다. 대부분의 상세/목록은 과거 REDEPLOY를 CONSOLE로 표시하지만 버전 목록은 저장된 값을 반환할 수 있습니다.
- 제한 및 동작
- 먼저 contentCheckRetryAvailable을 확인하세요. 보존된 결과물, 프로젝트 상태와 접근 권한이 적합해야 합니다. 더 최근 게시 버전이 있으면 새 재시도를 만들 수 없습니다. 같은 실패를 반복 호출하면 기존 재시도를 반환합니다.
- 필드 및 동작 상세
상업용 한도가 적용되는 계정의 첫 재시도 생성은 일별·월별 배포 횟수를 소비하지만 업로드 사용량을 늘리지 않습니다. 같은 실패의 반복 요청은 기존 자식 배포를 반환할 수 있으며 횟수를 다시 차감하지 않습니다.
호출 예시
curl -X POST 'https://api.previewship.com/v1/deployments/42/retry-content-check' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"응답
{
"deploymentId": 43,
"status": "QUEUED",
"deploymentSource": "CONTENT_CHECK_RETRY",
"visibility": "PUBLIC",
"createdAt": "2026-11-13T10:05:00Z"
}/v1/projects프로젝트 목록
API Key 소유 계정의 프로젝트를 나열합니다.
- 요청
- 쿼리와 요청 본문이 없습니다.
- 응답
- 200: ID, 이름, 최신 상태, 미리보기 URL 및 접근 설정이 포함된 projects 배열.
- 필드 값
- latestDeploymentStatus:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKED배포 수명 주기입니다. READY는 활성화 성공을 뜻하지만 이후 SUPERSEDED, EXPIRED 또는 BLOCKED로 바뀔 수 있습니다. 일부 BLOCKED 배포는 수정 후 복구될 수 있습니다. 어떤 상태도 영구적이라고 보장되지 않으며 status만으로 URL 접근 가능 여부를 판단할 수 없습니다.
urlStatus:READY,BLOCKED,EXPIRED,UNAVAILABLE백엔드 상태를 기준으로 계산한 URL 가용성이며 배포 상태와 함께 확인해야 합니다. READY여도 비밀번호 없이 또는 모든 방문자가 접근할 수 있다고 보장하지 않으며 접근 제어, 네트워크 및 호스팅 상태의 영향을 받습니다.
projectVisibility:PUBLIC,PASSWORD,PRIVATE배포 및 PATCH 쓰기에는 PUBLIC과 PASSWORD만 허용됩니다. 과거 조회에는 PRIVATE가 나타날 수 있습니다.
latestDeploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOY응답 source는 닫힌 열거형이 아니며 과거 또는 향후 값이 있을 수 있습니다. 대부분의 상세/목록은 과거 REDEPLOY를 CONSOLE로 표시하지만 버전 목록은 저장된 값을 반환할 수 있습니다.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLE계산된 호스팅 상태이며 호스팅 상태 서비스를 사용할 수 있을 때만 반환됩니다.
- 제한 및 동작
- 계정 소유 프로젝트만 반환하며 게스트 프로젝트는 제외됩니다.
- 필드 및 동작 상세
latestDeploymentId, latestDeploymentStatus, latestDeploymentSource, latestDeployedAt, previewUrl, previewExpiresAt은 null일 수 있습니다. hostingStatus, hostingUntil, paidThrough, autoRenews, restorable은 호스팅 상태가 제공될 때만 반환되며 hostingUntil과 paidThrough는 null일 수 있습니다. latest가 가리키는 기록이 없으면 latestDeploymentStatus, latestDeploymentSource, previewUrl 등의 표시값이 과거 READY Vercel 배포로 대체될 수 있어 latestDeploymentId와 반드시 일치하지 않습니다.
호출 예시
curl 'https://api.previewship.com/v1/projects' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"응답
{
"projects": [
{
"id": 7,
"name": "my-project",
"latestDeploymentId": 42,
"latestDeploymentStatus": "READY",
"latestDeploymentSource": "API",
"latestDeployedAt": "2026-11-13T10:00:00Z",
"deploymentCount": 1,
"previewUrl": "https://example.previewship.net",
"previewExpiresAt": null,
"projectStatus": "ACTIVE",
"contentRestricted": false,
"hostingState": "HOSTED",
"projectVisibility": "PUBLIC",
"passwordProtected": false,
"abuseBlockedAt": null,
"abuseBlockedReason": null,
"urlStatus": "READY",
"canRedeploy": false,
"createdAt": "2026-11-13T10:00:00Z",
"updatedAt": "2026-11-13T10:01:00Z"
}
]
}/v1/projects/{id}프로젝트 조회
프로젝트와 최신 배포 정보를 조회합니다.
- 요청
- 경로 id는 프로젝트 ID이며 요청 본문은 없습니다.
- 응답
- 200: id, name, latestDeploymentId, latestDeploymentStatus, previewUrl, projectVisibility, urlStatus, canRedeploy.
- 필드 값
- latestDeploymentStatus:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKED배포 수명 주기입니다. READY는 활성화 성공을 뜻하지만 이후 SUPERSEDED, EXPIRED 또는 BLOCKED로 바뀔 수 있습니다. 일부 BLOCKED 배포는 수정 후 복구될 수 있습니다. 어떤 상태도 영구적이라고 보장되지 않으며 status만으로 URL 접근 가능 여부를 판단할 수 없습니다.
urlStatus:READY,BLOCKED,EXPIRED,UNAVAILABLE백엔드 상태를 기준으로 계산한 URL 가용성이며 배포 상태와 함께 확인해야 합니다. READY여도 비밀번호 없이 또는 모든 방문자가 접근할 수 있다고 보장하지 않으며 접근 제어, 네트워크 및 호스팅 상태의 영향을 받습니다.
projectVisibility:PUBLIC,PASSWORD,PRIVATE배포 및 PATCH 쓰기에는 PUBLIC과 PASSWORD만 허용됩니다. 과거 조회에는 PRIVATE가 나타날 수 있습니다.
latestDeploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOY응답 source는 닫힌 열거형이 아니며 과거 또는 향후 값이 있을 수 있습니다. 대부분의 상세/목록은 과거 REDEPLOY를 CONSOLE로 표시하지만 버전 목록은 저장된 값을 반환할 수 있습니다.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLE계산된 호스팅 상태이며 호스팅 상태 서비스를 사용할 수 있을 때만 반환됩니다.
- 제한 및 동작
- 소유한 비게스트 프로젝트만 조회할 수 있습니다. 없거나 소유하지 않으면 404입니다.
- 필드 및 동작 상세
latestDeploymentId, latestDeploymentStatus, latestDeploymentSource, latestDeployedAt, previewUrl, previewExpiresAt은 null일 수 있습니다. hostingStatus, hostingUntil, paidThrough, autoRenews, restorable은 호스팅 상태가 제공될 때만 반환되며 hostingUntil과 paidThrough는 null일 수 있습니다. latest가 가리키는 기록이 없으면 latestDeploymentStatus, latestDeploymentSource, previewUrl 등의 표시값이 과거 READY Vercel 배포로 대체될 수 있어 latestDeploymentId와 반드시 일치하지 않습니다.
호출 예시
curl 'https://api.previewship.com/v1/projects/7' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"응답
{
"id": 7,
"name": "my-project",
"latestDeploymentId": 42,
"latestDeploymentStatus": "READY",
"latestDeploymentSource": "API",
"latestDeployedAt": "2026-11-13T10:00:00Z",
"deploymentCount": 1,
"previewUrl": "https://example.previewship.net",
"previewExpiresAt": null,
"projectStatus": "ACTIVE",
"contentRestricted": false,
"hostingState": "HOSTED",
"projectVisibility": "PUBLIC",
"passwordProtected": false,
"abuseBlockedAt": null,
"abuseBlockedReason": null,
"urlStatus": "READY",
"canRedeploy": false,
"createdAt": "2026-11-13T10:00:00Z",
"updatedAt": "2026-11-13T10:01:00Z"
}/v1/projects/{id}프로젝트 삭제
프로젝트와 관련 배포를 영구 삭제합니다.
- 요청
- 경로 id는 프로젝트 ID이며 요청 본문은 없습니다.
- 응답
- 204, 응답 본문 없음.
- 제한 및 동작
- 고정 URL, 호스팅된 프로젝트, 관련 배포와 Showcase 항목이 삭제됩니다. HTTP API는 프로젝트 이름 확인을 요구하지 않으므로 호출 전 대상을 확인하세요.
호출 예시
curl -i -X DELETE 'https://api.previewship.com/v1/projects/7' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"응답
HTTP 204 No Content/v1/projects/{id}/redeploy-latest최신 버전 재배포
보존된 최신 결과물로 배포를 대기열에 넣습니다.
- 요청
- 경로 id는 프로젝트 ID이며 요청 본문은 없습니다.
- 응답
- 201: deploymentId, projectId, status, deploymentSource, createdAt.
- 필드 값
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKED배포 수명 주기입니다. READY는 활성화 성공을 뜻하지만 이후 SUPERSEDED, EXPIRED 또는 BLOCKED로 바뀔 수 있습니다. 일부 BLOCKED 배포는 수정 후 복구될 수 있습니다. 어떤 상태도 영구적이라고 보장되지 않으며 status만으로 URL 접근 가능 여부를 판단할 수 없습니다.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOY응답 source는 닫힌 열거형이 아니며 과거 또는 향후 값이 있을 수 있습니다. 대부분의 상세/목록은 과거 REDEPLOY를 CONSOLE로 표시하지만 버전 목록은 저장된 값을 반환할 수 있습니다.
- 제한 및 동작
- 적격 프로젝트와 보존된 자체 호스팅 결과물이 필요합니다. 보통 URL이 만료되어야 하며 내부 계정은 READY 버전도 재배포할 수 있습니다. 새 배포 상태를 조회하세요.
- 필드 및 동작 상세
상업용 한도가 적용되는 계정의 재배포 생성은 일별·월별 배포 횟수를 소비하지만 업로드 사용량을 늘리지 않습니다. 반환된 배포는 비동기 작업입니다.
호출 예시
curl -X POST 'https://api.previewship.com/v1/projects/7/redeploy-latest' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"응답
{
"deploymentId": 43,
"projectId": 7,
"status": "QUEUED",
"deploymentSource": "CONSOLE",
"createdAt": "2026-11-13T10:05:00Z"
}/v1/projects/{id}/access프로젝트 접근 조회
프로젝트 접근 방식을 조회합니다.
- 요청
- 경로 id는 프로젝트 ID이며 요청 본문은 없습니다.
- 응답
- 200: projectId, visibility, passwordProtected, proOnly.
- 필드 값
- visibility / projectVisibility:
PUBLIC,PASSWORD,PRIVATE배포 및 PATCH 쓰기에는 PUBLIC과 PASSWORD만 허용됩니다. 과거 조회에는 PRIVATE가 나타날 수 있습니다.
- 제한 및 동작
- 소유 프로젝트만 조회할 수 있으며 비밀번호 자체는 반환되지 않습니다.
- 필드 및 동작 상세
proOnly는 이 계정에 비밀번호 접근 권한이 없음을 나타냅니다. 프로젝트의 현재 접근 방식과 비밀번호 상태는 visibility와 passwordProtected를 확인하세요.
호출 예시
curl 'https://api.previewship.com/v1/projects/7/access' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"응답
{
"projectId": 7,
"visibility": "PUBLIC",
"passwordProtected": false,
"proOnly": false
}/v1/projects/{id}/access프로젝트 접근 변경
공개 또는 비밀번호 접근을 설정합니다.
- 요청
- 경로 id는 프로젝트 ID. JSON: visibility는 PUBLIC 또는 PASSWORD이며 기존 비밀번호가 있으면 password를 생략할 수 있습니다.
- 응답
- 200: projectId, visibility, passwordProtected, proOnly.
- 필드 값
- visibility / projectVisibility:
PUBLIC,PASSWORD,PRIVATE배포 및 PATCH 쓰기에는 PUBLIC과 PASSWORD만 허용됩니다. 과거 조회에는 PRIVATE가 나타날 수 있습니다.
- 제한 및 동작
- PASSWORD는 적격 요금제가 필요하며 비밀번호가 없으면 6–100자로 설정해야 합니다. PUBLIC은 저장된 비밀번호를 지우고 visibility가 없거나 비어 있으면 PUBLIC이 기본값입니다.
- 필드 및 동작 상세
proOnly는 이 계정에 비밀번호 접근 권한이 없음을 나타냅니다. 프로젝트의 현재 접근 방식과 비밀번호 상태는 visibility와 passwordProtected를 확인하세요.
visibility를 생략하거나 비워 두면 PUBLIC으로 처리하고 저장된 비밀번호를 지웁니다. 비밀번호 길이는 앞뒤 공백을 제거하여 검증하지만 PATCH는 원래 입력을 저장하므로 배포 업로드와 다릅니다. 비밀번호 앞뒤에 공백을 넣지 않는 것이 좋습니다.
호출 예시
curl -X PATCH 'https://api.previewship.com/v1/projects/7/access' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY" -H 'Content-Type: application/json' \
-d '{"visibility":"PUBLIC"}'응답
{
"projectId": 7,
"visibility": "PUBLIC",
"passwordProtected": false,
"proOnly": false
}/v1/projects/{id}/versions프로젝트 버전 목록
버전 기록과 롤백 가능 여부를 조회합니다.
- 요청
- 경로 id는 프로젝트 ID. 선택 쿼리 page(기본 0), size(기본 20).
- 응답
- 200: projectId, latestDeploymentId, limit, versions, page, size, totalElements, totalPages.
- 필드 값
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKED배포 수명 주기입니다. READY는 활성화 성공을 뜻하지만 이후 SUPERSEDED, EXPIRED 또는 BLOCKED로 바뀔 수 있습니다. 일부 BLOCKED 배포는 수정 후 복구될 수 있습니다. 어떤 상태도 영구적이라고 보장되지 않으며 status만으로 URL 접근 가능 여부를 판단할 수 없습니다.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOY응답 source는 닫힌 열거형이 아니며 과거 또는 향후 값이 있을 수 있습니다. 대부분의 상세/목록은 과거 REDEPLOY를 CONSOLE로 표시하지만 버전 목록은 저장된 값을 반환할 수 있습니다.
- 제한 및 동작
- page는 0부터 시작하고 size는 1–100입니다. 표시 기록은 계정 한도에 따릅니다. 각 버전의 retained와 canRollback을 확인하세요.
호출 예시
curl -G 'https://api.previewship.com/v1/projects/7/versions' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY" --data-urlencode 'page=0' --data-urlencode 'size=20'응답
{
"projectId": 7,
"latestDeploymentId": 42,
"limit": 3,
"versions": [
{
"deploymentId": 42,
"current": true,
"status": "READY",
"deploymentSource": "API",
"previewUrl": "https://example.previewship.net",
"previewExpiresAt": null,
"artifactExpiresAt": null,
"artifactDeletedAt": null,
"retained": true,
"canRollback": true,
"createdAt": "2026-11-13T10:00:00Z"
}
],
"page": 0,
"size": 20,
"totalElements": 1,
"totalPages": 1
}/v1/projects/{id}/versions/{deploymentId}/rollback버전 롤백
보존된 과거 버전에서 새 비동기 배포를 만듭니다.
- 요청
- 경로 id는 프로젝트 ID, deploymentId는 대상 버전 ID이며 요청 본문은 없습니다.
- 응답
- 200: rolledBack, status, deploymentSource, deploymentId, previewUrl(처음에는 null).
- 필드 값
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKED배포 수명 주기입니다. READY는 활성화 성공을 뜻하지만 이후 SUPERSEDED, EXPIRED 또는 BLOCKED로 바뀔 수 있습니다. 일부 BLOCKED 배포는 수정 후 복구될 수 있습니다. 어떤 상태도 영구적이라고 보장되지 않으며 status만으로 URL 접근 가능 여부를 판단할 수 없습니다.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOY응답 source는 닫힌 열거형이 아니며 과거 또는 향후 값이 있을 수 있습니다. 대부분의 상세/목록은 과거 REDEPLOY를 CONSOLE로 표시하지만 버전 목록은 저장된 값을 반환할 수 있습니다.
- 제한 및 동작
- 결과물이 보존된 자체 호스팅 READY 또는 SUPERSEDED 버전만 가능합니다. 활성화에 성공한 뒤 고정 URL이 전환되므로 반환된 deploymentId를 조회하세요. HTTP는 이름 확인을 요구하지 않습니다.
- 필드 및 동작 상세
롤백은 일별·월별 배포 횟수를 소비하지 않고 새로운 비동기 배포를 만듭니다. rolledBack=true는 작업 생성만 의미하며 활성화 완료가 아닙니다. 반환된 deploymentId를 조회하세요.
호출 예시
curl -X POST 'https://api.previewship.com/v1/projects/7/versions/42/rollback' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"응답
{
"rolledBack": true,
"status": "QUEUED",
"deploymentSource": "ROLLBACK",
"deploymentId": 43,
"previewUrl": null
}/v1/usage사용량 조회
계정 한도와 현재 사용량을 조회합니다.
- 요청
- 쿼리와 요청 본문이 없습니다.
- 응답
- 200: plan, subscriptionStatus, businessLimitsApplied, maxUploadMb, daily, monthly, monthlyUpload, concurrentBuilds, projects.
- 필드 값
- plan / subscriptionPlan:
FREE,PRO_MONTHLY,PRO_YEARLYplan은 현재 유효한 권한이고 subscriptionPlan은 실제 구독 요금제입니다. 권한 종료 후에도 후자는 Pro일 수 있습니다.
- 제한 및 동작
- 한도는 계정 정책에 따라 달라질 수 있으므로 반환된 값을 사용하세요.
- 필드 및 동작 상세
HTTP 402는 일별·월별 배포 횟수 또는 월별 업로드 총량 초과를 뜻할 수 있습니다. 실제 한도와 상업용 제한 적용 여부는 계정 정책에 따릅니다.
호출 예시
curl 'https://api.previewship.com/v1/usage' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"응답
{
"plan": "FREE",
"subscriptionPlan": "FREE",
"subscriptionStatus": "FREE",
"paidThrough": null,
"autoRenews": false,
"businessLimitsApplied": true,
"maxUploadMb": 15,
"daily": {
"used": 1,
"limit": 5,
"resetAt": "2026-11-14T00:00:00Z"
},
"monthly": {
"used": 1,
"limit": 20,
"resetAt": "2026-12-01T00:00:00Z"
},
"monthlyUpload": {
"usedMb": 1,
"limitMb": 200,
"resetAt": "2026-12-01T00:00:00Z"
},
"concurrentBuilds": {
"current": 0,
"limit": 1
},
"projects": {
"used": 1,
"limit": 1
}
}필드 값
status
배포 수명 주기입니다. READY는 활성화 성공을 뜻하지만 이후 SUPERSEDED, EXPIRED 또는 BLOCKED로 바뀔 수 있습니다. 일부 BLOCKED 배포는 수정 후 복구될 수 있습니다. 어떤 상태도 영구적이라고 보장되지 않으며 status만으로 URL 접근 가능 여부를 판단할 수 없습니다.
QUEUED- 대기열에서 대기 중
BUILDING- 작업자가 처리 중
READY- 배포가 활성화됨
SUPERSEDED- 후속 배포로 대체됨
FAILED- 배포 실패
EXPIRED- 미리보기 만료
BLOCKED- 배포 차단됨
urlStatus
백엔드 상태를 기준으로 계산한 URL 가용성이며 배포 상태와 함께 확인해야 합니다. READY여도 비밀번호 없이 또는 모든 방문자가 접근할 수 있다고 보장하지 않으며 접근 제어, 네트워크 및 호스팅 상태의 영향을 받습니다.
READY- 백엔드 상태상 사용 가능으로 계산됨
BLOCKED- 접근이 차단되거나 제한됨
EXPIRED- 미리보기 만료
UNAVAILABLE- 현재 사용 가능한 URL 없음
visibility / projectVisibility
배포 및 PATCH 쓰기에는 PUBLIC과 PASSWORD만 허용됩니다. 과거 조회에는 PRIVATE가 나타날 수 있습니다.
PUBLIC- 공개 접근
PASSWORD- 비밀번호 접근
PRIVATE- 과거 비공개 방식이며 쓰기 API에서 허용되지 않음
source
선택 source는 기록용이며 인증을 제어하지 않습니다. API Key 요청에서 누락되거나 유효하지 않으면 API가 됩니다.
CONSOLE- 콘솔 라벨
CLI- CLI 라벨
MCP- MCP 라벨
EXTENSION- 에디터 확장 라벨
API- 직접 API 라벨
GUEST- 게스트 라벨
deploymentSource
응답 source는 닫힌 열거형이 아니며 과거 또는 향후 값이 있을 수 있습니다. 대부분의 상세/목록은 과거 REDEPLOY를 CONSOLE로 표시하지만 버전 목록은 저장된 값을 반환할 수 있습니다.
CONSOLE- 콘솔 또는 정규화된 과거 재배포
CLI- CLI
MCP- MCP
EXTENSION- 에디터 확장
API- 직접 API
GUEST- 게스트
UNKNOWN- 출처 알 수 없음
CONTENT_CHECK_RETRY- 기술적 검사 재시도
ROLLBACK- 롤백 배포
SUBSCRIPTION_RESTORE- 구독 복원
REDEPLOY- 저장된 과거 재배포 출처
projectStatus
알려진 프로젝트 상태입니다. 과거 또는 향후 다른 값도 처리하세요.
ACTIVE- 프로젝트 활성
BLOCKED- 프로젝트 차단됨
hostingState
호스팅 상태는 projectStatus 및 콘텐츠 제한과 별개입니다.
HOSTED- 프로젝트 호스팅 중
ARCHIVED- 프로젝트 보관됨
hostingStatus
계산된 호스팅 상태이며 호스팅 상태 서비스를 사용할 수 있을 때만 반환됩니다.
BLOCKED- 프로젝트 또는 배포 차단됨
ARCHIVED- 프로젝트 보관됨
RESTORING- 구독 복원 진행 중
SUBSCRIPTION_ACTIVE- 유료 호스팅 활성
GRACE- 유료 호스팅 유예 기간
FREE_ACTIVE- 무료 호스팅 활성
EXPIRED- 만료되었으나 복원 가능
RESTORE_UNAVAILABLE- 복원 불가
plan / subscriptionPlan
plan은 현재 유효한 권한이고 subscriptionPlan은 실제 구독 요금제입니다. 권한 종료 후에도 후자는 Pro일 수 있습니다.
FREE- 무료 요금제
PRO_MONTHLY- Pro 월간 요금제
PRO_YEARLY- Pro 연간 요금제
subscriptionStatus
현재 구독 상태이며 배포 상태와 별개입니다.
FREE- 무료 구독 상태
ACTIVE- 구독 활성
PAST_DUE- 결제 연체
CANCELED- 구독 취소됨
contentRisk.status
contentRisk는 null일 수 있습니다. status는 검사 진행 상태이며 URL 가용성이 아닙니다.
PENDING- 검사 대기
CHECKING- 검사 진행 중
RETRYING- 재시도 대기
COMPLETED- 검사 완료, 결과가 UNKNOWN일 수 있음
contentRisk.decision
contentRisk.decision은 검사 결과이며 미리보기 접근 가능성을 보장하지 않습니다.
PASS- 검사 통과
HOLD- 위험으로 보류
UNKNOWN- 결론 미확정
contentRisk.riskLevel
contentRisk 위험 분류입니다. UNKNOWN은 안전을 뜻하지 않습니다.
LOW- 낮은 위험
MEDIUM- 중간 위험
HIGH- 높은 위험
UNKNOWN- 위험 미확정
contentRisk.notificationStatus
알림 상태입니다. ACCEPTED는 메일 서비스가 접수한 것이며 전달 완료가 아닙니다. RUNNING은 PENDING으로 표시됩니다. 알려진 값이며 고정 목록이 아닙니다.
PENDING- 발송 대기
RETRYING- 발송 재시도 대기
ACCEPTED- 메일 서비스 접수
FAILED- 발송 실패
SKIPPED_NO_RECIPIENT- 수신자 없음
SKIPPED- 알림 건너뜀
SUPERSEDED- 후속 상태로 알림 대체됨
contentRisk.findings[].limit.scope
일부 finding에만 나타나며 현재 알려진 scope 문자열은 고정 목록이 아닙니다. actual과 maximum의 단위는 각 값을 참조하세요.
TOTAL_BYTES- 결과물 총 바이트
FILE_BYTES- 파일 바이트
MARKUP_NODES- 마크업 노드 수
LINKED_SCRIPT_BYTES- 연결된 스크립트 바이트
AI_TAG_CHARS_AT_LEAST- 종료되지 않은 HTML 시작 태그의 최소 문자 수
AI_CONTEXT_CHARS- 검사 컨텍스트 문자 수
AI_CANDIDATES- 안전 후보 수
AI_BATCHES- AI 검토 배치 수
AI_INPUT_CHARS- AI 입력 문자 수
error.code
주요 HTTP error.code이며 고정 목록이 아닙니다. message와 선택적 details를 확인하세요.
INVALID_API_KEY- 키 누락 또는 무효
ACCOUNT_BLOCKED- 계정 차단
INVALID_PARAM- 잘못된 매개변수
DAILY_QUOTA_EXCEEDED- 일일 배포 한도 초과
MONTHLY_QUOTA_EXCEEDED- 월간 배포 한도 초과
MONTHLY_UPLOAD_EXCEEDED- 월간 업로드 한도 초과
MAX_PROJECTS_EXCEEDED- 프로젝트 한도 초과
ZIP_TOO_LARGE- 업로드 크기 초과
DEPLOYMENT_NOT_REDEPLOYABLE- 배포를 직접 재시도할 수 없음
DEPLOYMENT_SUPERSEDED- 더 최신 배포가 있음
PROJECT_URL_NOT_EXPIRED- 프로젝트 URL이 아직 만료되지 않음
PROJECT_ARCHIVED- 프로젝트 보관됨
ARTIFACT_NOT_RETAINED- 결과물이 보존되지 않음
PROJECT_NOT_FOUND- 프로젝트가 없거나 접근할 수 없음
DEPLOYMENT_NOT_FOUND- 배포가 없거나 접근할 수 없음
PROJECT_BLOCKED- 프로젝트 차단됨
DOWNGRADE_NOT_ALLOWED- 현재 요금제에서 작업을 허용하지 않음
failureCode
주요 비동기 배포 failureCode이며 고정 목록이 아닙니다. errorMessage와 재시도 가능 여부를 확인하세요.
UNBUILT_SOURCE- 소스 미빌드
EMPTY_ARCHIVE- 빈 압축 파일
MISSING_ENTRY_FILE- 진입 파일 누락
MULTIPLE_BUILD_OUTPUTS- 여러 빌드 결과물
INVALID_PDF_FILE- 잘못된 PDF
INVALID_ARCHIVE_PATH- 잘못된 압축 경로
ARCHIVE_READ_FAILED- 압축 파일 읽기 실패
UPLOAD_ARTIFACT_MISSING- 업로드 결과물 누락
DEPLOYMENT_PROVIDER_FAILED- 호스팅 제공자 실패
CONTENT_CHECK_UNAVAILABLE- 콘텐츠 검사 사용 불가
CONTENT_RISK_HIGH- 콘텐츠 위험 확인
MULTIPLE_PDF_FILES- 여러 PDF 파일
ZIP_TOO_LARGE- 압축 파일이 너무 큼
DEPLOYMENT_SUPERSEDED- 더 최신 배포로 대체됨