REST API 레퍼런스
매니저는 /api 에 루트를 둔 단일 REST API 를 노출합니다. web/ 안의 SPA 가 이를 호출하며, 임의의 HTTP 클라이언트로 직접 호출해도 됩니다. 애플리케이션 트래픽용 GraphQL 도, gRPC 도 없습니다 (gRPC 는 매니저 내부의 geminio 터널에만 사용됩니다).
이 페이지는 손으로 작성한 swagger 스펙이 아니라 라우트 카탈로그입니다. 소스 오브 트루스: cmd/ongrid/main.go (chi.Router 마운트들) 와 internal/manager/server/*/http.go (BC 별 핸들러들). 정확한 요청/응답 구조체 필드는 핸들러로 직접 들어가 확인하세요.
관례
- 기본 경로: 모든 라우트는
/api접두사를 가집니다. 따라서GET /v1/edges는https://<manager>/api/v1/edges로 도달합니다. - 버전 관리: 모든 라우트는
/v1/아래에 있습니다./v2/는 없습니다. 하위 비호환 변경은 feature flag 나 새 라우트 뒤로 배포됩니다. - 인증:
Authorization: Bearer ...의 JWT. 공개 라우트 (login, refresh, register, IM webhook, Prometheus auth_request probe) 는 미들웨어를 건너뜁니다. 아래 "Public" 표에 나열되어 있습니다. - Role:
admin,user,viewer. 쓰기 라우트는admin(또는edge:* / write같은 관련 casbin action) 을 요구하고, 읽기 라우트는 인증된 어떤 role 이든 받습니다.viewer는 chat 할 수 있지만 에이전트의 toolbag 은ClassSafe로 필터링됩니다. ADR-022 세 역할 RBAC 참고. - 에러: JSON
{"error":"code","message":"human text"}. 코드는 안정 enum (not_found,invalid_argument,unauthorized,forbidden,conflict). - 콘텐츠 타입: 명시적으로 언급된 경우를 제외하고 모든 요청 / 응답은
application/json입니다 (스트리밍 chat 은 SSE, 로그/트레이스 ingest 는 OTLP-protobuf 또는 Loki-JSON).
공개 라우트 (인증 없음)
| 메서드 | 경로 | 목적 |
|---|---|---|
| GET | /healthz | liveness probe |
| GET | /readyz | readiness probe |
| GET | /internal/auth/dataplane-verify | 로그/트레이스 ingest 용 nginx auth_request probe |
| POST | /api/v1/auth/login | email + 비밀번호를 JWT 로 교환 |
| POST | /api/v1/auth/refresh | refresh token 을 새 access token 으로 교환 |
| POST | /api/v1/auth/register | 자체 가입 (config 로 게이팅) |
| GET | /api/v1/prometheus/auth | Grafana 임베드용 nginx auth_request probe |
| POST | /api/v1/im/feishu/events | 인바운드 Feishu/Lark 콜백; webhook 서명이 인증 |
인증된 라우트
iam (사용자, 조직, 세션)
| 메서드 | 경로 | Role | 소스 |
|---|---|---|---|
| GET | /v1/version | any | cmd/ongrid/main.go (인라인) |
| GET | /v1/me | any | internal/iam/server/http.go |
| GET | /v1/self | any | internal/iam/server/http.go |
| GET | /v1/users | any | 사용자 목록 |
| POST | /v1/users | admin | 사용자 생성 |
| PATCH | /v1/users/{id} | admin | 사용자 수정 (이름, email) |
| PATCH | /v1/users/{id}/password | self 또는 admin | 비밀번호 변경 |
| PATCH | /v1/users/{id}/role | admin | role 변경 (admin/user/viewer) |
| DELETE | /v1/users/{id} | admin | 사용자 제거 |
| GET | /v1/orgs | any | 조직 목록 |
| POST | /v1/orgs | admin | 조직 생성 |
| PATCH | /v1/orgs/{id} | admin | 조직 수정 |
| DELETE | /v1/orgs/{id} | admin | 조직 제거 |
| GET | /v1/orgs/{id}/members | any | 멤버 목록 |
| POST | /v1/orgs/{id}/members | admin | 멤버 추가 |
| PATCH | /v1/orgs/{id}/members/{user_id} | admin | 멤버 role 변경 |
| DELETE | /v1/orgs/{id}/members/{user_id} | admin | 멤버 제거 |
edge (터널 연결 에이전트)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| POST | /v1/edges | edge:* | edge 생성, access+secret 키 발급 |
| GET | /v1/edges | any | edge 목록 |
| GET | /v1/edges/{id} | any | edge 상세 조회 |
| DELETE | /v1/edges/{id} | edge:* | edge 삭제 |
| POST | /v1/edges/{id}/rotate-secret | edge:* | secret 키 교체 |
| POST | /v1/edges/{id}/upgrade | edge:* | 명시적 URL + sha256 으로 원격 에이전트 업그레이드 트리거 |
| POST | /v1/edges/{id}/upgrade-package | edge:* | 원클릭 번들 업그레이드 (ADR-024) |
| GET | /v1/edges/{id}/processes | any | 읽기 전용 프로세스 목록 (on-demand RPC) |
| GET | /v1/edges/{id}/plugins | any | edge 의 구성 + 실행 중 플러그인 목록 (헬스 포함) |
| PUT | /v1/edges/{id}/plugins/{name} | edge:plugin | 플러그인 활성/비활성 + 튜닝 |
| GET | /v1/integrations/plugin-counts | any | 글로벌 플러그인 활성/비활성 카운트 (홈페이지 타일용) |
device (호스트 엔티티, 터널 상태와 분리)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/devices | any | 호스트 디바이스 목록 |
| GET | /v1/devices/{id} | any | 디바이스 상세 조회 |
| PATCH | /v1/devices/{id} | device:* | 표시명, 태그 수정 |
| DELETE | /v1/devices/{id} | device:* | 디바이스 제거 |
| PATCH | /v1/devices/{id}/roles | device:* | role 할당 (db, web, cache...) |
| GET | /v1/devices/{id}/edges | any | 현재 이 디바이스를 대표하는 edge 들 |
| GET | /v1/devices/{device_id}/shell | webshell | WebSSH 스트림 열기 (websocket 업그레이드) |
topology (타입드 CMDB)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/topology/node-types | any | node-type 스키마 목록 |
| POST | /v1/topology/node-types | topology:* | node type 생성 |
| GET | /v1/topology/node-types/{name} | any | 단일 node type 조회 |
| DELETE | /v1/topology/node-types/{name} | topology:* | node type 제거 |
| GET | /v1/topology/nodes | any | 노드 목록 (type, tag 로 필터) |
| POST | /v1/topology/nodes | topology:* | 노드 생성 |
| GET | /v1/topology/nodes/{id} | any | 노드 조회 |
| PATCH | /v1/topology/nodes/{id} | topology:* | 노드 수정 |
| DELETE | /v1/topology/nodes/{id} | topology:* | 노드 제거 |
| GET | /v1/topology/relation-types | any | relation-type 스키마 목록 |
| POST | /v1/topology/relation-types | topology:* | relation type 생성 |
| GET | /v1/topology/relation-types/{name} | any | 단일 relation type 조회 |
| DELETE | /v1/topology/relation-types/{name} | topology:* | relation type 제거 |
| GET | /v1/topology/relations | any | edge (relation) 목록 |
| POST | /v1/topology/relations | topology:* | relation 생성 |
| GET | /v1/topology/relations/{id} | any | relation 조회 |
| PATCH | /v1/topology/relations/{id} | topology:* | relation 수정 |
| DELETE | /v1/topology/relations/{id} | topology:* | relation 제거 |
alert (규칙, incident, 채널)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/alert-rules | any | 규칙 목록 |
| POST | /v1/alert-rules | alert:* | 규칙 생성 |
| GET | /v1/alert-rules/{id} | any | 규칙 조회 |
| PUT | /v1/alert-rules/{id} | alert:* | 규칙 교체 |
| DELETE | /v1/alert-rules/{id} | alert:* | 규칙 제거 |
| POST | /v1/alert-rules/{id}/enabled | alert:* | enabled 플래그 토글 |
| POST | /v1/alert-rules/preview | alert:* | 현재 데이터에 대해 규칙 정의 dry-run |
| GET | /v1/alerts/incidents | any | incident 목록 (필터: status, severity, scope) |
| GET | /v1/alerts/incidents/{id} | any | incident 조회 |
| GET | /v1/alerts/incidents/{id}/events | any | 이벤트 타임라인 |
| POST | /v1/alerts/incidents/{id}/ack | any | acknowledge |
| POST | /v1/alerts/incidents/{id}/resolve | any | resolved 처리 |
| POST | /v1/alerts/incidents/{id}/silence | any | N 시간 동안 silence |
| GET | /v1/alerts/incidents/{id}/investigation | any | AI 생성 조사 보고서 조회 |
| POST | /v1/alerts/incidents/{id}/investigation | any | 조사 트리거 또는 재실행 |
| GET | /v1/alerts/runtime-info | any | evaluator 페이스 + 마지막 사이클 통계 |
| GET | /v1/notification-channels | any | 채널 목록 |
| POST | /v1/notification-channels | channel:* | 채널 생성 |
| GET | /v1/notification-channels/{id} | any | 채널 조회 |
| PUT | /v1/notification-channels/{id} | channel:* | 채널 교체 |
| DELETE | /v1/notification-channels/{id} | channel:* | 채널 제거 |
| POST | /v1/notification-channels/{id}/test | channel:* | 합성 알림 발송 |
규칙의 JSON 모양은 알림 규칙 스키마 를 보세요.
aiops (chat, agents, models)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/agents | any | 에이전트 persona 목록 |
| GET | /v1/agents/{name} | any | persona 상세 조회 |
| DELETE | /v1/agents/{name} | agent:* | 빌트인 / 디스크 persona 삭제 (드묾; 보통 custom 만 삭제 가능) |
| POST | /v1/agents/custom | agent:* | 사용자 정의 persona 생성 |
| PATCH | /v1/agents/custom/{name} | agent:* | 사용자 persona 수정 |
| DELETE | /v1/agents/custom/{name} | agent:* | 사용자 persona 삭제 |
| GET | /v1/chat/sessions | any | 세션 목록 |
| POST | /v1/chat/sessions | any | 세션 생성 |
| PATCH | /v1/chat/sessions/{id} | any | 세션 이름 변경 / 태깅 |
| DELETE | /v1/chat/sessions/{id} | any | 세션 삭제 |
| GET | /v1/chat/sessions/{id}/messages | any | 메시지 히스토리 |
| POST | /v1/chat/sessions/{id}/messages | any | 메시지 전송 (비스트리밍, 최종 응답 반환) |
| POST | /v1/chat/sessions/{id}/messages/stream | any | 메시지 전송 (토큰 + 도구 호출 이벤트의 SSE 스트림) |
| GET | /v1/aiops/models | any | 사용 가능한 제공자 + 모델 (구성된 API 키로 게이팅) |
| POST | /v1/aiops/query-translate | any | LLM 보조 PromQL / LogQL / TraceQL 작성 |
| GET | /v1/aiops/mentions/search | any | @edge, @device, @dashboard 멘션 자동완성 |
| GET | /v1/usage/today | any | 현재 UTC 일자의 토큰 사용량 |
markdown frontmatter 모양은 에이전트 persona 포맷 을 보세요.
knowledge (RAG, vault, repos, 업로드)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/knowledge/docs | any | 문서 목록 (트리) |
| POST | /v1/knowledge/docs | knowledge:* | 문서 생성 |
| GET | /v1/knowledge/docs/{id} | any | 문서 조회 |
| PATCH | /v1/knowledge/docs/{id} | knowledge:* | 문서 본문 편집 |
| PATCH | /v1/knowledge/docs/{id}/move | knowledge:* | 다른 경로로 이동 |
| DELETE | /v1/knowledge/docs/{id} | knowledge:* | 문서 제거 |
| GET | /v1/knowledge/paths | any | path 노드 목록 (트리용) |
| GET | /v1/knowledge/repos | any | Git 저장소 목록 |
| POST | /v1/knowledge/repos | knowledge:* | 저장소 등록 |
| DELETE | /v1/knowledge/repos/{id} | knowledge:* | 저장소 제거 |
| POST | /v1/knowledge/repos/{id}/sync | knowledge:* | 재동기화 트리거 |
| POST | /v1/knowledge/upload | knowledge:* | .md / .txt / .pdf / .docx 업로드 (docextract 로 파싱) |
| GET | /v1/knowledge/search | any | RAG 질의 (청크 + 점수 반환) |
| POST | /v1/knowledge/vault/sync | knowledge:* | 내장 vault 를 GitHub 에서 재 pull |
| GET | /v1/knowledge/ssh-identities | knowledge:* | Git 인증용 SSH 키 목록 |
| POST | /v1/knowledge/ssh-identities | knowledge:* | 기존 SSH 키 등록 |
| POST | /v1/knowledge/ssh-identities/generate | knowledge:* | 새 키 쌍 생성 (개인 키는 서버 밖으로 나가지 않음) |
| PATCH | /v1/knowledge/ssh-identities/{id} | knowledge:* | identity 수정 (이름, 코멘트) |
| DELETE | /v1/knowledge/ssh-identities/{id} | knowledge:* | identity 제거 |
skill (toolbag 조회)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/skills | any | skill 목록 (manager-scope + edge-scope) |
| GET | /v1/skills/{key} | any | skill 상세 조회 (schema, description, scope, class) |
| POST | /v1/skills/{key}/execute | skill:* | 직접 skill 실행 (테스트 / 디버깅) |
디스크의 skill.json 모양은 Skill manifest 를 보세요.
logs / traces (읽기 전용 프록시)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/logs/query_range | any | 프록시된 LogQL query_range |
| GET | /v1/logs/labels | any | 프록시된 label-names |
| GET | /v1/logs/labels/{name}/values | any | 프록시된 label-values |
| GET | /v1/traces/search | any | 프록시된 TraceQL /api/search |
| GET | /v1/traces/{trace_id} | any | ID 로 단일 트레이스 |
| GET | /v1/traces/tags/{tag}/values | any | 프록시된 /api/search/tag/.../values |
monitor (대시보드 / 패널)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/monitor/panels | any | 패널 목록 |
| POST | /v1/monitor/panels | monitor:* | 패널 생성 |
| PATCH | /v1/monitor/panels/{id} | monitor:* | 패널 수정 |
| DELETE | /v1/monitor/panels/{id} | monitor:* | 패널 제거 |
| GET | /v1/observability/dashboards/{uid} | any | 렌더 준비된 Grafana 대시보드 JSON |
metric (edge 별 메트릭 스냅샷)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/edges/{id}/metrics | any | 최신 폐쇄형 호스트 메트릭 스냅샷 |
prometheus (admin)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| POST | /v1/prometheus/launch | admin | 임베디드 Prometheus 재기동 |
| POST | /v1/prometheus/query_range | any | LLM 도구용 query_range (정규화된 매트릭스 반환) |
imbridge (채팅 표면 — Slack / Telegram / Lark / DingTalk / WeCom)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/im/apps | any | 연결된 IM 앱 목록 |
| POST | /v1/im/apps | im:* | IM 앱 등록 |
| GET | /v1/im/apps/{id} | any | 앱 조회 |
| PUT | /v1/im/apps/{id} | im:* | 앱 수정 |
| DELETE | /v1/im/apps/{id} | im:* | 앱 제거 |
| POST | /v1/im/apps/{id}/reveal | admin | 마스킹된 secret 공개 |
marketplace (skill pack)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/marketplace/registries | any | 구성된 레지스트리 목록 |
| GET | /v1/marketplace/installed | any | 설치된 pack 목록 |
| POST | /v1/marketplace/install | marketplace:* | 레지스트리에서 pack 설치 |
| DELETE | /v1/marketplace/installed/{pack_id} | marketplace:* | pack 제거 |
setting (시스템 설정: integrations, 기본값, secret)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/system-settings | any | 보이는 설정 목록 |
| PUT | /v1/system-settings/{category}/{key} | admin | 설정 upsert |
| DELETE | /v1/system-settings/{category}/{key} | admin | 설정 제거 |
| GET | /v1/system-settings/{category}/{key}/reveal | admin | 마스킹된 secret 공개 |
integration (연결 테스트)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| POST | /v1/integrations/grafana/sync | admin | 대시보드 + 데이터소스 동기화 |
| POST | /v1/integrations/grafana/test | admin | Grafana 연결 테스트 |
| POST | /v1/integrations/llm/invalidate | admin | 캐시된 LLM 클라이언트 무효화 (API 키 재독을 강제) |
| POST | /v1/integrations/loki/test | admin | Loki 연결 테스트 |
| POST | /v1/integrations/prom/test | admin | Prometheus 연결 테스트 |
| POST | /v1/integrations/tempo/test | admin | Tempo 연결 테스트 |
| POST | /v1/integrations/websearch/test | admin | SearXNG / 웹 검색 백엔드 테스트 |
webshell (터널 위의 인터랙티브 shell)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/devices/{device_id}/shell | webshell | WebSocket 업그레이드된 SSH 스트림 열기 |
| GET | /v1/webshell/sessions | any | 활성 세션 목록 |
| DELETE | /v1/webshell/sessions/{id} | webshell | 세션 종료 |
audit (admin 로그)
| 메서드 | 경로 | Role | 설명 |
|---|---|---|---|
| GET | /v1/admin/audit-logs | admin | 테넌트 전역 감사 추적 (HLD-010) |
페이지네이션
리스트 엔드포인트는 불투명 커서를 사용합니다:
text
GET /v1/edges?limit=50&cursor=eyJpZCI6MTAwMH0응답은 {"items":[...], "next_cursor":"...", "total":...} 를 담고 있습니다. 마지막 페이지에서 next_cursor 는 비어 있습니다.
속도 제한
오픈 소스 빌드에는 글로벌 속도 제한이 없습니다. LLM 예산 게이트 (ONGRID_LLM_DAILY_TOKEN_LIMIT) 가 채팅 트래픽의 상한입니다 — 다른 모든 엔드포인트는 매니저 앞에 두는 것 (nginx, 자체 게이트웨이) 에 의존합니다.
버전 관리
GET /v1/version 은 {"manager_version":"vX.Y.Z"} 를 반환합니다. SPA 가 이를 읽어 에이전트 버전이 매니저와 어긋나는 edge 를 표시합니다. 업그레이드 도구에 활용하세요.
함께 보기
- 환경 변수 — API 동작을 제어하는 것들.
- 알림 규칙 스키마 —
/v1/alert-rules의 요청 본문. - Skill manifest —
/v1/skills와 마켓플레이스 설치의 요청 본문. - 에이전트 persona 포맷 —
/v1/agents/custom의 요청 본문.