API Reference

The Workloom registry API is a Hono-based HTTP server with automatic OpenAPI 3.1 spec generation via @hono/zod-openapi. The live spec is always available at GET /v1/openapi.json.

Base URL

Environment	URL
Development	http://localhost:4050/v1
Production	Configured per deployment

Authentication

All endpoints (except health and OpenAPI spec) require a Bearer token in the Authorization header:

Authorization: Bearer <token>

Auth Methods

Method	Use case	Endpoint
Device Login	CLI interactive login	POST /v1/auth/device/start
OIDC	Web app browser-based login	GET /v1/auth/oidc/authorize
CI Token	Automated pipeline access	POST /v1/auth/ci-token

SAML and service accounts were removed.

Device Login Flow (CLI)

# 1. Start device login
curl -X POST http://localhost:4050/v1/auth/device/start

# Response: { "deviceCode": "...", "userCode": "...", "verificationUri": "..." }

# 2. User visits verificationUri and enters userCode

# 3. Poll for completion
curl -X POST http://localhost:4050/v1/auth/device/complete \
  -H "Content-Type: application/json" \
  -d '{"deviceCode": "..."}'

# Response: { "token": "wl_...", "role": "user" }

OIDC Flow (Web App)

The web app authenticates against Supabase's OAuth server, brokered by the API (API-mediated OIDC with PKCE). The API exchanges the code, verifies the ES256 id_token against Supabase JWKS, and issues a wl_ session token:

• Authorize: GET /v1/auth/oidc/authorize (returns a Supabase authorize URL)
• Callback: POST /v1/auth/oidc/callback (exchanges the code for a wl_ token)

The user signs in to Supabase (email/password) and approves consent before the callback. See the full flow in the authentication docs.

Endpoints

Health

Method	Path	Auth	Description
GET	/v1/health	No	Server health and registry hash
GET	/v1/openapi.json	No	OpenAPI 3.1 specification

Packages

Method	Path	Auth	Description
GET	/v1/packages	user	List published packages
GET	/v1/packages/:name/:version	user	Get specific package version
POST	/v1/packages/draft	user	Create a draft package
POST	/v1/packages/:name/:version/publish	admin	Publish a draft package
POST	/v1/packages/:name/:version/approve	admin	Approve a package

Workspaces

Method	Path	Auth	Description
GET	/v1/workspaces/revisions	user	List all workspace revisions
POST	/v1/workspaces/revisions	user	Create a workspace revision
GET	/v1/workspaces/:id	user	Get workspace revision by ID
GET	/v1/workspaces/:id/current	user	Get current workspace revision

Approvals

Method	Path	Auth	Description
GET	/v1/approvals	admin	List pending approvals

Objects

Method	Path	Auth	Description
PUT	/v1/objects/:hash	user	Upload object (returns 201 + ETag)
GET	/v1/objects/:hash	user	Download object (supports Range)

Telemetry

Method	Path	Auth	Description
POST	/v1/telemetry/ingest	user	Ingest telemetry events
GET	/v1/telemetry/dashboard	user	Telemetry dashboard summary

Audit

Method	Path	Auth	Description
GET	/v1/audit	admin	Query audit event log

Generated Client Usage

The @workloom/workloom-api package provides type-safe access to all endpoints via generated React Query hooks and client functions.

React Query Hooks (Web App)

import { useListPackages, useGetPackage } from "@workloom/workloom-api";

function PackageList() {
  const { data, isLoading } = useListPackages({
    client: { headers: { Authorization: `Bearer ${token}` } },
    query: { enabled: !!token },
  });

  return <ul>{data?.map(pkg => <li key={pkg.name}>{pkg.name}</li>)}</ul>;
}

Client Functions (CLI / Server-side)

import { listPackages, getPackage } from '@workloom/workloom-api'
import { setAuthToken } from '@workloom/fetch-client'

setAuthToken('wl_abc123...')

const packages = await listPackages()
const pkg = await getPackage({ name: 'my-package', version: '1.0.0' })

Non-Standard Responses

Three endpoints have non-standard response formats:

Endpoint	Behavior
PUT /v1/objects/:hash	Returns 201 with ETag header
GET /v1/objects/:hash	Supports Range header, returns 206 with Content-Range

CORS

The API includes CORS middleware allowing requests from the web app origin. Allowed headers: Authorization, Content-Type, X-Workloom-SHA256.