hanarang-dashboard/.plans/design/api-design.md

API 설계

공통 규칙

• Base URL: https://hanarang-api.nabomhalang.co.kr
• 응답 형식: JSON
• 인증: MVP에서는 인증 없음 (내부망 전용). 추후 JWT 추가 가능.
• 에러 형식: { "statusCode": 400, "message": "...", "error": "Bad Request" }

Sisters (자매 상태)

Method	Endpoint	설명
GET	/api/sisters	4자매 상태 목록 (SSH로 실시간 조회)
GET	/api/sisters/:name	자매 상세 (설정 + 상태)
GET	/api/sisters/:name/config	openclaw.json 내용
GET	/api/sisters/:name/sessions	최근 세션 목록
GET	/api/sisters/:name/subagents	서브에이전트 사용 현황
POST	/api/sisters/:name/restart	Gateway 재시작 (관리자)
POST	/api/sisters/:name/reset	세션 리셋 (관리자)

GET /api/sisters

// Response 200
[
  {
    "name": "harang",
    "displayName": "하랑이",
    "ip": "10.10.10.112",
    "status": "online",
    "lastSeen": "2026-04-04T01:45:00Z",
    "role": "Orchestrator"
  }
]

Projects (프로젝트)

Method	Endpoint	설명
GET	/api/projects	프로젝트 목록 (Gitea API 연동)
GET	/api/projects/:id	프로젝트 상세 + Sprint + Task
GET	/api/projects/:id/tasks	Task Ledger
GET	/api/projects/:id/activity	활동 로그

Activity (활동 피드)

Method	Endpoint	설명
GET	/api/activity	전체 최근 활동 피드 (limit, offset)

Org (조직도)

Method	Endpoint	설명
GET	/api/org	조직도 데이터 (자매 + 서브에이전트 트리)

Admin (관리자)

Method	Endpoint	설명
GET	/api/admin/harness/:sister/:file	하네스 파일 읽기 (AGENTS.md 등)
PUT	/api/admin/harness/:sister/:file	하네스 파일 수정 + SSOT push
GET	/api/admin/repos	Gitea repo 목록
GET	/api/admin/logs/:sister	세션 로그
GET	/api/admin/costs	토큰 사용량/비용

Health

Method	Endpoint	설명
GET	/health	서버 상태 확인