> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worktruck.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> REST API at api.worktruck.app — chi+huma, OpenAPI-described, bearer-authenticated.

WorkTruck's HTTP API lives at `https://api.worktruck.app`. It's a chi+huma stack, fully OpenAPI 3.x described, and shipped behind tenant-scoped bearer authentication.

## Base URL

* **Production:** `https://api.worktruck.app`
* **OpenAPI document:** `https://api.worktruck.app/openapi.json`

## Authentication

Every request carries a bearer token in `Authorization: Bearer <token>`. Two token shapes work:

* **API keys** — long-lived, tenant-scoped. Prefix `wt_`. Most agent integrations use these.
* **Keycloak JWTs** — short-lived, issued via PKCE OAuth. The dashboard uses this path; agents typically don't.

Multi-tenant principals must additionally pass `X-Worktruck-Tenant-ID: <uuid>` to disambiguate. Single-tenant principals can omit it.

## Response envelope

Successes return the resource directly:

```json theme={null}
{ "id": "...", "display_name": "Alice", ... }
```

Errors return the canonical `{"error": {"code", "message"}}` envelope:

```json theme={null}
{ "error": { "code": "not_found", "message": "person not found" } }
```

## Backend stamp

Every response includes `X-Worktruck-Backend: go` so you can confirm at the wire layer that you've reached the Go service and not a stale path.

## Coming soon

A full endpoint catalog with request/response schemas is on the v1.x roadmap. Until then, the canonical reference is the live OpenAPI document at `/openapi.json` — the dashboard's `@worktruck/schema` package consumes it directly to generate TypeScript types.