API Reference

이 문서는 main/core/src/api_server.rs 기준의 로컬 AllvIa Core API를 설명합니다. 기존 SaaS형 /automations API가 아니라, 에이전트 실행 파이프라인 중심 API입니다.

중요: AllvIa Core API는 로컬 머신에서 구동되는 에이전트 API입니다. 기본 포트는 5680이며 외부 퍼블릭 API Base URL을 사용하지 않습니다.

Base URL

http://127.0.0.1:5680

포트는 STEER_API_PORT 환경변수로 변경할 수 있습니다.

Authentication

운영 환경에서는 STEER_API_KEY를 설정하고 아래 헤더 중 하나를 사용합니다.

Authorization: Bearer YOUR_STEER_API_KEY

X-API-Key: YOUR_STEER_API_KEY

로컬 개발에서만 STEER_API_ALLOW_NO_KEY=1로 무키 모드를 허용할 수 있습니다.

Quick Check

GET /api/health

curl -H "X-API-Key: $STEER_API_KEY" http://127.0.0.1:5680/api/health
# ok

GET /api/status

{
  "cpu_usage": 3.1,
  "memory_used": 145,
  "memory_total": 16384
}

Core Endpoint Groups

그룹	주요 엔드포인트	설명
Agent Pipeline	`POST /api/agent/intent`, `/plan`, `/execute`, `/verify`, `/approve`	자연어 입력을 의도 분류 -> 계획 생성 -> 실행/검증으로 처리
Goal	`POST /api/agent/goal`, `/goal/run`, `GET /api/agent/goal/current`	목표 기반 비동기/동기 실행
Recommendations	`GET /api/recommendations`, `POST /api/recommendations/:id/approve`	추천 조회/승인/거절/보류 및 메트릭
Verification	`POST /api/verify/runtime`, `/visual`, `/semantic`, `/performance`	런타임/시각/의미/성능 검증
Ops/System	`GET /api/logs`, `/api/system/health`, `/api/system/runtime-info`	운영 상태/로그/런타임 정보 확인
Sessions	`GET /api/sessions`, `GET\|DELETE /api/sessions/:id`, `POST /api/sessions/:id/resume`	세션 관리

Agent Pipeline Example

POST /api/agent/intent

{ "text": "오늘 업무 로그를 분석해서 루틴 추천해줘" }

POST /api/agent/plan

{ "session_id": "session_xxx" }

POST /api/agent/execute

{
  "plan_id": "plan_xxx",
  "profile": "strict"
}

Response (요약)

{
  "status": "success",
  "run_id": "plan_xxx_1730000000000",
  "planner_complete": true,
  "execution_complete": true,
  "business_complete": true,
  "logs": ["..."]
}

Error Codes

Status	의미
`200`	정상 처리
`202`	비동기 수락(예: goal 실행 대기/진행 중)
`400`	요청 형식 오류
`401`	인증 실패(API Key 누락/불일치)
`404`	세션/플랜/리소스 없음
`409`	동일 플랜/전역 실행 충돌
`500`	서버 내부 오류

전체 라우트는 main/core/src/api_server.rs의 Router 설정을 기준으로 하며, API 변경 사항은 Releases에서 확인하세요.