# Contracts

## API OpenAPI Readiness

<!-- api-openapi-readiness:start -->

<!-- This section is auto-generated by scripts/generate-api-readiness-readme.mjs. Do not edit between the markers. -->

Snapshot generated from `packages/contracts/generated/api/readiness.json` after running `pnpm -C packages/contracts gen-api-contract-from-openapi`.

Are we OpenAPI ready? **No.** Current generated API contracts are **16.7% ready**.

| Surface   |   Ready | Not ready |   Total |   Ready % |
| --------- | ------: | --------: | ------: | --------: |
| console   |      96 |       474 |     570 |     16.8% |
| service   |      16 |        72 |      88 |     18.2% |
| web       |       5 |        36 |      41 |     12.2% |
| **total** | **117** |   **582** | **699** | **16.7%** |

Readiness here means the generated contract operation is not marked with:

> Generated contract types may be inaccurate because backend OpenAPI annotations are incomplete. Do not migrate callers until the generated contract is accurate.

Operations marked with that warning should not be migrated to blindly. Prefer fixing backend OpenAPI annotations first so the generated contract has accurate request and response types, then migrate callers endpoint by endpoint.

The current heuristic marks an operation as not ready when a request body or success response that should have a body contains a loose object type, or when an operation has no documented 2xx response. 204, 205, and 304 responses are treated as bodyless when the request type is otherwise accurate.

<!-- api-openapi-readiness:end -->

## How to Improve Readiness

Improve the ready percentage by fixing the backend annotations that produce loose generated types, then regenerating the contracts.

- Add accurate request body schemas for endpoints that currently generate loose object types.
- Add accurate 2xx response schemas for endpoints that return JSON payloads.
- Use 204 responses for endpoints that intentionally return no body.
- Avoid untyped dictionaries, raw objects, or `additionalProperties: true` responses unless the API really returns an arbitrary object.
- Regenerate with `pnpm -C packages/contracts gen-api-contract` and use this README to verify the updated percentage.

Do not remove the generated warning just to increase the number. The warning should disappear because the backend OpenAPI output became accurate enough for callers to migrate safely.
