> ## 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 JSON

> Download the OpenAPI 3.1 specification for this API converted to JSON.

Serves the same OpenAPI 3.1 document as
[Get OpenAPI YAML](/api-reference/operations/openapi-yaml), converted from
the embedded YAML to JSON once at process start. Use it with tooling that
expects JSON — code generators, request validators, API gateways. The
content is identical to the YAML form; only the encoding differs. No
authentication is required.

The conversion decodes the YAML into a generic map and re-encodes it with
Go's `json.Marshal`, so the body is a single compact line with object keys
in alphabetical order (`components`, `info`, `openapi`, `paths`,
`security`, `servers`, `tags`) rather than the authored order. Pipe it
through `jq .` if you want to read it.

## Example Request

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

## Response

`Content-Type: application/json`. The body is the specification document
itself — a bare OpenAPI object, not a `data` envelope. The excerpt below is
pretty-printed and abridged (`info.description`, `info.license`, `tags`,
every path but `/health`, the `/health` response `content` and `503`, the
`portalSession` and `sessionCookie` security schemes, and all of
`components.parameters`, `components.responses` and `components.schemas`
are omitted); the key order matches the real body, and every value shown
is verbatim.

```json theme={null}
{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "bearerFormat": "API key",
        "description": "Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "title": "Recurso API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/health": {
      "get": {
        "description": "Reports overall service health plus per-component status (Postgres, Redis, TigerBeetle).",
        "operationId": "getHealth",
        "responses": {
          "200": { "description": "Service is healthy (or degraded but serving)." }
        },
        "security": [],
        "summary": "Health check",
        "tags": ["System"]
      }
    }
  },
  "security": [{ "bearerAuth": [] }],
  "servers": [
    {
      "description": "Example deployment — substitute the base URL of your own Recurso deployment.",
      "url": "https://billing.example.com"
    }
  ]
}
```

## Errors

This endpoint has no failure modes of its own and always returns `200`. The
YAML-to-JSON conversion happens at boot and a conversion failure aborts
startup, so a running instance never serves a malformed document.


## OpenAPI

````yaml GET /openapi.json
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.json:
    get:
      tags:
        - System
      summary: This OpenAPI document (JSON)
      operationId: getOpenAPIJSON
      responses:
        '200':
          description: The OpenAPI 3.1 specification in JSON.
          content:
            application/json:
              schema:
                type: object
      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`.

````