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

# Get OpenAPI YAML

> Download the OpenAPI 3.1 specification for this API, as authored, in YAML.

Serves the OpenAPI 3.1 document that describes every route on this
instance, exactly as authored. The spec is embedded into the binary at build
time, so what you download always matches the code that is running — it is
the same file this reference is generated from and the source the SDKs are
kept in sync with. No authentication is required. For the same document as
JSON, use [Get OpenAPI JSON](/api-reference/operations/openapi-json); to
confirm which build you are reading, pair it with
[Get Version](/api-reference/operations/version).

## Example Request

```bash theme={null}
curl https://api.recurso.dev/openapi.yaml -o recurso-openapi.yaml
```

## Response

`Content-Type: application/yaml`. The body is the specification document
itself, byte-for-byte as authored, not a JSON envelope. The excerpt below
is abridged — `# …` comments mark where the real document continues — but
every line shown is verbatim.

```yaml theme={null}
openapi: 3.1.0
info:
  title: Recurso API
  version: 1.0.0
  # … description and license
servers:
  - url: https://billing.example.com
    description: Example deployment — substitute the base URL of your own Recurso deployment.

security:
  - bearerAuth: []

# … tags

paths:
  /health:
    get:
      operationId: getHealth
      tags: [System]
      summary: Health check
      description: Reports overall service health plus per-component status (Postgres, Redis, TigerBeetle).
      security: []
      responses:
        '200':
          description: Service is healthy (or degraded but serving).
          # … content, and the '503' response
  # … every other path
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`.
    # … portalSession and sessionCookie
  # … parameters, responses and schemas
```

## Errors

This endpoint has no failure modes of its own and always returns `200`. A
build whose embedded spec fails to parse does not start, so a running
instance always has a valid document to serve.


## OpenAPI

````yaml GET /openapi.yaml
openapi: 3.1.0
info:
  title: Recurso API
  version: 1.0.0
  description: |
    The Recurso billing engine REST API.

    Authenticate by passing your API key as a bearer token:

        Authorization: Bearer <api_key>

    Obtain an API key by registering a tenant via `POST /auth/register`.
    All authenticated endpoints live under the `/v1` prefix. Mutating
    endpoints support idempotency via the `Idempotency-Key` header.
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://billing.example.com
    description: >-
      Example deployment — substitute the base URL of your own Recurso
      deployment.
security:
  - bearerAuth: []
tags:
  - name: System
    description: Health, version, and API metadata
  - name: Auth
    description: Tenant registration
  - name: Plans
    description: Product catalog plans
  - name: Customers
    description: Customer management
  - name: Subscriptions
    description: Subscription lifecycle
  - name: Invoices
    description: Invoices, PDFs, and Indian GST e-invoicing
  - name: Coupons
    description: Discounts
  - name: Usage
    description: Metered usage events
  - name: Credit Notes
    description: Customer credits
  - name: Quotes
    description: Quote-to-invoice lifecycle
  - name: Webhooks
    description: Webhook endpoint management and event feed
  - name: Analytics
    description: Revenue analytics
  - name: Checkout
    description: Public hosted checkout for invoices
  - name: Payments
    description: Payment order creation
  - name: Inbound Webhooks
    description: Receivers for payment-gateway callbacks (Razorpay, Stripe)
  - name: Customer Portal
    description: Customer-facing portal — magic-link auth and session-scoped data
  - name: Developer
    description: API key management
  - name: Account
    description: Tenant account settings
  - name: Finance
    description: Ledger accounts, entries, reconciliation, and revenue recognition
  - name: Settings
    description: Tax (GST) and e-invoicing (IRP) configuration
  - name: Consents
    description: Consent records for RBI-compliant recurring billing
  - name: Referrals
    description: Customer referral program
  - name: Gifts
    description: Gift subscriptions
  - name: Mandates
    description: UPI Autopay mandates
  - name: Offline Payments
    description: Virtual accounts and manually recorded payments
  - name: Organizations
    description: Multi-entity organizations grouping several tenants
  - name: Accounting
    description: QuickBooks / Xero accounting integrations
  - name: Churn
    description: Churn risk scoring and alerts
  - name: Cancel Flows
    description: Configurable retention flows shown at cancellation time
  - name: Dunning
    description: Dunning analytics and multi-channel dunning campaigns
paths:
  /openapi.yaml:
    get:
      tags:
        - System
      summary: This OpenAPI document (YAML)
      operationId: getOpenAPIYAML
      responses:
        '200':
          description: The OpenAPI 3.1 specification in YAML.
          content:
            application/yaml:
              schema:
                type: string
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Tenant API key obtained from `POST /auth/register` or `POST
        /v1/developer/keys`.

````