로컬 API
에이전트가 장비 안에서 여는 HTTP API(포트 8600) 레퍼런스
에이전트는 api.host:api.port(기본 0.0.0.0:8600)에 HTTP API 를 엽니다. 현장 태블릿의 화면, 같은 LAN 의 다른 프로그램, geo-mlops-edge status 같은 CLI 가 모두 이 API 를 씁니다. 엣지 PC 는 보통 화면이 없으므로 이것이 장비를 들여다보는 창입니다.
인증
api.token이 비어 있으면 인증이 없습니다(기본값). 같은 LAN 안이면 누구나 쓸 수 있다는 뜻입니다. 현장 태블릿마다 토큰을 나눠 주지 않아도 라인이 수집 중인지 바로 볼 수 있게 하려는 기본값입니다.api.token을 설정하면 모든 요청에X-Edge-Api-Token헤더가 필요하고, 틀리면401 invalid api token입니다.GET /health는 토큰과 상관없이 늘 열려 있습니다(로드밸런서·컨테이너 헬스체크용).
# 토큰 설정 (환경 변수 권장)
GEO_EDGE_API__TOKEN=<your-secret>
curl -H 'X-Edge-Api-Token: <your-secret>' http://edge-pc:8600/api/v1/status요청 본문은 api.max_body_bytes(기본 2 GiB)를 넘으면 413 으로 거절합니다. 인증이 없는 API 에 잘못 보낸 업로드 하나 때문에 장비가 멈추지 않게 하려는 한도입니다.
엔드포인트
| 메서드 | 경로 | 하는 일 |
|---|---|---|
GET | /health | 살아 있는지. 토큰 불필요. {"status":"ok","version":"0.2.0"} |
GET | /api/v1/status | 장비·링크·대기량·동기화·모델·수집기·리소스·attention 한꺼번에 |
GET | /api/v1/resources | cpu / gpu / mem / disk 사용률(%) |
GET | /api/v1/queue | 대기 중인 항목. state(pending·uploading·failed), kind, limit(1~500, 기본 50), offset |
DELETE | /api/v1/queue/{id} | 항목 하나 버리기 |
POST | /api/v1/records | 선언 없이 레코드 넣기. 본문 {"kind", "payload", "priority"} |
POST | /api/v1/blobs | 선언 없이 파일 넣기. 본문이 파일 그 자체. 쿼리 kind, filename, priority, dataset_id |
PUT | /api/v1/collectors/{name}/records/{id} | 선언된 push 입구에 넣기. 본문 {"payload", "ts"}. 201 새로 저장 / 200 중복 |
GET | /api/v1/sync | 업로더 상태 |
POST | /api/v1/sync:run | 지금 바로 보내기 |
POST | /api/v1/sync:retry-failed | failed 가 된 항목을 다시 대기 상태로 |
GET | /api/v1/models | 캐시된 모델과 활성 모델 |
POST | /api/v1/models/{name}:pull | 받기(기본으로 활성화까지). 본문 {"version", "activate"} |
POST | /api/v1/models/{name}:activate | 이 버전으로 바꾸기. 본문 {"version"} |
DELETE | /api/v1/models/{name}?version= | 캐시에서 한 버전 지우기 |
POST | /api/v1/inference | 활성 모델로 이미지 판정(모델과 추론 참고) |
GET | /api/v1/settings | 적용 중인 설정(토큰은 빼고 configured 여부만) |
GET | /api/v1/events | 서버 전송 이벤트(SSE): link · sync · queue · model · command … |
dataset_id 를 준 파일은 중앙에서 조립이 끝나면 그 데이터셋의 파일로 등록되고 웹 업로드와 같은 검증을 거칩니다. 다른 테넌트의 데이터셋이면 404 입니다.
예시
큐에서 실패한 것 보기
curl -s 'http://127.0.0.1:8600/api/v1/queue?state=failed&limit=5'{
"items": [],
"backlog": { "count": 0, "bytes": 0, "oldest_ts": null, "evicted_24h": 0, "by_kind": {} }
}항목이 있으면 attempts(시도 횟수)와 last_error(마지막 오류)가 함께 나옵니다.
이벤트 구독
curl -N http://127.0.0.1:8600/api/v1/events?history=20event: <kind>
data: {"kind": "<kind>", "name": "<이벤트 이름>", "ts": "<ISO 시각>", "data": {...}}접속 직후 최근 이벤트 history 개(기본 20, 최대 200)를 먼저 보내므로, 방금 연 화면이 빈 채로 기다리지 않습니다.
설정 확인
curl -s http://127.0.0.1:8600/api/v1/settings{
"device": {
"id": "edge-bench-01",
"location": "bench",
"hostname": "edge-pc",
"os": "Ubuntu 24.04.5 LTS x86_64",
"agent_version": "0.2.0"
},
"central": { "base_url": "https://mlops.example.com", "configured": true },
"policy": { "revision": 0, "heartbeat_interval_s": 5.0, "commands_poll_s": 10.0 }
}(일부 필드를 줄였습니다.) OpenAPI 문서는 에이전트의 /docs 에서 볼 수 있습니다.