Get started

API / Cookbook / 01

Send transcripts from a machine

Each machine gets its own revocable credential, then sends batches to Tracez. A batch stays on disk until a receipt proves it was committed, so a dropped connection never loses or doubles a turn.

RESTLive

Enroll once, then send
actor you: You
actor cli: recurz-collector
actor id: id.recurz.ai
actor api: Tracez API
you -> cli: recurz
cli -> id: browser sign-in
id --> cli: your access token
note cli: make a device secret on disk
cli -> id: POST /v1/devices {secret_sha256}
cli -> id: POST /v1/token (device secret)
id --> cli: five-minute device token
cli -> api: POST /api/collector/device
api --> cli: 201 registered
loop for each batch
cli -> api: POST /api/collector/ingest (turns-v1)
api --> cli: receipt {batch_id, accepted, turns}
note cli: receipt matches, so mark the turns sent
end

Steps

  1. Install and sign in

    On a Mac, you can also open the Collectorz menu-bar app and choose Sign in & set up. From a terminal on macOS or Linux:

    npm install -g @recurz/cli
recurz

    npm puts recurz and recurz-collector on your PATH. The first recurz run signs you in at id.recurz.ai in the browser, enrolls the machine and starts the background collector.

  2. What enrollment sends

    The collector makes the device secret itself and sends identityz only its SHA-256. It then trades the secret for a five-minute device token and registers the device with Tracez, which binds it to the host.

    POST https://id.recurz.ai/v1/devices
Authorization: Bearer <your access token>

{"kind":"device","name":"build-box","host":"build-box","secret_sha256":"SHA256_OF_SECRET"}

POST https://tracez.recurz.ai/api/collector/device
Authorization: Bearer <device token>

{"host":"build-box","name":"build-box","ingest":"https"}

  3. Send batches

    A batch holds up to 200 turns and 8 MiB, and keeps the same batch_id across retries, so a resend never doubles a turn.

    POST https://tracez.recurz.ai/api/collector/ingest
Authorization: Bearer <device token>
X-Baud-Format: turns-v1

    A receipt says accepted: true only after the transcript transaction commits. Check its batch_id and turn count before treating the turns as sent.

  4. Check and revoke

    recurz status
recurz-collector devices
recurz-collector revoke DEVICE_ID

    Over the API, GET /api/ingestion shows recent receipts and each device's last-seen time. Revoking a device at identityz cuts the machine off within five minutes.