Състояние и договор — API документация

GET

/api/health/live

Unauthenticated process liveness probe.

Изисква обхвата none — no API key required scope.

Example request

Request

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

Примерен отговор

json

{
  "status": "ok",
  "service": "car-details-api",
  "contract_version": "2026-10-05"
}

GET

/api/health/ready

Unauthenticated readiness probe — is the data layer reachable?

Изисква обхвата none — no API key required scope.

Example request

Request

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

Примерен отговор

json

{
  "status": "ready"
}

GET

/api/health

Return service, data-feed and schema health.

Изисква обхвата ops scope.

Example requests

Request

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

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

Примерен отговор

json

{
  "status": "healthy",
  "service": "car-details-api",
  "worker_pid": 41,
  "contract_version": "2026-10-05",
  "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.

Изисква обхвата 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"

Примерен отговор

json

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

Какво получавате

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.

Изисква обхвата ops scope.

Example requests

Request

GET https://api.thecarapi.com/

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

Примерен отговор

json

{
  "service": "Car Details API",
  "version": "2.0.0",
  "endpoints": {
    "GET /api/health": "Health check endpoint"
  },
  "typesense": {
    "enabled": true,
    "running": true
  }
}