TheCarApi logoTheCarApiVEHICLE DATA ENGINE
contract 2026-08-19
Endpoints

Health & contract

Check service dependencies and inspect the API index.

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-08-19"
}
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",
  "service": "car-details-api",
  "contract_version": "2026-08-19"
}
GET

/api/health

Return service, database-feed, Typesense, 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",
  "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.

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-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
  }
}

What you get back

versionstring

The contract version this deployment serves — the same value every response carries as 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.

paginationobject

max_limit and max_offset for paged endpoints.

live_pricesobject

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.

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/search": "Search auction inventory",
    "GET /api/health": "Service health"
  }
}
GET

/api/diagnostics

Executor and connection-pool diagnostics.

Requires the ops scope.

Example request

Request
GET https://api.thecarapi.com/api/diagnostics

Example response

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