API Documentation

Open Labor Project exposes a REST API for automotive labor times, torque specs, fluid capacities, OBD-II DTCs, batteries, parts, and estimates. All endpoints return JSON. Authentication is a single header. Start with a free Hobbyist key, upgrade tiers when you outgrow it.

New here? Start here.

If you've never used an API before, this section walks you through your first successful call — what to click, where to paste, and what success looks like. No assumptions.

curl "https://openlaborproject.com/api/v1/labor-times?make=ford&model=f-150&year=2017" -H "x-api-key: YOUR_KEY_HERE"

Quickstart

1. Get a free key at openlaborproject.com/developers (no credit card for Hobbyist).

2. Send a test request:

curl "https://openlaborproject.com/api/v1/labor-times?make=ford&model=f-150&year=2017" \
  -H "x-api-key: YOUR_KEY_HERE"

You should get a JSON response with labor times grouped by engine variant. If you get 401 INVALID_API_KEY, double-check the key value. If you get 403 with HTML, you've hit Cloudflare — see Common gotchas.

Authentication

Every request needs an API key passed via one of two headers. Both work identically — pick whichever fits your HTTP client.

Option A — x-api-key header

x-api-key: 12345678-1234-1234-1234-123456789abc

Option B — Authorization: Bearer

Authorization: Bearer 12345678-1234-1234-1234-123456789abc

The Bearer form is convenient if you're using a generic API client (Postman, Insomnia, an SDK builder) that has a built-in Bearer auth field.

Storing your key safely

The pro move is to put the key in an environment variable on your computer or server, then have your code read it from there. That way the key never appears in your source files — so it can't accidentally end up on GitHub.

Set the variable (one-time per machine)

# Persistent (survives reboots):
[System.Environment]::SetEnvironmentVariable(
  'OLP_API_KEY','YOUR_KEY_HERE','User')

# Then close and reopen PowerShell.
# Verify it stuck:
$env:OLP_API_KEY

# Add this line to ~/.zshrc (Mac default)
# or ~/.bashrc (most Linux):
export OLP_API_KEY="YOUR_KEY_HERE"

# Reload your shell:
source ~/.zshrc    # or ~/.bashrc

# Verify:
echo $OLP_API_KEY

# Create a file named .env in your project root:
OLP_API_KEY=YOUR_KEY_HERE

# Add ".env" to your .gitignore so it
# never gets committed!

# In your code:
require('dotenv').config();
process.env.OLP_API_KEY

Then use it in your code

Once the variable is set, your code reads it without ever knowing the actual key value:

// Node / JavaScript
fetch(url, { headers: { 'x-api-key': process.env.OLP_API_KEY } })

# Python
requests.get(url, headers={'x-api-key': os.environ['OLP_API_KEY']})

# Bash / curl
curl -H "x-api-key: $OLP_API_KEY" "$url"

Response shape

Every endpoint returns the same envelope. Success or failure, the three top-level keys are always present.

{
  "data":  { ... } | null,    // the payload on 2xx; null on 4xx/5xx
  "meta":  {
    "timestamp": "2026-06-09T18:00:00.000Z",
    // endpoint-specific extras (count, region, rateLimit, etc.)
  },
  "error": null | {
    "code":    "MACHINE_READABLE_CODE",
    "message": "Human-readable explanation."
  }
}

Inspect error.code (not the HTTP status alone) to branch on failure mode — codes are stable, messages may evolve.

Error codes

Rate limits

Two limits run in parallel: a daily cap (resets midnight UTC) and a per-minute burst cap (resets every full minute). Hitting either returns 429.

Headers returned on every response

X-RateLimit-Tier:              builder
X-RateLimit-Limit-Daily:       1000
X-RateLimit-Remaining-Daily:   847
X-RateLimit-Reset-Daily:       2026-06-10T00:00:00.000Z
X-RateLimit-Limit-Minute:      300
X-RateLimit-Remaining-Minute:  295
Retry-After:                   42         # only on 429 BURST_LIMIT_EXCEEDED

Watch Remaining-Daily and back off proactively rather than waiting for a 429. The legacy X-RateLimit-Limit / X-RateLimit-Remaining headers are still sent as daily-value aliases for backward compatibility.

Endpoint reference

All endpoints are GET, hosted at https://openlaborproject.com, and return JSON. Query params are URL-encoded.

{
  "data": {
    "vehicle": { "make": "Ford", "model": "F-150", "yearRange": "2017-2017", "engine": "3.5L V6 EcoBoost" },
    "laborTimes": [
      { "job": "Brake Pads — Front", "jobSlug": "brake-pads-front", "category": "brakes",
        "hours": 1.3, "lowRange": 1.1, "highRange": 1.6, "confidence": "high" },
      // ...
    ]
  },
  "meta": { "count": 287, "region": "US", "timestamp": "2026-06-09T18:00:00.000Z" },
  "error": null
}

{
  "data": {
    "vehicle": { "make": "Ford", "model": "F-150", "engine": "3.5L V6 EcoBoost" },
    "torqueSpecs": [
      { "job": "Brake Pads — Front", "component": "Caliper Bracket Bolt",
        "nm": 175, "lbFt": 129, "angleDegrees": null, "sequence": null,
        "isCritical": true, "notes": "Use new bolts", "confidence": "oem_verified" }
    ]
  },
  "meta": { "count": 4, "region": "US" }
}

{
  "data": {
    "make": "Ford",
    "model": "F-150",
    "engines": [
      {
        "yearStart": 2017, "yearEnd": 2017, "yearRange": "2017",
        "engine":          "3.5L V6 EcoBoost",
        "engineSlug":      "3.5l-v6-ecoboost",
        "engineCode":      "ECOBOOST-35",
        "fuelType":        "gasoline",
        "forcedInduction": "twin-turbo",
        "transmission":    "automatic",
        "drivetrain":      "4wd"
      }
    ]
  },
  "meta": { "count": 4, "region": "US" }
}

Code examples

Same request — labor times for a 2017 Ford F-150 3.5L EcoBoost — in the three most common languages.

cURL

curl "https://openlaborproject.com/api/v1/labor-times?make=ford&model=f-150&year=2017&engine=3.5l-v6-ecoboost" \
  -H "x-api-key: $OLP_API_KEY"

JavaScript / Node (fetch)

const res = await fetch(
  'https://openlaborproject.com/api/v1/labor-times?make=ford&model=f-150&year=2017&engine=3.5l-v6-ecoboost',
  { headers: { 'x-api-key': process.env.OLP_API_KEY } }
);

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`OLP ${error.code}: ${error.message}`);
}

const { data, meta } = await res.json();
console.log(`${data.laborTimes.length} jobs for the ${data.vehicle.engine}`);

// Back off if we're close to the daily cap
const remaining = parseInt(res.headers.get('X-RateLimit-Remaining-Daily'), 10);
if (remaining < 50) console.warn('Approaching daily limit:', remaining);

Python (requests)

import os, requests

r = requests.get(
    'https://openlaborproject.com/api/v1/labor-times',
    params={'make': 'ford', 'model': 'f-150', 'year': 2017, 'engine': '3.5l-v6-ecoboost'},
    headers={'x-api-key': os.environ['OLP_API_KEY']},
    timeout=15,
)

if r.status_code == 429:
    retry = int(r.headers.get('Retry-After', '60'))
    raise SystemExit(f'Rate limited, retry in {retry}s')

r.raise_for_status()
data = r.json()['data']
print(f"{len(data['laborTimes'])} jobs for the {data['vehicle']['engine']}")

Common gotchas

Cloudflare bot challenge (403 with HTML body)

If you get a 403 response that looks like HTML instead of JSON, you've hit our Cloudflare bot challenge — meaning your request arrived without the API key header. Cloudflare lets anything with a valid x-api-key or Authorization: Bearer header through. Most often: a proxy or SDK stripped the header. Confirm by inspecting the request right before it's sent.

Make and model slugs are lowercase, hyphenated

ford, not Ford. f-150, not F-150 or F150. Pull the slug list from /api/v1/vehicles if you're unsure.

Year can be single or range

year=2017 matches that single model year. year=2015-2020 matches any vehicle whose year range overlaps. Anything else returns 400 INVALID_YEAR.

Engine slug is the canonical form, not a display string

3.5l-v6-ecoboost, not 3.5L V6 EcoBoost. Hit /api/v1/vehicles?make=…&model=… to list engine slugs for a model.

404 NOT_FOUND vs. empty result

We return 404 with NOT_FOUND when the vehicle/job combo has no data — not a 200 with an empty array. Branch on error.code to distinguish "we don't have it yet" from "your request was malformed".

Premium features and grandfathered keys

Some features (advanced filtering, bulk lookup, webhooks, bulk export) require a paid tier and return 403 TIER_LOCKED on Hobbyist. The error payload includes feature and required_tier so you can prompt an upgrade.