사이트 API

사이트 표면을 사용하면 작업 공간에서 사이트를 열거, 검사 및 생성할 수 있습니다. REST API에는 버전 접두사가 없습니다. 아래의 모든 경로는 https://api.showly.ai에 뿌리를 두고 있습니다.

사이트 목록

GET /sites
Authorization: Bearer <token>

토큰이 볼 수 있는 모든 사이트(일반 배열 - 아직 페이지 매김 없음)와 작업공간의 사이트 캡이 있는 형제 entitlements 객체를 반환합니다.

{
  "ok": true,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "projectId": "9b2f1c44-0d31-4c19-8a77-0f4bd4a1c001",
      "slug": "marketing-site",
      "name": "Marketing site",
      "framework": "next-export",
      "status": "active",
      "repositoryUrl": "https://github.com/acme/marketing",
      "productionUrl": "https://marketing-site.showly.site",
      "createdAt": "2026-03-01T10:14:22Z",
      "updatedAt": "2026-07-01T08:03:10Z"
    }
  ],
  "entitlements": {
    "maxSites": "unlimited",
    "currentSites": 3,
    "maxLiveSites": "unlimited",
    "currentLiveSites": 1
  }
}

사이트 ID는 UUID입니다. framework 값은 빌더에서 자동 감지된 자유 형식 문자열입니다(예: next-export, astro, static-html).

사이트 허용량

maxLiveSites는 라이브 사이트의 상업적 허용량입니다. Free와 Pro 모두 "unlimited"입니다. 사용자 지정 계약이나 권한 재정의에서는 유한한 값이 반환될 수 있으며, 이 경우에만 게시 시 확인됩니다.

maxSites는 미리보기 전용 사이트를 포함한 모든 활성 사이트 레코드에 적용됩니다. 모든 기본 요금제에서 "unlimited"입니다. 운영자가 워크스페이스에 명시적 재정의를 설정한 경우에만 유한한 값이 나타납니다. Free에서 Pro로 변경해도 사이트 슬롯은 늘어나지 않습니다. 워크스페이스 미리보기는 만료되지 않습니다.

단일 사이트 확보

GET /sites/{siteId}

사이트와 함께 현재 매니페스트 및 최신 배포 요약을 반환합니다.

사이트 만들기

POST /sites
Content-Type: application/json

{
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Docs",
  "slug": "docs",
  "repositoryUrl": "https://github.com/acme/docs"
}

201과 생성된 사이트를 반환합니다. projectId는 사이트가 속한 프로젝트의 UUID입니다. slug는 ^[a-z0-9-]+$와 일치하고 워크스페이스에서 고유해야 합니다. 충돌하면 409와 error.code: "slug_taken"이 반환됩니다. framework와 repositoryUrl는 선택 사항입니다.

빌드 구성은 생성 본문이 아닌 저장소에 커밋된 showly.json 매니페스트에 있습니다. 빌더는 프레임워크를 자동으로 감지하고 해당 파일에서 rootDirectory, runtime, buildCommand, output 및 관련 필드를 읽습니다. 전체 스키마는 사이트 매니페스트를 참조하세요.

대상 배포

배포 대상은 사이트 단위가 아닌 조직 수준에서 구성됩니다. /deployment-targets에 마운트됩니다:

대상에는 provider, mode 및 runtime가 표시됩니다. 능력 끝점은 다음과 같습니다. 현재 환경에서 활성화된 조합에 대한 정보 소스 열거형 API 스키마의 값은 공급자가 프로비저닝된다는 것을 보장하지 않습니다. 지원되지 않는 조합은 400 deployment_target_not_implemented를 반환합니다.

자신의 클라우드 계정에 배포 대상을 등록하려면 byoCloudTargets 자격 및 사용자 행위자. 토큰 전용 봇은 생성할 수 없습니다. 자체 클라우드 대상을 업데이트하거나 삭제합니다.

Curl 예: 엔드투엔드 생성 + 첫 번째 배포

# 1. Create the site
SITE=$(curl -sS -X POST https://api.showly.ai/sites \
  -H "authorization: bearer $SHOWLY_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Demo", "slug": "demo", "repositoryUrl": "https://github.com/acme/demo" }' \
  | jq -r '.data.id')

# 2. Inspect the site (and the auto-detected manifest)
curl -sS "https://api.showly.ai/sites/$SITE" \
  -H "authorization: bearer $SHOWLY_TOKEN"

# 3. Request a preview deployment (siteId in the path; Idempotency-Key required)
curl -sS -X POST "https://api.showly.ai/sites/$SITE/deploy" \
  -H "authorization: bearer $SHOWLY_TOKEN" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{ "environment": "preview" }'

배포 생성 호출은 202를 반환합니다. POST /sites/:siteId/deploy에는 Idempotency-Key 헤더가 필요합니다. 이것이 없으면 요청은 428를 반환하고 충돌하는 재시도는 409를 반환합니다. 배포 수명주기의 나머지 부분은 배포를 참조하세요.

보관 및 복원

사이트를 삭제하면 보관됩니다. GET /sites에서는 사라지지만 GET /sites/archived에는 계속 표시됩니다. Preview 상태로 남아 있다는 이유만으로 자동 보관되지는 않습니다. 명시적으로 삭제하면 slug를 다시 사용할 수 있습니다. 워크스페이스에 유한한 명시적 maxSites 재정의가 있다면 삭제 시 해당 재정의 슬롯도 하나 해제됩니다.

다음을 포함하여 다시 가져오세요:

POST /sites/:siteId/restore

사이트가 비어 있고 재배포 준비가 완료되었습니다. 이전 배포는 그렇지 않습니다. 빌드 아티팩트가 이미 가비지 수집되었기 때문에 부활했습니다. 복원에는 사이트 슬롯이 소모되므로 현재 상태라면 402가 반환됩니다. maxSites 수당, 404 ID를 알 수 없는 경우 다른 사람에게 속함 작업공간이거나 이미 활성 상태입니다.

오류