# 서버 REST API 사용법

> curl로 서버를 등록하고 조회, 수정, 삭제, 토큰 재발급을 수행합니다.

## 기본 설정

API base URL은 `https://crm.theseeker.io/api/v1`입니다. 예시에서는 실제 키를 출력하지 않고 환경 변수에서 읽습니다.

```bash
export THESEEKER_API_KEY='<keyId>.<secret>'
export BASE='https://crm.theseeker.io/api/v1'
```

모든 요청에 다음 헤더를 사용합니다.

```http
Authorization: Bearer $THESEEKER_API_KEY
```

## 서버 목록

`admin:read` 또는 `servers:read`가 필요합니다. 조직 키는 조직 전체를 조회하고, 프로젝트 키는 자신의 프로젝트만 조회합니다.

```bash
curl -sS "$BASE/servers?projectSlug=payments" \
  -H "Authorization: Bearer $THESEEKER_API_KEY"
```

응답은 `{ "servers": [...] }` 형태입니다.

## 서버 등록

`admin:write` 또는 `servers:write`가 필요합니다.

```bash
curl -sS -X POST "$BASE/servers" \
  -H "Authorization: Bearer $THESEEKER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"projectSlug":"payments","name":"Payments API","slug":"payments-api","intervalSec":15,"watchedServices":["nginx.service"],"nginxEnabled":true}'
```

`201` 응답에는 `server`, `token`, `agentEndpoint`, `install.ubuntu`, `install.macos`, `install.nvm`이 들어 있습니다. `token`은 다시 조회할 수 없습니다.
예시 응답의 `server`에는 `"state": "unknown"`이 포함됩니다. 상태 행은 첫 heartbeat에서 생성되므로 등록 직후에는 상태를 알 수 없습니다.

```json
{ "server": { "state": "unknown" }, "token": "<one-time-token>", "agentEndpoint": "wss://<agent-endpoint>", "install": { "ubuntu": "...", "macos": "...", "nvm": "..." } }
```

프로젝트 키는 `projectSlug`를 생략할 수 있고 자신의 프로젝트로 자동 지정됩니다. 다른 프로젝트를 지정하면 `403 project_forbidden`입니다.

## 상세와 변경

```bash
curl -sS "$BASE/servers/<server-id>" \
  -H "Authorization: Bearer $THESEEKER_API_KEY"

curl -sS -X PATCH "$BASE/servers/<server-id>" \
  -H "Authorization: Bearer $THESEEKER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Payments API primary","intervalSec":30}'
```

상세 `server`에는 `state`, `lastSeenAt`, `agentVersion`, 최신 metrics가 포함됩니다. `state`는 `unknown`, `online`, `offline` 중 하나입니다.

## 삭제와 토큰 재발급

```bash
curl -sS -X DELETE "$BASE/servers/<server-id>" \
  -H "Authorization: Bearer $THESEEKER_API_KEY"

curl -sS -X POST "$BASE/servers/<server-id>/rotate-token" \
  -H "Authorization: Bearer $THESEEKER_API_KEY"
```

토큰 재발급은 이전 토큰을 즉시 무효화하고 새 토큰과 설치 스니펫을 반환합니다.
재발급 응답의 `server.state`는 현재 상태이며, 상태 행이 없다면 `unknown`입니다. 예를 들어 연결된 에이전트라면 다음과 같습니다.

```json
{ "server": { "state": "online" }, "token": "<new-one-time-token>", "agentEndpoint": "wss://<agent-endpoint>", "install": { "ubuntu": "...", "macos": "...", "nvm": "..." } }
```