Generated contract v1

API reference

440 runtime-validated operations share one Zod-backed registry with the OpenAPI document.

OpenAPI JSONBrowse operations

Generated reference

The API reference at /docs/api/reference and /public/openapi/v1.json are generated from the same Zod-backed route registry used for runtime request and response validation. The build rejects duplicate method/path registrations and schemas that cannot be represented safely.

API v1 is the first redesigned canonical contract, not an alias for the historical main-branch API. It has no numeric global agent ID and no silent chain-local coercion.

Serialization conventions

  • UUIDs are canonical lowercase strings.
  • Economic quantities, heights, slots, nonces, uint-sized values, and large counters are decimal strings.
  • Scores, ratios, and confidence are integer ppm.
  • Timestamps are RFC 3339 UTC.
  • Unknown is null or absent; zero is measured zero.
  • Public URLs are HTTPS in production.

Compatibility policy

Additive optional fields may ship within v1. Removing a field, adding a required field, contracting an enum, or changing semantics requires a new API version. Deprecations are announced in this documentation and changelog and include response headers during a bounded support period.

Protocol-specific fields live in typed subresources or discriminated unions. Internal workspace/admin DTOs are not public schemas. Only operations present in the generated reference are released; roadmap designs are deliberately absent.

Download and validate the current document:

bash
curl --fail-with-body --etag-save openapi.etag \
  --output openapi-v1.json \
  'https://agentranking.io/public/openapi/v1.json'