# 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://docs.lizzy.albinilabs.com/agent): machine-first source order, control-surface boundary, bounded execution loop, stop conditions, and conflict resolution.
- [Full agent context](https://docs.lizzy.albinilabs.com/llms-full.txt): consolidated lifecycle contract for a tool-using AI runtime.
- [Pilot execution playbook](https://docs.lizzy.albinilabs.com/agent-playbook.md): typed-tool policy for Pilot. Do not apply its approval behavior to a standalone REST client.

## Start here

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

## Build a Distill workflow

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

## Operate and diagnose

- [Pilot copilot](https://docs.lizzy.albinilabs.com/pilot): resumable workflow phases, human handoffs, approval boundaries, and no-progress stops.
- [Webhooks](https://docs.lizzy.albinilabs.com/webhooks): signed event delivery, retries, deduplication, and redelivery.
- [API conventions](https://docs.lizzy.albinilabs.com/api): headers, cursor pagination, exact-byte idempotency, async resources, and contract metadata.
- [Errors and recovery](https://docs.lizzy.albinilabs.com/errors): failure layers, stable codes, correlation IDs, and recovery playbooks.
- [Changelog](https://docs.lizzy.albinilabs.com/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.
- [Event type catalog](https://lizzy.albinilabs.com/v1/event_types): supported exact and wildcard webhook subscriptions.
- [Pilot execution playbook](https://docs.lizzy.albinilabs.com/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 Lizzy envelopes from upstream proxy responses.
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.