Userz

Engine + Harness API

The Userz engine — the Signal/Directive graph, its connection engine, and promotion — is the moat; harnesses are a commodity. This public API exposes the engine and a harness execution surface so you can build your own harness on us. Our own renderer consumes this exact contract.

Authentication + versioning

Authenticate every request with an org-scoped secret key as a bearer token (Authorization: Bearer sk_…) — including WebSocket connections, which send the same header on the upgrade. A key in the URL (?key=sk_…) is no longer accepted: it would land in access logs, proxy logs and browser history. Every request is org-scoped — a foreign id returns 404, never another org's data.

The API is date-versioned via X-Userz-Api-Version.

Engine endpoints

Read/write Signals, query the signal graph (the part no competitor exposes), CRUD + promote Directives, and observe the engine event stream. The Engine API is served at https://engine.{domain} — engine. on every environment’s domain.

All 433 endpoints are listed in the Engine API reference, generated from the engine’s own route table so it cannot drift.

Taking work as a harness

A harness links as a machine (POST /v1/harness/register), listens on the engine event stream (GET /v1/stream, WebSocket), claims a Directive, and reports its lifecycle back. The run itself happens on your machine, with your agent.

The intake host

Data coming in has its own host, https://api.{domain}: the feedback widget (pub_…), the browser SDK’s endpoints, connector webhooks, signal intake (/v1/ingest/…, POST /v1/signals) and AI passthrough, plus the customer routes @userz-ai/api wraps. They are not Engine API operations; the intake reference lists them.

Headless harness-host endpoints

A headless harness-host — the Userz harness running as a server, not inside the desktop app — serves these routes itself, not the engine API. For a run its own local dispatch started, stream the canonical ProviderRuntimeEvents, answer approvals, interrupt, fetch artifacts and open the pull request — identical across every provider.

GET/v1/harness/runs/:id/stream (WS)Auth: Bearer sk_ · directives:read
POST/v1/harness/runs/:id/approvalsAuth: sk_ · directives:control
POST/v1/harness/runs/:id/interruptAuth: sk_ · directives:control
GET/v1/harness/runs/:id/artifactsAuth: sk_ · directives:read
POST/v1/harness/runs/:id/prAuth: sk_ · directives:control

Reference + schemas

  • Endpoint reference: Engine + Harness API, with the canonical field-level schemas generated directly from the contract (so they cannot drift).
  • The ProviderRuntimeEvent union — session / thread / turn / item / request / approval — is the same shape across every provider and path.