For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/contracts/http/README.md.

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.

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. See the browser client guide.

The Project member and invitation preview 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).

Page source

Source snapshot · Revision f928834c8.