# Lizzy API documentation

> Build, operate, and diagnose a complete model-distillation workflow on Lizzy. The API origin is https://lizzy.albinilabs.com and the versioned REST base is /v1.

## Agent version

- [Agent documentation](https://lizzy.albinilabs.com/docs/agent): machine-first source order, control-surface boundary, bounded execution loop, stop conditions, and conflict resolution.
- [Full agent context](https://lizzy.albinilabs.com/docs/llms-full.txt): consolidated lifecycle contract for a tool-using AI runtime.
- [MCP server](https://lizzy.albinilabs.com/docs/mcp): connect a remote MCP client to `POST https://lizzy.albinilabs.com/v1/mcp` with a test or live `full_access` API token.
- [Pilot execution playbook](https://lizzy.albinilabs.com/docs/agent-playbook.md): typed-tool policy for Pilot. Do not apply its approval behavior to a standalone REST client.

## Start here

- [Quickstart](https://lizzy.albinilabs.com/docs/start): verify a test token, create a Distill loop, and retry without creating duplicates.
- [Core concepts](https://lizzy.albinilabs.com/docs/concepts): resource graph, test/live isolation, async handles, and authority boundaries.
- [Authentication](https://lizzy.albinilabs.com/docs/auth): server-side tokens, scopes, mode, verification, and rotation.
- [End-to-end example](https://lizzy.albinilabs.com/docs/example): one connected capture-to-shadow implementation.

## Build a Distill workflow

- [Capture traffic](https://lizzy.albinilabs.com/docs/capture): managed and BYOK sources, the teacher catalog, OpenAI-compatible proxying, billing, metadata, feedback, and retention.
- [Datasets](https://lizzy.albinilabs.com/docs/datasets): captured-call filters, connectors, multipart JSONL, and immutable versions.
- [Rewards](https://lizzy.albinilabs.com/docs/rewards): verifier, judge, webhook, and feedback signals with test cases.
- [Training](https://lizzy.albinilabs.com/docs/training): recipe proposal, live-mode dry run, plan hash, approval, and run monitoring.
- [Results](https://lizzy.albinilabs.com/docs/results): run state, supported metric series, reports, examples, and student artifacts.
- [Serving](https://lizzy.albinilabs.com/docs/serving): shadow, percent, full, fallback, health, and retirement.

## Operate and diagnose

- [Pilot copilot](https://lizzy.albinilabs.com/docs/pilot): resumable workflow phases, human handoffs, approval boundaries, and no-progress stops.
- [MCP server](https://lizzy.albinilabs.com/docs/mcp): client configuration, tools, shared workflow phases, token authority, and limits.
- [Webhooks](https://lizzy.albinilabs.com/docs/webhooks): signed event delivery, retries, deduplication, and redelivery.
- [API conventions](https://lizzy.albinilabs.com/docs/api): headers, cursor pagination, exact-byte idempotency, async resources, and contract metadata.
- [Errors and recovery](https://lizzy.albinilabs.com/docs/errors): failure layers, stable codes, correlation IDs, and recovery playbooks.
- [Changelog](https://lizzy.albinilabs.com/docs/changelog): compatibility and contract changes.

## Machine-readable contracts

- [OpenAPI 3.1](https://lizzy.albinilabs.com/v1/openapi.json): public API schema. Distill operations include workflow stage, prerequisites, async terminal states, recovery guidance, human-only policy, authentication requirements, and idempotency metadata.
- [Managed teacher catalog](https://lizzy.albinilabs.com/v1/distill/teachers): current managed model IDs and the USD-per-million-token rates actually billed. Requires bearer authentication with `distill:read`.
- [Remote MCP](https://lizzy.albinilabs.com/v1/mcp): stateless Streamable HTTP endpoint. Send JSON-RPC by POST with a `full_access` bearer token; responses are JSON and sessionless.
- [Event type catalog](https://lizzy.albinilabs.com/v1/event_types): supported exact and wildcard webhook subscriptions.
- [Pilot execution playbook](https://lizzy.albinilabs.com/docs/agent-playbook.md): the version-pinned, agent-safe lifecycle companion used before Pilot selects a typed workflow action. It contains no credentials, raw API commands, or upload bytes.

## Non-negotiable integration rules

1. Keep `lz_test_*`, `lz_live_*`, upstream, connector, and webhook secrets on a trusted server and out of model context.
2. Treat token mode as a data boundary. Test artifacts cannot authorize live training.
3. Persist every resource ID before polling. A local watch timeout is not a failed resource and must not create replacement work.
4. Reuse one globally unique idempotency key with byte-identical JSON after an unknown write outcome. Never rotate the key merely because the response was lost.
5. A standalone REST client owns its human approval gate. Pilot adds approvals inside Lizzy; direct live REST mutations execute immediately when authorized.
6. Branch on stable `error.code`, retain `X-Request-Id`, and distinguish BYOK passthrough responses from managed `teacher_unavailable` errors.
7. Use explicit reward IDs. An omitted rewards field has compatibility behavior and is not the same as an empty list.
8. Use a succeeded dry run made with the live credential, then preserve dataset version, recipe, budget, and compute when sending `validated_dry_run` and `plan_hash`.
9. Require a live publish stage to produce a serveable student. Dry runs never publish one.
10. Start serving in shadow, keep a resolvable teacher fallback, and change one rollout boundary at a time.
11. Choose the source kind explicitly. `kind: "managed"` uses a catalog `teacher_model` without a provider key and bills live calls at catalog rates; `kind: "byok"` keeps `base_url` and `upstream_key`, forwards calls verbatim, and records captured cost as zero.