Agent API

The agent talks to one endpoint. It pushes state and pulls work in the same call, which keeps the agent small and the firewall simple.

Endpoints

Both verbs accept a query parameter with a short random value; the server uses it only for cache busting and does not persist it.

Conventions

• Requests and responses use Content-Type: application/json.
• The agent identifies itself with a SlatefieldAgent/<version> user agent.
• Session state travels in the slate_device cookie.
• Errors return a JSON object with code and message.
• Retries use exponential backoff with jitter, capped at 15 minutes.

Check in and submit

The agent posts its state and any queued results. The response carries the interval it should wait before the next call.

POST /v2/sync.json
Content-Type: application/json

{"status":"ok","uptime_seconds":18422,"results":[]}

200 OK
{"next_poll_seconds":300}

The returned next_poll_seconds is a target, not a deadline. Agents apply jitter of up to 20% so a large fleet does not check in at the same instant.

Fetch work

GET /v2/sync.json?device=ws-0142

200 OK
{"tasks":[],"next_poll_seconds":300}

Enrollment

A device enrolls by posting its short-lived enrollment token on its first check-in. The server returns a device identity, which replaces the token for all later calls.

Errors

{"error":{"code":"rate_limited","message":"too many requests"}}