> ## 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 Health
> Report overall service health plus per-component status for Postgres, Redis and TigerBeetle.
The liveness and readiness probe for a Recurso instance. It pings Postgres,
pings Redis when the process connected to one at boot, and reports the
boot-time TigerBeetle connection state, then rolls the two pings up into a
single `status`. No
authentication is required, and the response never includes the underlying
error — component failures are logged server-side only, so a public probe
cannot leak connection details. Point your uptime monitor at this endpoint
(see [Monitoring and Alerting](/going-to-production#7-monitoring-and-alerting-checklist)).
For the build identifier alone, use [Get Version](/api-reference/operations/version);
for scrape-style telemetry, use [Get Prometheus Metrics](/api-reference/operations/metrics).
The HTTP status follows the system of record. Postgres down returns `503`
with `status: "degraded"`. Redis down (locking and rate-limit degrade, money
paths still work) returns `200` with `status: "degraded"`. A disconnected
TigerBeetle (the Postgres ledger is authoritative; TigerBeetle is an
optional accelerator) does not touch `status` at all — with Postgres and
Redis up you get `200` and `status: "ok"` alongside
`components.tigerbeetle.status: "disconnected"`. Read `components` for the
detail.
## Example Request
```bash theme={null}
curl https://api.recurso.dev/health
```
## Response
Returned bare — no `data` envelope.
```json theme={null}
{
"status": "ok",
"version": "v0.14.0",
"components": {
"postgres": { "status": "up" },
"redis": { "status": "up" },
"tigerbeetle": { "status": "connected" }
}
}
```
When Postgres is unreachable the same shape comes back with HTTP `503`:
```json theme={null}
{
"status": "degraded",
"version": "v0.14.0",
"components": {
"postgres": { "status": "down" },
"redis": { "status": "up" },
"tigerbeetle": { "status": "disconnected" }
}
}
```
## Fields
| Field | Type | Description |
| ------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | string | `ok` unless the Postgres or Redis ping fails, in which case `degraded`. TigerBeetle never affects this value — a disconnected TigerBeetle is reported only under `components`. |
| `version` | string | The running build version — the same value [Get Version](/api-reference/operations/version) returns. |
| `components` | object | Per-component status, keyed by component name. |
| `components.postgres.status` | string | `up` or `down`. Down is critical: the response is `503`. |
| `components.redis.status` | string | `up` or `down`. Present only when Redis was connected at boot — `REDIS_URL` parsed and the boot-time ping succeeded. If `REDIS_URL` is set but unusable and `REQUIRE_REDIS` is not, the process falls back to in-memory and this key is absent. Down is degraded but serving. |
| `components.tigerbeetle.status` | string | `connected` or `disconnected` — the boot-time client state. Disconnected means PG-only ledger mode. |
## Errors
| Status | Code | When | Fix |
| ------ | ---- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `503` | — | Postgres ping failed. The body is the health payload above with `status: "degraded"`, not an error envelope. | Check the database and `DATABASE_URL`; the process keeps serving so the probe can report recovery. |
This endpoint does not use the error envelope — every response, including
`503`, is the health payload above.
## OpenAPI
````yaml GET /health
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
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:
/health:
get:
tags:
- System
summary: Health check
description: >-
Reports overall service health plus per-component status (Postgres,
Redis, TigerBeetle).
operationId: getHealth
responses:
'200':
description: Service is healthy (or degraded but serving).
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
'503':
description: A critical dependency (Postgres) is down.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
security: []
components:
schemas:
HealthResponse:
type: object
properties:
status:
type: string
enum:
- ok
- degraded
version:
type: string
components:
type: object
additionalProperties:
type: object
properties:
status:
type: string
error:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: >-
Tenant API key obtained from `POST /auth/register` or `POST
/v1/developer/keys`.
````