사양 우선, 사후 문서화 지양
OpenAPI 사양은 진실의 단일 소스이며, 사양에 포함되지 않은 엔드포인트는 배포되지 않습니다. 이 단 하나의 규칙 덕분에 공개 API는 사후가 아닌 빌드 시점에 완벽하게 문서화됩니다. 문서화되지 않은 엔드포인트는 아예 존재할 수 없으므로, 문서화되지 않은 사각지대는 없습니다.
- 700,000+전 세계에서 호스팅되는 사이트
- 1모든 도구가 생성되는 OpenAPI 사양
- 4클라이언트 SDK — TypeScript, Python, PHP, Go
- OAuth 2.1범위가 지정되고 취소 가능한 AI 에이전트 액세스
하나의 API. 모든 인터페이스가 그 위에서 구동됩니다.
대부분의 호스팅 업체는 나중에 제어판에 API를 덧붙이며, 이는 그대로 드러납니다 — 제어판 기능의 절반은 결코 외부에 제공되지 않습니다. 당사는 정반대 방식으로 구축했습니다. 대시보드, 관리자 콘솔, CLI, Terraform 제공자, MCP 서버 및 귀하의 자체 통합 기능은 모두 동일한 엔진 API를 사용합니다. 패널에서 할 수 있는 작업이라면 코드에서도 수행하실 수 있습니다.
자동 생성됨, 직접 관리되지 않음
대화형 참조 문서, 4개의 클라이언트 SDK, CLI의 대부분, Terraform 공급자 스캐폴딩이 모두 하나의 사양에서 생성됩니다. 단 하나의 소스로 수많은 아티팩트가 항상 동기화되므로, 구현에서 벗어난 문서를 뒤쫓을 필요가 전혀 없습니다.
지원 중단 정책이 적용된 버전 관리
엔드포인트는 게시된 지원 중단 정책 및 변경 로그와 함께 /v1 아래에 위치합니다. 빌드 실패를 통해 변경 사실을 알게 되는 대신, 변경 사항이 발생하기 전에 서면으로 안내를 받으실 수 있습니다.
CI에서 계약 테스트됨
구현과 사양 간의 계약 테스트 및 OpenAPI 린팅은 변경 사항이 있을 때마다 실행됩니다. 코드와 계약 사이의 불일치는 빌드 실패로 이어지므로, 귀하가 클라이언트를 생성하는 사양은 서버가 실제로 준수하는 사양과 정확히 일치합니다.
인증, 범위 지정, 그리고 대규모 환경에서 발생하는 문제들
두 가지 접근 방식, 그 이면의 일관된 하나의 원칙. 어느 것을 사용하시든 동일한 권한 검사와 동일한 데이터베이스 수준의 격리가 적용됩니다.
조직별 API 키
키는 zdk_<mode>_<prefix>_<secret> 형식입니다. 시크릿의 SHA-256 해시만 저장되므로 발급 후에는 키를 다시 표시해 드릴 수 없으며, 당사의 데이터베이스에 접근하는 사람도 이를 확인할 수 없습니다. 키에는 범위가 지정되어 있고, 취소할 수 있으며, 개인이 아닌 조직별로 발급됩니다.
라이브 모드와 테스트 모드의 확실한 분리
샌드박스 키는 프로덕션 키와 분리되어 있으며 샌드박스 모드에서 실행됩니다. 실제 청구도, 실제 프로비저닝도 발생하지 않습니다. 비용을 지출하거나 서버를 구축하지 않고도 통합 테스트를 통해 API에 대량의 요청을 보낼 수 있습니다.
사람을 위한 OIDC
사용자 세션은 realm 공개 키로 검증되는 Keycloak 발급 JWT를 통해 인증되며, API 키와 동일한 Principal 객체로 확인됩니다. 엔드포인트는 sites.create 또는 apikeys.manage와 같은 세분화된 권한 키를 기준으로 제어되며 조직별로 확인됩니다. 특정 조직의 권한은 관련 없는 별도의 조직에 대한 액세스를 부여하지 않지만, 그 하위에 중첩된 조직에는 적용됩니다.
하단의 행 수준 보안
모든 테넌트 요청은 주 구성원으로부터 설정된 Postgres 조직 범위가 포함된 트랜잭션에서 실행되므로, 누군가 누락할 수 있는 ORM 필터가 아닌 데이터베이스에 의해 격리가 강제됩니다. 다층 방어 체계로서 queryset 필터도 여전히 유지됩니다.
데모만을 위한 것이 아닌, 기계를 위해 제작되었습니다
README에서 API를 멋지게 보이도록 만드는 것은 쉽지만, 실제 트래픽 환경에서 안정적으로 작동하게 하는 것은 어렵습니다. 바로 이러한 부분들이 새벽 3시에 연동 문제를 일으키기 때문에, 저희가 가장 공들여 개발한 부분이기도 합니다.
대량 작업의 작동 방식을 결정짓는 주목할 만한 세부 사항이 하나 있습니다. 중복 도메인에 대한 409 응답은 모든 테넌트에 대해 "이 호스트 이름이 여기에 호스팅되어 있는가?"라는 질문에 답을 제공하므로, 열거 오라클(enumeration oracle)이자 Footprint-Free에 대한 실질적인 탈익명화 위험 요소가 됩니다. 사이트 생성을 제한(throttling)하는 것은 안이한 대처이자 대량 프로비저닝 제품을 완전히 망가뜨리는 방법이었을 것입니다. 그 대신 주체(principal)별로 거부된 중복 도메인 시도에 대해서만 한도가 차감됩니다. 성공적인 생성 건은 한도에서 차감되지 않으므로 하루 종일 대량으로 프로비저닝할 수 있으며, 탐색 시도는 거의 즉시 차단됩니다.
- 모든 실패 시 일관된 오류 형식 제공: 코드, 읽기 쉬운 메시지, 선택적인 필드 수준 세부 정보 및 지원팀에 문의할 때 전달할 수 있는 request_id. 유효성 검사 오류는 문제가 있는 필드명과 함께 422를 반환합니다.
- 인라인이 아닌 커밋 시 리플레이 레코드가 기록되는 POST의 멱등성 키 — 이를 통해 재시도 시 커밋되지 않은 행을 지정하는 캐시된 201 응답이 재생되지 않습니다. 실패한 요청은 진행 중인 잠금을 즉시 해제하므로 422 응답으로 인해 수정된 재시도가 차단되지 않습니다.
- UUIDv7 기반 키셋 방식의 커서 페이지네이션 — 동시 쓰기 작업에서도 안정적이며, 검색 도중 행이 삽입되어도 페이지 밀림 현상이 발생하지 않습니다.
- 생성된 클라이언트가 추측하는 대신 지능적으로 백오프할 수 있도록 응답에 RateLimit-Remaining이 포함됩니다.
- 범위 외의 리소스는 403 대신 404를 반환합니다. 403은 리소스가 존재함을 확인해 주기 때문입니다. 귀하의 범위 외에 있는 조직으로 필터링하는 경우에도 동일한 이유로 빈 페이지가 반환됩니다.
- 사이트 생성은 프로비저닝이 아닌 등록입니다. POST /v1/sites는 pending 상태와 함께 201을 반환하며 빌드를 절대 차단하지 않습니다. 이벤트는 행과 동일한 트랜잭션 내에서 transactional outbox에 기록되므로, 프로비저닝 요청이 보장되는 경우에만 사이트가 존재합니다.
SDK, CLI 및 Terraform 공급자
서로 다른 세 가지 작업 방식을 위한, 동일한 사양의 세 가지 소비자.
클라이언트 SDK
TypeScript, Python, PHP 및 Go용으로 생성되었으며 사양을 추적하므로 직접 작성한 래퍼를 기다릴 필요 없이 새로운 엔드포인트가 해당 언어로 즉시 제공됩니다.
Zinnector®, CLI
WordPress 사이트의 기본 구조를 생성하고, Node 외에는 아무것도 설치하지 않은 상태로 로컬에서 실행한 후 배포하십시오. Zinnector®는 배포하려는 슬롯을 기준으로 프로젝트의 PHP 버전, 디스크, 파일 수 등을 사전 점검하여 푸시한 후가 아니라 푸시하기 전에 경고를 표시합니다. 또한 로그인, 사이트 목록 조회, 배포, 도메인 및 DNS 관리, 메일 서비스 확인, 백업 생성, 허용 목록에 등록된 WP-CLI 실행, 실시간 로그 확인 및 대량 작업 실행을 지원합니다. 무료이며 MIT 라이선스가 적용되고 동일한 공개 API를 기반으로 구축되었습니다.
Terraform 공급자
사이트, 도메인, DNS 레코드, 사서함 및 요금제를 코드형 인프라로 관리하세요. terraform apply가 호스팅을 프로비저닝하여, 사용자의 환경은 아무도 기록하지 않은 단순한 클릭의 연속 대신 재현 및 검토가 가능한 상태가 됩니다.
대화형 레퍼런스
서버가 구현하는 엔드포인트를 정확하게 설명하며 브라우저에서 직접 읽고 호출할 수 있는 생성된 문서입니다. 둘 다 동일한 사양에서 비롯되었기 때문입니다.
엔드포인트가 다운되어도 안전하게 유지되는 웹훅
플랫폼 이면에는 내구성 있는 이벤트 중추가 있습니다. 모든 상태 변경은 데이터베이스 변경과 함께 원자적으로 Postgres의 트랜잭션 outbox에 이벤트를 기록하며, 릴레이가 이를 NATS JetStream에 게시합니다. 이벤트는 형식과 버전이 지정되어 있습니다 — site.deployed, order.paid, invoice.overdue, backup.completed, abuse.flagged, trial.ending 등.
관심 있는 콘텐츠를 구독하세요
엔드포인트를 WebhookSubscription으로 등록하고 수신할 이벤트 유형을 선택하십시오. 단일 스트림이 알림, 분석, 자동화 및 고객님의 통합 기능을 동일하게 지원합니다. 당사가 사용하는 것과 동일한 이벤트를 사용하시게 됩니다.
HMAC으로 서명됨
모든 전송은 HMAC으로 서명되므로 조치를 취하기 전에 당사에서 보낸 것인지 확인할 수 있습니다.
백오프를 적용하여 다시 시도했으며 기록되었습니다
실패한 전송은 백오프 간격으로 재시도되며 각 시도는 WebhookDelivery로 기록됩니다. 무엇을 보냈는지 고객 지원팀에 이메일로 문의하는 대신 대시보드에서 전송 내역을 검사하고 다시 실행할 수 있습니다.
최소 한 번이므로 id를 기준으로 중복을 제거하십시오
이 파이프라인은 '정확히 한 번'인 척하는 대신 의도적으로 '최소 한 번'으로 작동합니다. 게시 도중에 중단된 릴레이는 클레임 임대가 만료되고 해당 이벤트가 다시 게시됩니다. 봉투 ID를 기준으로 중복을 제거하면 사용자의 컨슈머는 구조적으로 올바르게 작동합니다.
사이트에 코드 배포하기
API는 개발자 이야기의 절반에 불과합니다. 나머지 절반은 배포입니다.
- 구성 파일이 아닌 자격 증명 저장소에 배포 키를 보관하여 OAuth를 통해 GitHub, GitLab 또는 Bitbucket을 연결하십시오.
- Push는 브랜치-환경 매핑(main에서 production으로, staging에서 staging으로) 및 composer와 npm을 위한 스택별 빌드 단계를 포함한 빌드 및 배포 파이프라인을 트리거합니다.
- 배포에 문제가 발생하면 이전 릴리스로 롤백하세요.
- 스테이징 복제 및 즉시 게시 기능을 통해 변경 사항이 방문자에게 도달하기 전에 실제 환경에서 검증됩니다.
- 각 테넌트가 자신의 파일만 볼 수 있도록 CageFS 격리 기반의 사이트별 SFTP가 제공되며, 공유 플랫폼에서 제한된(jailed) SSH 셸도 함께 지원됩니다.
- 패널 터미널 및 SSH를 통한 wp-cli.
- code-server를 통한 브라우저 내 VS Code — 사이트 파일을 직접 편집할 수 있는 git이 포함된 완전한 편집기.
- 사이트별 PHP 버전, 편집 가능한 PHP 설정, 사이트별 확장 프로그램, 환경 변수 및 WP-cron과 함께 제공되는 실제 cron.
사이트에서 작업하는 4가지 방법
API는 하나의 문입니다. 이것이 나머지 네 개의 문이며, 개발자 전용 등급으로 별도 판매되지 않고 플랜에 모두 포함되어 있습니다.
웹 편집기
대시보드의 사이트 페이지에서 열리는 브라우저 기반 VS Code는 내장된 git과 함께 해당 사이트의 실제 파일을 편집하며, 전체 편집기는 귀하의 SFTP 액세스와 동일한 CageFS 격리 환경 내에 있습니다. 이 기능은 라이브(LIVE) 사이트를 직접 편집합니다. 중간에 스테이징 복사본이 없으므로 저장한 파일은 기록되는 즉시 공개됩니다. 단, 정적 파일은 최대 4시간 동안 CDN 캐시에서 계속 제공될 수 있습니다.
Zinnector®, CLI
무료이며 MIT 라이선스가 적용되고 동일한 공개 API를 기반으로 구축되었습니다. WordPress 사이트의 골격을 생성하고, 자체 머신에서 실행하며, 배포할 슬롯에 맞춰 사전 점검(PHP 버전, 디스크, 파일 수)을 진행한 후 배포하십시오. Node 24 이상이 필요합니다.
MCP 서버
하나의 도구 카탈로그를 통해 이미 사용 중인 AI 클라이언트가 대시보드에서 사용하는 것과 동일한 API 및 동일한 권한으로 사이트에서 작업할 수 있습니다. 자체 클라이언트가 연결되는 동일한 서버가 웹 에디터에도 연결됩니다. 다르게 지정하기 전까지는 읽기 전용입니다.
사이트별 개발자 액세스
클라이언트 작업에는 고객님의 비밀번호가 필요하지 않습니다. 이메일 주소로 사용자를 초대하면 정확히 하나의 사이트만 제공됩니다. 해당 사용자는 뷰어, 편집자 또는 관리자 역할로 직접 로그인하며, 다른 모든 사이트는 핸들러가 실행되기 전에 404로 응답합니다. 이는 단순한 단일 검사가 아니라 Postgres 행 수준 보안 정책이자 요청 수준의 펜스입니다. 계정 소유자는 클릭 한 번으로 권한을 부여하고 취소할 수 있으며, 다음 요청부터 즉시 적용됩니다.
그리고 귀하의 AI 에이전트가 사용할 수 있는 동일한 API
당사는 플랫폼을 호스팅된 MCP 서버로 제공합니다. 이는 동일한 작업 카탈로그, RBAC 및 감사 추적을 재사용하는 엔진 API 기반의 씬(thin) 프로토콜 어댑터입니다. Claude Code, Cursor, ChatGPT, Claude Desktop 또는 모든 MCP 지원 클라이언트를 한 번만 연결하면 당사가 API에 추가하는 모든 기능을 자동으로 사용할 수 있습니다.
에이전트는 세 가지를 받습니다: Tools(동일한 API 엔드포인트, 편차를 유발하는 병렬 로직 없음), Resources(조치를 취하기 전에 실제 데이터로 진단할 수 있도록 읽기 전용 사이트 상태, 구성, 최근 로그, 메트릭, 가동 시간 및 KB 문서 제공), Prompts("diagnose this site" 또는 "prepare a migration"과 같은 게시된 워크플로 템플릿).
보안은 인증과 동일한 원칙을 따릅니다. OAuth 2.1, 귀하의 조직에 연결된 토큰, 행 수준 보안이 적용된 RBAC 권한, 도구별로 범위 지정 및 취소 가능, 프로덕션 환경과 분리된 샌드박스를 제공합니다. 삭제, 정지, 결제, 대규모 지출과 같은 파괴적인 작업에는 명시적인 확인이나 사람의 승인 정책이 필요합니다. 전송률 제한과 지출 한도로 AI가 유발하는 유료 작업을 제한하며, 모든 MCP 호출은 ID, 도구, 인수 및 결과와 함께 감사 로그에 기록됩니다.
각 앱을 개별적으로 통합하는 대신 프로토콜을 지원하므로, 호스팅 통합을 변경하지 않고도 AI 도구 선택을 변경할 수 있습니다.
자주 묻는 질문
공개 API는 대시보드에서 사용하는 것과 동일한가요?
예 — 게시되고 강화된 동일한 엔진 API입니다. 대시보드, 관리 콘솔, CLI, Terraform 공급자, MCP 서버 및 웹후크는 모두 단일 인터페이스의 소비자이므로 API가 패널보다 뒤처지지 않습니다.
비용을 들이거나 실제 서버를 구축하지 않고도 연동을 테스트할 수 있습니까?
예. Sandbox 키는 프로덕션 키와 별도로 발급되며 테스트 모드로 실행됩니다. 실제 청구 및 실제 프로비저닝이 발생하지 않습니다. CI가 sandbox 자격 증명을 가리키도록 설정하고 전체 요청 및 응답 주기를 안전하게 실행하십시오.
재시도로 인해 동일한 항목이 두 개 생성되는 것을 방지하려면 어떻게 해야 하나요?
POST 요청 시 Idempotency-Key를 전송하십시오. 재생 기록은 인라인이 아닌 커밋 시점에 기록되므로, 실제로 커밋되지 않은 행에 대해 캐시된 성공 결과가 재시도 시 재생되지 않으며, 실패한 요청은 즉시 잠금을 해제하므로 수정된 재시도가 지연되지 않습니다. Webhook 전송은 설계상 최소 한 번(at-least-once) 전달되므로 수신 측에서 envelope id를 기준으로 중복을 제거하십시오.
하나의 API 키에 모든 클라이언트 조직에 대한 액세스 권한을 부여할 수 있나요?
현재는 지원되지 않습니다. API 키는 조직별로 발급되므로 여러 클라이언트 조직에 걸친 통합은 각 조직마다 키를 보유합니다. 사용자 주체에 대한 권한 또한 조직별로 확인됩니다. 한 조직에서 sites.create 권한을 보유하더라도 관련 없는 별도의 조직에 대한 액세스 권한은 부여되지 않지만, 해당 조직 하위에 중첩된 조직에는 적용됩니다. 이는 의도된 설계입니다. 손상된 키의 영향을 전체 플랫폼이 아닌 해당 조직 및 그 하위 하위 조직으로만 제한합니다.
기본 제공되는 개발자 역할은 실제로 무엇을 허용하나요?
dev 역할은 조직 정보 조회, API 키 관리, 사이트 보기 및 생성, 사이트 재시작, 캐시 삭제, 티켓 확인 및 답변을 포함합니다. 청구 관리는 의도적으로 제외되어 있습니다. 배포 및 프로덕션 반영 권한은 포함되지 않는다는 점에 유의하십시오. 팀원에게 해당 권한이 필요한 경우 Developer가 가장 광범위한 기술 역할이라고 가정하지 마시고, 해당 권한이 포함된 역할을 할당하십시오.
엔드포인트가 1시간 동안 다운되면 웹훅은 어떻게 됩니까?
전송은 백오프를 통해 재시도되며, 모든 시도는 사용자가 검사할 수 있는 WebhookDelivery로 기록됩니다. 업스트림에서는 변경 사항 자체와 동일한 데이터베이스 트랜잭션 내의 트랜잭션 아웃박스에 이벤트가 기록되므로 컨슈머를 사용할 수 없는 동안에도 유실되는 내용이 없습니다. 다운된 컨슈머는 지연될 뿐 프로듀서를 중단시키지 않으며, 복구된 후 대시보드에서 전송을 재생할 수 있습니다.
이를 기반으로 개발을 시작하는 데 비용이 얼마나 드나요?
결제 정보 입력 없이 최대 5개 사이트를 이용할 수 있는 Footprint-Free 호스팅의 14일 무료 체험을 시작해 보세요. 유료 Footprint-Free 요금제는 PBN 5 기준 월 $6부터 시작합니다. 모든 요금제에는 30일 환불 보장, 무료 마이그레이션, 벤더 종속 배제가 제공됩니다.
관련 항목
사양을 읽은 후 그에 맞춰 구축하십시오
스펙 우선 API, 자동 생성된 SDK, CLI, Terraform 프로바이더, 서명된 웹훅 및 MCP 서버 — 전 세계 700,000개 이상의 사이트를 위해 구축된 호스팅에서 제공됩니다. 카드 등록이나 결제 정보 입력 없이 14일 무료 평가판을 시작해 보세요.
무료로 시작하기AI 에이전트가 사용할 수 있는 WordPress 플러그인
이 플러그인들은 각각 워드프레스(WordPress) 사이트를 MCP 서버로 만들어 주므로, Claude, Cursor, VS Code 및 기타 AI 어시스턴트가 사용자로 로그인하여 허용된 작업 범위 내에서 실제 작업을 수행할 수 있습니다.