Health & contract — API Reference

GET

/api/health/live

Unauthenticated process liveness probe.

Requires the none — no API key required scope.

Example request

Request

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

Example response

json

{
  "status": "ok",
  "service": "car-details-api",
  "contract_version": "2026-09-03"
}

GET

/api/health/ready

Unauthenticated readiness probe — is the data layer reachable?

Requires the none — no API key required scope.

Example request

Request

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

Example response

json

{
  "status": "ready"
}

GET

/api/health

Return service, data-feed and schema health.

Requires the ops scope.

Example requests

Request

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

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

Example response

json

{
  "status": "healthy",
  "service": "car-details-api",
  "worker_pid": 41,
  "contract_version": "2026-09-03",
  "typesense": {
    "enabled": true,
    "healthy": true
  },
  "public_auction_feed": {
    "enabled": true,
    "fresh": true
  }
}

GET

/api/contract

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

Requires the ops scope.

Example requests

Request

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

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

Example response

json

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

What you get back

versionstring

The contract version this deployment serves. Matches the contract_version on response bodies that carry one. This response itself carries no envelope metadata — version is the contract version.

schemasobject

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.max_limitinteger

The page-size ceiling. Clamp your own paging to it rather than discovering it by being clamped.

pagination.max_offsetinteger

The offset cap on the capped endpoints (catalog, archive, top-offers, classifieds listings). Search and listVehicles have no offset cap.

live_pricesobject

Whether this deployment reads a running auction’s bid when its detail is requested, which sources it covers, and how long a refreshed price stays current ({ enabled, sites, ttl_seconds }). The values are illustrative, not guaranteed — read them at startup rather than hardcoding them. The whole block is absent where the feature does not exist at all, and that absence is the only way to tell “live prices are unavailable” from “this car has none right now”, because both look identical in a detail response.

GET

/

Return the human-readable API index and service version.

Requires the ops scope.

Example requests

Request

GET https://api.thecarapi.com/

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/health": "Health check endpoint"
  },
  "typesense": {
    "enabled": true,
    "running": true
  }
}