---
title: "Service health"
method: GET
path: "/api/v1/health"
tags: ["System"]
---

# Service health

`GET /api/v1/health`

Return service status and BORME freshness from exactly one bounded global_counters_v1 offline projection. Its ETag is also bound to the shared asv1 generation used by CCAA, sector and sources, with 60-second must-revalidate caching. A cold request never opens SQLite, validates person/company sidecars, scans artifact directories, probes CSV files or rebuilds counters. Missing, legacy, malformed or future-dated projection bytes return 503.

## Headers

- `If-None-Match` string

## Response `200`

Health response

- HealthResponse
  - `status` 'ok' | 'stale' | 'error', required
  - `service` 'openmercantil', required
  - `version` string, required
  - `projection` 'global_counters_v1', required
  - `projection_generation` string, required
  - `generated_at` string, date-time, required
  - `artifacts_age_hours` number, required
  - `latest_borme_processed` string, date, required
  - `companies_indexed_approx` integer, required
  - `total_events_approx` integer, required
  - `count_source` 'offline_projection', required
  - `features` object, required — Runtime feature health. Cheap signals only (env + offline counters); no live query in the request path.
    - `google_signin` 'available' | 'disabled', required
    - `sources_catalog` 'valid' | 'invalid', required
    - `data_fresh` boolean, required
  - `degraded` boolean, required — True when any feature is disabled/invalid or the data is stale (artifacts_age_hours >= 26), even if status is still "ok".

## Other responses

- `304` — The exact offline health representation and shared stats generation have not changed
- `429` — Rate limit exceeded
- `503` — The public read failed closed because its legal source catalog, subject classification, bounded projection, database helper or required artifact is unavailable. Clients must not infer an empty result.

---

[API](https://skmtc.net/openmercantil/apis/openmercantil-public-api.md) · [All operations](https://skmtc.net/openmercantil/apis/openmercantil-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmercantil/openmercantil-public-api/versions/996f96a11758/schema)