Skip to content

API

Stub

This API is a stub and will change. It documents the device/fleet surface that exists today so early integrators know the shape of things. It is not yet a stability promise.

Authentication

Two credential types, both scoped and revocable:

  • Household API keys - created in the app, scoped per household (and optionally per capability). Sent as Authorization: Bearer <key>. Revoking a key takes effect fleet-wide within one heartbeat interval.
  • Device JWTs - issued to a device when it is claimed (see below), bound to the device keypair, used for heartbeats and artifact pulls.

There are no global keys. The blast radius of any leaked credential is one household.

Endpoints overview

Claim a device

POST /v1/claim

Pairs factory hardware to a household. The claim code comes from the QR card; the device generates its keypair on first boot and never reveals the private half.

Request:

{
  "claim_code": "OLS-7F3K-9Q2M",
  "device_pubkey": "BASE64_ED25519_PUBLIC_KEY",
  "device_type": "olsie-mini"
}

Response:

{
  "device_id": "dev_01J9XQ4R7C2M",
  "device_jwt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
}

Channel manifest

GET /v1/channels/{channel}/manifest

Returns the artifact set a device on dev, beta, or stable should be running. Promotion between channels re-points this manifest; artifacts themselves are immutable.

Response:

{
  "channel": "stable",
  "version": "1.4.2",
  "released_at": "2026-05-28T09:00:00Z",
  "artifacts": [
    {
      "key": "hub/voice-pipeline/1.4.2/image.tar",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "signature": "minisign:RWQf6LRCGA9i..."
    }
  ]
}

Presigned artifact download

POST /v1/artifacts/presign

Exchanges an artifact key from the manifest for a short-lived download URL. Devices verify the sha256 and signature after download; an unsigned or mismatched artifact is refused.

Request:

{
  "key": "hub/voice-pipeline/1.4.2/image.tar"
}

Response:

{
  "url": "https://artifacts.olsie.ai/hub/voice-pipeline/1.4.2/image.tar?X-Signature=...",
  "expires_at": "2026-06-10T12:15:00Z"
}

Heartbeat

POST /v1/heartbeat (device JWT)

Devices report version, uptime and basic health on a fixed interval. Outbound-only: this is the only way the fleet talks to us, and the response is the only way we talk back (it can carry a "check the manifest" hint).

Errors

Errors follow one shape:

{
  "error": {
    "code": "claim_code_expired",
    "message": "This claim code has expired. Generate a new one in the app."
  }
}