> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruddr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI Specification

> Download and use the Ruddr API OpenAPI 3.1 spec

The Ruddr API publishes a complete [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) specification. You can use it for client generation, API exploration, testing, and validation.

## Variants

Two variants of the spec are available:

<CardGroup cols={2}>
  <Card title="Bundled" icon="cube" href="/openapi.json" target="_blank">
    **openapi.json** — Uses internal `$ref` references to shared schemas in `#/components/`. Best for tools that resolve
    `$ref` natively, such as Swagger UI, Redocly, and most code generators.
  </Card>

  <Card title="Dereferenced" icon="file-code" href="/openapi-deref.json" target="_blank">
    **openapi-deref.json** — Fully inlined with no `$ref` pointers. Every schema is expanded at point of use. Best for
    tools that don't handle `$ref` well, or for direct inspection and scripting.
  </Card>
</CardGroup>

## Use Cases

* **Client generation** — Feed the spec to [OpenAPI Generator](https://openapi-generator.tech/) or similar tools to generate typed API clients in your language of choice.
* **API exploration** — Import into Postman, Insomnia, or any OpenAPI-compatible tool to browse endpoints and try requests.
* **Testing and validation** — Validate request/response payloads against the spec in your test suite.
* **Documentation** — The API Reference in these docs is generated directly from the bundled spec.

## Shared Schemas

The bundled spec defines reusable components under `#/components/`:

* **Resource schemas** (`components/schemas`) — Named response shapes for each resource (e.g., `Client`, `Project`, `Member`). All endpoints returning a resource reference the same schema.
* **Error schemas** (`components/schemas`) — `ErrorResponse` and `ValidationErrorResponse` for consistent error handling.
* **Pagination parameters** (`components/parameters`) — `StartingAfter`, `EndingBefore`, and `Limit` used by all list endpoints.

In the dereferenced variant, these are inlined everywhere they're used.