Cloud API Reference

The Slate Tracker desktop agent talks to a small set of cloud endpoints. This page documents them in case you are building integrations, mirroring the cloud privately, or just curious about what the agent sends.

Base URL

https://api.slate-tracker.com/v1

All requests are HTTPS. The agent will refuse to talk to a plain HTTP host.

Authentication

Every request includes the license key in the Authorization header:

Authorization: Bearer stk_live_<your-key>

Keys are scoped to a single subscription and identify which seat is active. If a key has been released or revoked, the cloud returns 401 unauthorized and the agent enters offline preview mode.

Endpoints

POST /license/heartbeat

Called once a minute by every active agent.

Request:

{
  "machine_id": "stable-uuid-per-machine",
  "agent_version": "1.4.2",
  "os": "win11",
  "processed_today": 42
}

Response:

{
  "status": "active",
  "plan": "tour",
  "quota": {
    "used": 4830,
    "limit": 5000,
    "resets_at": "2026-06-01T00:00:00Z"
  }
}

POST /vision/read

Send a resized reference image and get back the parsed slate fields.

Request body is multipart:

• image: the resized image bytes.
• metadata (JSON):

{
  "filename": "IMG_0021.jpg",
  "captured_at": "2026-05-28T14:30:22Z",
  "context": {
    "previous_scene": "012",
    "previous_take": 3
  }
}

Response:

{
  "fields": {
    "scene": { "value": "012", "confidence": 96 },
    "take":  { "value": "4",   "confidence": 94 },
    "lens":  { "value": "35mm","confidence": 89 },
    "notes": { "value": "kitchen day", "confidence": 78 }
  },
  "model": "standard",
  "billable_units": 1
}

POST /corrections

Used by the review queue to record corrections. Improves future reads on similar slates.

Request:

{
  "original": { "scene": "12", "take": "4" },
  "corrected": { "scene": "012", "take": "4" },
  "image_hash": "sha256:0abc...",
  "machine_id": "stable-uuid-per-machine"
}

Response:

{ "ok": true, "history_length": 137 }

GET /downloads/latest

Used by the in app updater to find the latest agent build.

Query: ?os=win11 or ?os=macos14.

Response:

{
  "version": "1.4.3",
  "url": "https://downloads.slate-tracker.com/...",
  "sha256": "0abc...",
  "release_notes_url": "https://slate-tracker.com/releases/1.4.3"
}

GET /usage

Used by the cloud dashboard. Returns daily counts for the current period.

Response:

{
  "period_start": "2026-05-01T00:00:00Z",
  "period_end":   "2026-06-01T00:00:00Z",
  "daily": [
    { "date": "2026-05-27", "processed": 120, "reviewed": 14, "corrected": 3 }
  ]
}

Rate limits

• License heartbeats: one per minute per agent. Excess calls return 429 with a Retry-After header.
• Vision reads: governed by your monthly plan quota, not a per second limit. Bursts are fine.
• Corrections: one per second per agent.

Errors

All error responses use this shape:

{
  "error": {
    "code": "license_expired",
    "message": "Your subscription is past due. Update billing in the dashboard."
  }
}

Common codes:

• unauthorized: the key is missing, malformed, or revoked.
• license_expired: payment is past due.
• quota_exceeded: monthly image quota is used up.
• validation_failed: a request body field is missing or malformed.

Versioning

The agent talks to /v1 only. We will support /v1 for the lifetime of every agent build released against it. New features land in /v2 and require an agent upgrade to use.