Problem statement / motivation
The agentic API currently exposes OpenAI-compatible Responses endpoints and Anthropic-compatible Messages endpoints, but there is no machine-readable OpenAPI document for client authors, tooling, or deployment integrations.
A published API contract would make the project easier for the community to discover, integrate, validate, and generate clients against.
Proposed solution
Add compile-time OpenAPI documentation generated from the Rust server, ideally exposed at a stable endpoint such as /openapi.json, with optional Swagger UI or another documentation frontend.
The initial contract should cover the stable HTTP surface, including:
/health and /ready/v1/models/v1/conversations/v1/responses/v1/responses/compact/v1/messages/v1/messages/count_tokens- authentication and common error envelopes
- JSON and SSE response shapes where applicable
The WebSocket form of /v1/responses can be documented separately if OpenAPI is not an appropriate representation.
A Rust-native solution such as utoipa/utoipa-axum could be evaluated, while preserving the existing proxy behavior and explicitly documenting fields that are intentionally extensible.
Alternatives considered
- Continue maintaining prose-only API documentation.
- Hand-maintain a standalone OpenAPI file, which would be more likely to drift from the Rust implementation.
- Use a different Rust OpenAPI library such as
aide.
Additional context
This is intended as a community-facing feature request and does not require an immediate implementation commitment. The generated document should describe the gateway's public contract, not expose internal executor or storage details.
Problem statement / motivation
The agentic API currently exposes OpenAI-compatible Responses endpoints and Anthropic-compatible Messages endpoints, but there is no machine-readable OpenAPI document for client authors, tooling, or deployment integrations.
A published API contract would make the project easier for the community to discover, integrate, validate, and generate clients against.
Proposed solution
Add compile-time OpenAPI documentation generated from the Rust server, ideally exposed at a stable endpoint such as
/openapi.json, with optional Swagger UI or another documentation frontend.The initial contract should cover the stable HTTP surface, including:
/healthand/ready/v1/models/v1/conversations/v1/responses/v1/responses/compact/v1/messages/v1/messages/count_tokensThe WebSocket form of
/v1/responsescan be documented separately if OpenAPI is not an appropriate representation.A Rust-native solution such as
utoipa/utoipa-axumcould be evaluated, while preserving the existing proxy behavior and explicitly documenting fields that are intentionally extensible.Alternatives considered
aide.Additional context
This is intended as a community-facing feature request and does not require an immediate implementation commitment. The generated document should describe the gateway's public contract, not expose internal executor or storage details.