공개 API 개요
MCP 표면 대신 REST API 을 직접 사용해야 하는 경우.
Showly의 공개 REST API는 MCP 표면이 적합하지 않은 경우(CI 스크립트, 사용자 정의 대시보드, 에이전트가 아닌 타사 통합)를 위해 존재합니다.
에이전트 코드를 작성하는 경우 MCP를 대신 사용하세요. MCP 표면은 최고 수준의 감사, 범위가 지정된 토큰 및 도구 스키마 입력을 가져옵니다. REST API는 동일한 작업을 노출하지만 사람이 작성한 자동화를 위해 설계된 보다 느슨한 의미를 갖습니다.
기본 URL
https://api.showly.ai모든 요청에는 TLS가 필요합니다. 일반 HTTP 요청은 거부됩니다.
버전 관리
현재는 /v1/ 접두어와 Api-Version 헤더가 없습니다. API는 단일 트랙입니다. 모든 주요 변경 사항은 날짜, 영향을 받은 경로 및 마이그레이션 메모와 함께 공개 변경 로그에 표시됩니다. 중요한 통합을 운영하는 경우 해당 페이지를 확인하세요. 추가 변경 사항(새로운 선택 필드, 새로운 엔드포인트)은 별다른 의식 없이 제공됩니다.
인증
모든 요청에는 Authorization: Bearer <token> 헤더가 필요합니다. 사용할 자격 증명은 다음과 같습니다.
- 개인 액세스 토큰(PAT) — 접두사
sk_live_/sk_test_. PAT는 생성된 단일 작업 영역으로 범위가 지정되며 생성 시 부여한 범위를 전달합니다. 임시 스크립트 및 CI에 편리합니다. - MCP 토큰 — 접두사
mcp_live_/mcp_test_, 작업 공간 설정 → MCP 클라이언트에서 발급되거나 장치 흐름에 의해 생성됩니다. 단일 작업 공간으로 범위가 지정되고 MCP 표면에서 사용됩니다. 또한 REST 통화도 인증합니다.
정적 토큰을 붙여넣을 수 없는 에이전트 설치의 경우 Showly는 승인 사용자에게 바인딩된 MCP 토큰을 발행하는 RFC 8628 장치 승인 흐름(POST /oauth/device, 그 다음 폴링 POST /oauth/token)을 지원합니다. 전체 흐름 및 토큰 순환은 인증를 참조하세요.
응답 봉투
모든 JSON 응답은 동일한 봉투를 사용합니다. 성공적인 응답:
{
"ok": true,
"data": { ... }
}오류:
{
"ok": false,
"error": { "code": "string", "message": "string" }
}error.code는 안정적인 계약입니다. error.message이 아닌 분기입니다. 코드는 케밥 또는 뱀 모양의 식별자입니다(rate_limited, idempotency_key_conflict, not_found). 메시지는 인간 독자를 위한 것이며 릴리스 간에 변경될 수 있습니다.
속도 제한
비율 제한은 인증된 작업 공간의 활성 항목에서 선택됩니다. 구성. MCP 토큰은 보수적인 분당 요청 60개 상한선을 사용합니다. 작업 공간 청구와 관계없이. 핫 루트는 경로당 한도가 더 엄격할 수 있습니다.
속도가 제한되면 서버는 error.code: "rate_limited" 및 Retry-After 헤더와 함께 백오프를 초 단위로 전달하는 HTTP 429를 반환합니다. Retry-After를 표준 대기로 처리합니다. 더 빨리 다시 시도하지 마세요.
멱등성
배포 생성 — POST /sites/:siteId/deploy — 필요 Idempotency-Key 헤더. 이것이 없으면 서버는 428를 반환합니다. 핵심은 귀하의 선택입니다. 논리적 시도당 UUID를 권장합니다. (프로덕션 게시는 environment: "production" 및 sourceDeploymentId와 동일한 경로를 거치므로 동일한 요구 사항이 적용됩니다.) 다른 경로에는 헤더가 필요하지 않습니다.
동일한 키를 재생하면 첫 번째 호출에서 캐시된 응답이 반환됩니다. 요청 본문이 동일한 키로 변경되면 서버는 idempotency_key_conflict와 함께 409를 반환합니다.
읽기 전용 GET 요청은 기본적으로 멱등성을 가지며 헤더를 무시합니다.
페이지 매김
목록 엔드포인트(GET /sites, GET /deployments)는 현재 작업 공간에 대한 전체 결과 세트를 일반 배열로 반환합니다. 아직 커서나 limit 매개변수가 없습니다. 페이지 매김이 출시되면 변경 로그에 발표된 추가(불투명 커서)가 됩니다.