# HTTP contracts

`site-execution.v1.yaml` defines the six Site execution start/cancel messages as
OpenAPI components. Its `paths` is empty: 1C establishes the message contract;
Site transport and delivery are implemented in Task 4.

`site-coordination.v1.yaml` adds command drafts, paginated command reads and typed
success/failure results. It references the six existing execution schemas.
Site Coordination assigns sequences and stores commands/results in its private
database. Its `paths` also remains empty until authenticated Runtime transport.

Batch observations may include an optional bounded `failure` after terminal
failure and confirmed cleanup. It carries stage, opaque native job/state and
separate process/derived-step exit facts. Existing observations and stored
outcomes retain their shape, and existing Protobuf Run fields carry the member
summary without new wire identities. Upgrade Site API and Execution Core before
the Runtime: older strict Site consumers reject the added field. This does not
retroactively enrich already terminal Runs.

`site-ssh-access.v1.yaml` declares the SSH access agent's `pull`, `snapshot` and
`acknowledge` routes with native bearer authentication; the Site comes from the
credential's grant. See the [SSH Access context](../../services/metallo/contexts/ssh_access/README.md).

`scripts/generate_site_execution.py` generates the three sets of strict Python transport models in
Metallo's generated adaptors with pinned tooling. `pnpm generate:contracts`
regenerates them; `pnpm verify` checks drift. Application DTOs have no generated
model dependency. The owning Execution Core codec additionally checks cross-field
rules, canonical identities, non-null fields and duplicate JSON keys.

`api.openapi.json` is the Go API's browser-facing contract. Each business path
references its owning context's fragment under `contracts/<context>/http_api/`,
names that context in `x-owner` and has an `operationId`. Shared errors live in
`contracts/shared/http_api/`; Execution Core's routes keep Themelio's `{error, code}`
errors and per-parameter 400 body. `scripts/http_contracts.py` bundles the fragments into
the API's embedded copy and generates the browser's tagged Orval client;
`pnpm generate:contracts` regenerates both and `pnpm verify` checks drift. The API
registers only declared business operations, each through a typed binding.
Technical AAI paths use the same browser document and their dedicated API adaptor.
An empty `security` list marks an operation as needing no session, and a list
holding only `CLIKey` marks it operator-only: a browser session is refused with
`403 operator_only`. Commands are `POST` operations on their target's `{id}` and
carry the shared headers in `contracts/shared/http_api/parameters.json`
(`Idempotency-Key`, `If-Match`, `X-Correlation-ID`); they answer the shared
`CommandOutcome`. Support's tickets, messages and customer links are in
[`contracts/support/http_api`](../support/http_api). See the
[browser client guide](../../docs/openapi-client.md).

The [Project member and invitation preview](../project/http_api/member-invitation-preview/README.md)
is an agreed standalone frontend contract with generated clients and Go API
fixture bindings. Explicit development configuration serves its examples through
the normal authenticated HTTP path. Its default API activation accompanies the
backend implementation.

`llm-access.v1.yaml` is owned by LLM Access and defines what the Waldur Site Agent sends for an order and
what it reads back: one order message with a request ID, a result, and the allocation status that says when the
gateway matches. `scripts/generate_site_execution.py` generates `llm_access_http.py` from it with the other
owned HTTP contracts. Its paths are mounted only when `LLM_ACCESS_INTAKE_KEY` is set (the usage path also needs
`LLM_ACCESS_USAGE_KEY`, and the members and member-revocation paths `LLM_ACCESS_SEAL_KEY` with key issuing), under their own credential
(see the context README).