한국어

Local API

Reference for the HTTP API the agent opens on the device (port 8600).

The agent opens an HTTP API on api.host:api.port (default 0.0.0.0:8600). A tablet screen on site, other programs on the same LAN, and CLI commands such as geo-mlops-edge status all use this API. Edge PCs usually have no screen, so you check the device's state through this API.

Authentication

  • When api.token is empty, there is no authentication (the default). Anyone on the same LAN can use it. This default lets site tablets see whether the line is collecting without handing a token to each one.
  • When you set api.token, every request needs the X-Edge-Api-Token header; a wrong one gets 401 invalid api token.
  • GET /health is always open regardless of the token (for load balancer and container health checks).
# Set the token (environment variable recommended)
GEO_EDGE_API__TOKEN=<your-secret>

curl -H 'X-Edge-Api-Token: <your-secret>' http://edge-pc:8600/api/v1/status

File (/blobs), push and inference (/inference) request bodies over api.max_body_bytes (default 2 GiB) are rejected with 413. This keeps one misdirected upload to an unauthenticated API from bringing the device down.

Endpoints

MethodPathWhat it does
GET/healthLiveness. No token needed. {"status":"ok","version":"0.3.0"}
GET/api/v1/statusDevice, link, backlog, sync, models, collectors, resources and attention all at once
GET/api/v1/resourcescpu / gpu / mem / disk utilization (%), per-GPU utilization gpus
GET/api/v1/queueQueued items. state (pending, uploading, failed), kind, limit (1–500, default 50), offset
DELETE/api/v1/queue/{id}Drop one item
POST/api/v1/recordsPush a record without a declaration. Body {"kind", "payload", "priority"}
POST/api/v1/blobsPush a file without a declaration. The body is the file itself. Query kind, filename, priority, dataset_id
PUT/api/v1/collectors/{name}/records/{id}Add a record to a declared push collector. Body {"payload", "ts"}. 201 newly stored / 200 duplicate
GET/api/v1/syncUploader state
POST/api/v1/sync:runSend now
POST/api/v1/sync:retry-failedPut items folded into failed back into the queue
GET/api/v1/modelsCached models and the active model
POST/api/v1/models/{name}:pullBody {"version", "activate"} — pull (activates by default). On failure, 502 with the cause in detail
POST/api/v1/models/{name}:activateBody {"version"} — switch to this version
DELETE/api/v1/models/{name}?version=Delete one version from the cache. Unloads that model name from memory first, even if another version is running
POST/api/v1/inferenceRun the active model on an image — Models and inference
GET/api/v1/settingsDevice info, Central address, the policy in effect, policy_source, data_dir, the collector list (tokens left out, only whether they are configured)
GET/api/v1/eventsServer-sent events (SSE): link · sync · queue · model · command …

A file sent with dataset_id is registered as a file of that dataset once Central finishes assembling it, and goes through the same validation as a web upload. For a missing dataset or one in another tenant, Central answers 404; the agent retries that file and marks it failed on the 20th failure. A file sent without one is kept apart from datasets, under Collected data.

Examples

See failed items in the queue

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": {} }
}

When there are items, attempts (number of tries) and last_error (the last error) come with them.

Subscribe to events

curl -N http://127.0.0.1:8600/api/v1/events?history=20
event: <kind>
data: {"kind": "<kind>", "name": "<event name>", "ts": "<ISO time>", "data": {...}}

Right after connecting it first sends the last history events (default 20, maximum 200), so a freshly opened screen does not sit empty.

Check the settings

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.3.0"
  },
  "central": { "base_url": "https://mlops.example.com", "configured": true },
  "policy": { "revision": 0, "heartbeat_interval_s": 5.0, "commands_poll_s": 10.0 }
}

(Some fields are omitted.) The OpenAPI docs are at the agent's /docs.

Written for the platform as of 2026-10-02.

© MLOps Central Platform