Search documentation
Browse Awaken Agents docs ›

On this page

Docs/Awaken Agentsv1.0.0-dev/Reference/ReferenceGenerate and verify the management API contract
Note·You're reading pre-release documentation (v1.0.0-dev). Interfaces and behavior may change before a stable release.

Reference · Reference

Generate and verify the management API contract

What this page covers

Generate one OpenAPI 3.1 artifact from the management wire types, prove that it matches the mounted router, and pin it beside every client.

Use contracts/openapi.generated.json when you need to inspect a management request, generate a client, or review an API change. It is generated from the Rust wire types and checked against the router that the process actually mounts. Do not copy its fields or operations into another reference.

The artifact is ready to consume only when both checks below pass:

scripts/contract/generate-contracts.sh --check
cargo test -p awaken-admin-config-api --features schema --test openapi_contract

The first command proves that the committed artifact matches the generator. The second proves that the document and the mounted router agree in both directions.

Choose the owning contract

You needUse
Exact /v1/config/* fields and operationscontracts/openapi.generated.json
All application route familiesHTTP API
Managed Agents request and response typesthe tested Anthropic SDK plus compatibility
AI SDK, AG-UI, A2A, ACP, or MCP payloadsthe matching protocol page

The generated contract covers provider connections, executable models, credentials, pools, inference profiles, resolution, and Agent resource bindings below /v1/config/*. Other surfaces keep their existing owners.

Static generation chain

flowchart LR
  W["Rust wire types"] --> G["OpenAPI generator"]
  R["Mounted management router"] --> P["Bidirectional parity test"]
  G --> O["contracts/openapi.generated.json"]
  O --> P
  P --> C["Console types / SDKs / reference renderers"]

The wire types own schemas, the route registry owns operations, and the parity test prevents either side from becoming a second, incomplete API.

Change the contract

From the Awaken source checkout, regenerate the complete contract bundle:

scripts/contract/generate-contracts.sh

The script writes the OpenAPI document, JSON Schemas, and TypeScript types from the same source. The OpenAPI document declares 3.1.0. Do not edit any generated artifact by hand.

Then run the two checks from the opening. Their failure meanings are distinct:

Check resultMeaningNext action
--check reports a stale artifactsource and committed generated files differregenerate, review the generated diff, and rerun the check
a documented operation returns routing 404 or 405the document names an operation the router does not mountcorrect the route registry or mount before publishing
a mounted operation is absentthe running API has no generated contract entryadd it to the registry before generating clients
a schema reference does not resolvethe generated component graph is incompletecorrect the wire schema or generator

These are change-gate failures, not runtime incidents. No action is needed when both checks pass and a consumer can read the pinned artifact.

Consume the artifact

npx @redocly/cli lint contracts/openapi.generated.json
npx openapi-typescript contracts/openapi.generated.json -o management-api.d.ts

These commands are consumers, not additional contract owners. Pin the Awaken source revision alongside generated clients so a deployment can reproduce the exact schema it used.