Quickstart · first API response, then production access

Step 1: make a keyless API fixture call

Add sample=1 to opt into the small response fixture without a token. It is for transport and response-shape testing, not search or coverage evaluation.

curl "https://api.apex-db.org/v1/apex?sample=1&limit=5"

# Fetch one record in full using an id from the list response
curl "https://api.apex-db.org/v1/apex/{id}?sample=1"

Step 2: inspect the response shape

List responses use the standard envelope: data, has_more, and next_cursor. Full records include field values and per-field provenance.

{
  "data": [
    {
      "id": 95124,
      "brand": "BMW",
      "model_name": "5 Series",
      "model_year": 2024,
      "_provenance": {
        "power_kw": {
          "source": "regulator-or-manufacturer-code",
          "source_record_url": "https://..."
        }
      }
    }
  ],
  "has_more": true,
  "next_cursor": "..."
}

Step 3: get a free API preview key

Sign in at the portal to create a free preview token. It uses the apex_live_ prefix and raises the daily fixture limit compared with keyless calls.

curl "https://api.apex-db.org/v1/apex?sample=1&limit=10" \
  -H "Authorization: Bearer apex_live_...."

Step 4: pay for one full-data call

No subscription is required for a one-off lookup. A full row costs $0.025; search pages cost $0.10, and coverage calls cost $0.25. Settlement uses x402 (USDC on Base) or MPP (USDC on Base and Tempo).

curl -i "https://api.apex-db.org/v1/apex/{id}"
# → 402 Payment Required
# x402 v2: decode PAYMENT-REQUIRED, then retry with PAYMENT-SIGNATURE;
# read PAYMENT-RESPONSE after settlement.
# x402 v1 compatibility: retry with X-PAYMENT and read X-PAYMENT-RESPONSE.
# MPP: read WWW-Authenticate, then retry with
# Authorization: Payment <credential>; read Payment-Receipt.

Step 5: switch to plan access

Remove sample=1 and pass a production token to query the full dataset.

curl "https://api.apex-db.org/v1/apex?brand=bmw&model_year=2024&limit=10" \
  -H "Authorization: Bearer apex_live_...."

Fields to inspect first

Start by checking the identity, powertrain, emissions, range, and provenance fields your workflow depends on.

• model_year

• powertrain

• variant_name

• body_class

  NHTSA body-class category from VIN decode: "Sedan/Saloon", "SUV/Crossover", "Pickup", "Hatchback/Liftback/Notchback", "Convertible/Cabriolet", "Coupe", "Wagon/Estate", "Van/Minivan". Populated only fr

• engine_name

• generation_id

  Optional FK to the generation this variant belongs to. NULL until Phase 2 (Wikidata bootstrap). ON DELETE SET NULL keeps variants stable when generations are cleaned up. The generation_id is an inferr

• markets

  Array of market codes where this variant is sold/registered. ISO 3166-1 alpha-2 codes (e.g. US, DE, FI, KR) plus the deliberate supranational extension 'EU', used by EEA-wide and JRC sources (eea-co2

• seats

  Number of seats as type-approved. Sources: SVV (antall_seter), NHTSA vPIC, manufacturer press. Universal (BEV/ICE/HEV/PHEV all have seats).

• doors

  Number of doors as type-approved. Sources: SVV (antall_dorer), NHTSA vPIC, manufacturer press. Universal.

• seats_max

  Maximum seating capacity including optional/fold-down seats, as type-approved. Always >= seats (standard layout). Sources: DGT NUM_PLAZAS_MAX. Universal — no powertrain gating. Source: spain-dgt.

Next steps

• ->REST API reference - Endpoint list, pagination, filters, errors, and pay-per-call behavior.
• ->Data dictionary - Field catalogue with type, applicability, fill rate, and sources.
• ->Provenance model - Per-value attribution, source classes, reconciliation, and DQ scoring.
• ->Sample manifest - Machine-readable sample rows, files, release metadata, and formats.