---
title: "Health & contract"
description: "Check service dependencies and inspect the API index."
canonical: "https://thecarapi.com/docs/ops"
contract_version: "2026-08-19"
api_base: "https://api.thecarapi.com"
source: "https://thecarapi.com/docs/ops.md"
---

# Health & contract

Check service dependencies and inspect the API index.

## GET /api/health/live

Unauthenticated process liveness probe.

**Scope:** `none — no API key required`

### Example requests

```http
GET https://api.thecarapi.com/api/health/live
```

### Example response

```json
{
  "status": "ok",
  "service": "car-details-api",
  "contract_version": "2026-08-19"
}
```

**Notes.** One of only two endpoints in the whole API that need no key. Always 200 while the process is up. This is the right target for an uptime monitor — it says nothing about whether the data behind the API is reachable, which is what /api/health/ready and /api/health are for.

## GET /api/health/ready

Unauthenticated readiness probe — is the data layer reachable?

**Scope:** `none — no API key required`

### Example requests

```http
GET https://api.thecarapi.com/api/health/ready
```

### Example response

```json
{
  "status": "ready",
  "service": "car-details-api",
  "contract_version": "2026-08-19"
}
```

**Notes.** 200 when the service can answer data requests, 503 when it cannot. Use this, not /api/health/live, to decide whether to send traffic. No key required.

## GET /api/health

Return service, database-feed, Typesense, and schema health.

**Scope:** `ops`

### Example requests

```http
GET https://api.thecarapi.com/api/health
```

```bash
curl -H "Authorization: Bearer $API_KEY" "https://api.thecarapi.com/api/health"
```

### Example response

```json
{
  "status": "healthy",
  "service": "car-details-api",
  "contract_version": "2026-08-19",
  "typesense": {
    "enabled": true,
    "running": true
  },
  "public_auction_feed": {
    "enabled": true,
    "fresh": true
  },
  "schema_findings": []
}
```

## GET /api/contract

Machine-readable schema catalog, pagination limits, and live-price capability.

**Scope:** `ops`

### Example requests

```http
GET https://api.thecarapi.com/api/contract
```

```bash
curl -H "X-API-Key: $API_KEY" "https://api.thecarapi.com/api/contract"
```

### Example response

```json
{
  "success": true,
  "version": "2026-08-19",
  "schemas": {
    "search_result_card": {
      "required": [],
      "optional": []
    }
  },
  "pagination": {
    "max_limit": 100,
    "max_offset": 5000
  },
  "live_prices": {
    "enabled": true,
    "sites": [
      "openlane",
      "ecarstrade"
    ],
    "ttl_seconds": 120
  }
}
```

### Response fields

| Field | Type | Meaning |
| --- | --- | --- |
| `version` | string | The contract version this deployment serves — the same value every response carries as contract_version. |
| `schemas` | object | Required and optional keys per response shape. This is the authoritative machine-readable schema; prefer it to hardcoding field lists. As of 2026-08-19, auction_detail.optional lists vault_gallery and brands_models_facets.optional lists errors — gate on those rather than comparing version strings. |
| `pagination` | object | max_limit and max_offset for paged endpoints. |
| `live_prices` | object | Whether this deployment refreshes a running auction’s price when its detail is read ({ enabled, sites, ttl_seconds }). Read sites from here rather than hardcoding it. The whole block is absent on a build from before the feature — that absence is the only way to tell “this deployment cannot refresh prices” from “this car has none right now”, because both look identical in a detail response. |

**Notes.** Read this once at startup. It is the correct answer to “does this deployment support live prices, and for which sources” — a missing live_price block on a detail response is not an error and never distinguishes the two cases on its own.

## GET /

Return the human-readable API index and service version.

**Scope:** `ops`

### Example requests

```http
GET https://api.thecarapi.com/
```

```bash
curl -H "X-API-Key: $API_KEY" "https://api.thecarapi.com/"
```

### Example response

```json
{
  "service": "Car Details API",
  "version": "2.0.0",
  "endpoints": {
    "GET /api/search": "Search auction inventory",
    "GET /api/health": "Service health"
  }
}
```

## GET /api/diagnostics

Executor and connection-pool diagnostics.

**Scope:** `ops`

### Example requests

```http
GET https://api.thecarapi.com/api/diagnostics
```

### Example response

```json
{
  "success": true,
  "executors": {},
  "pools": {}
}
```

**Notes.** Operational telemetry for support conversations. The shape is not part of the versioned contract and may change without a contract bump — do not build against it.