API 레퍼런스
서버 목록, 등록, 상세, 수정, 삭제, 토큰 재발급의 REST 계약입니다.
Method | Path | Scope |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Authorization: Bearer <keyId>.<secret>GET /servers?projectSlug=는 { "servers": [...] }를 반환합니다. 조직 키는 조직 전체를 보고, 프로젝트 키는 자신의 프로젝트만 봅니다.
요청 body는 다음 필드를 받을 수 있습니다.
필드 | 타입 | 설명 |
|---|---|---|
| string? | 프로젝트 키는 생략 가능 |
| string | 서버 표시 이름 |
| string? | 서버 식별자 |
| number? | 10에서 60초, 기본 15 |
| string[]? | 감시할 systemd unit |
| boolean? | nginx 수집 여부 |
201 응답은 { server, token, agentEndpoint, install: { ubuntu, macos, nvm } }입니다. token은 1회만 표시됩니다.
{ "server": { "state": "unknown" }, "token": "<one-time-token>", "agentEndpoint": "wss://<agent-endpoint>", "install": { "ubuntu": "...", "macos": "...", "nvm": "..." } }상태 행은 에이전트의 첫 heartbeat에서 생성되므로 등록 직후 state는 unknown입니다.
상세 server는 state(unknown, online, offline), lastSeenAt, agentVersion, 최신 metrics를 포함합니다.
PATCH는 name, intervalSec, watchedServices, nginxEnabled를 부분 수정합니다.
401 UNAUTHORIZED, 403 FORBIDDEN_SCOPE, 403 project_forbidden, 403 reserved_project_forbidden, 403 ip_not_allowed, 404 SERVER_NOT_FOUND, 404 PROJECT_NOT_FOUND, 400 VALIDATION_ERROR, 409 SLUG_TAKEN을 반환할 수 있습니다.
POST /servers/{id}/rotate-token은 이전 토큰을 무효화하고 새 token, agentEndpoint, install을 반환합니다.
회전 응답의 server.state는 현재 상태를 반영하며, 상태 행이 없으면 unknown입니다.
{ "server": { "state": "online" }, "token": "<new-one-time-token>", "agentEndpoint": "wss://<agent-endpoint>", "install": { "ubuntu": "...", "macos": "...", "nvm": "..." } }서버 API 전체는 keyId마다 60초 60회로 제한되며 초과 시 429 RATE_LIMITED와 Retry-After를 반환합니다.
이 페이지가 도움이 되었나요?