# cOBD API v1 — AI Agent Documentation

## Overview
cOBD is a real-time OBD-II car telemetry platform. This API gives AI agents read-only access to a user's vehicle data — status, trips, health scores, fuel economy, GPS location, and driving behavior.

## Authentication
Every request requires an API key. The user generates one from their Settings page.

**Header method (preferred):**
```
Authorization: Bearer cobd_xxxx...
```

**Query parameter method:**
```
GET /api/v1/summary?api_key=cobd_xxxx...
```

## Base URL
```
https://obd.cakcan.com/api/v1
```

## Endpoints

### GET /api/v1/me
Verify the API key and see account info.

**Response:**
```json
{
  "user": { "id": 1, "email": "user@example.com", "display_name": "Kemal", "tier": "pro" },
  "vehicles": [{ "id": 1, "name": "Lancer 1.6", "make": "Mitsubishi", "model": "Lancer", "year": 2006 }]
}
```

### GET /api/v1/summary
**Best endpoint for daily briefings.** Returns everything in one call — vehicle info, latest readings, health score, fuel status, and recent trips.

**Response:**
```json
{
  "vehicles": 1,
  "total_logs": 2243,
  "last_upload": "2026-04-04T12:49:06Z",
  "current_vehicle": { "id": 1, "name": "Lancer 1.6", "make": "Mitsubishi", "model": "Lancer", "year": 2006 },
  "latest_readings": {
    "time": "2026-04-04T12:49:06Z",
    "rpm": 754, "speed_kph": 0, "coolant_temp": 95,
    "throttle_pos": 0, "gps_lat": 40.723, "gps_lon": 29.795,
    "fuel_remaining_pct": 69.5, "distance_to_empty_km": 215,
    "battery_voltage": 13.8, "boost_vacuum_psi": -10.8,
    "intake_air_temp": 74, "engine_load_pct": 27.8
  },
  "health_score": { "score": 82, "components": { "coolant": { "score": 25, "max": 25 }, "fuelTrim": { "score": 18, "max": 25 }, "o2": { "score": 25, "max": 25 }, "battery": { "score": 14, "max": 25 } } },
  "fuel": { "remaining_pct": 69.5, "distance_to_empty_km": 215, "battery_voltage": 13.8 },
  "recent_trips": [
    { "date": "2026-04-04T11:36:06Z", "distance_km": 32.18, "duration_min": 73, "avg_speed": 26.4, "max_speed": 99, "fuel_used_l": null }
  ]
}
```

### GET /api/v1/status
Latest sensor readings for each vehicle.

**Response:** Array of objects, one per vehicle:
```json
[{
  "vehicle": { "id": 1, "name": "Lancer 1.6", "make": "Mitsubishi", "model": "Lancer", "year": 2006 },
  "latest": {
    "time": "...", "rpm": 754, "speed_kph": 0, "coolant_temp": 95,
    "throttle_pos": 0, "gps_lat": 40.723, "gps_lon": 29.795,
    "fuel_remaining_pct": 69.5, "distance_to_empty_km": 215,
    "battery_voltage": 13.8, "boost_vacuum_psi": -10.8,
    "intake_air_temp": 74, "engine_load_pct": 27.8
  }
}]
```

### GET /api/v1/trips
Last 10 trips. Optional `?vehicle_id=1` to filter by vehicle.

**Response:**
```json
[{
  "date": "2026-04-04T11:36:06Z", "end": "2026-04-04T12:49:06Z",
  "distance_km": 32.18, "duration_min": 73,
  "avg_speed_kph": 26.4, "max_speed_kph": 99,
  "fuel_used_l": null, "data_points": 2190
}]
```

### GET /api/v1/location
Last known GPS position with a Google Maps link.

**Response:**
```json
{
  "lat": 40.723, "lon": 29.795, "alt": 413, "speed_kph": 0,
  "time": "2026-04-04T12:49:06Z",
  "vehicle": { "name": "Lancer 1.6", "make": "Mitsubishi", "model": "Lancer", "year": 2006 },
  "maps_url": "https://maps.google.com/?q=40.723,29.795"
}
```

### GET /api/v1/health *(Pro only)*
Engine health score (0-100) with component breakdown.

**Response:**
```json
{
  "score": 82,
  "components": {
    "coolant":  { "score": 25, "max": 25, "label": "Coolant Temp" },
    "fuelTrim": { "score": 18, "max": 25, "label": "Fuel Trims" },
    "o2":       { "score": 25, "max": 25, "label": "O2 Sensors" },
    "battery":  { "score": 14, "max": 25, "label": "Battery/Charging" }
  }
}
```

### GET /api/v1/fuel *(Pro only)*
Fuel economy stats and latest readings.

**Response:**
```json
{
  "latest": {
    "fuel_remaining_pct": 69.5, "distance_to_empty_km": 215,
    "fuel_flow_lph": 0.36, "instant_kpl": 0, "avg_l100km": 12.9
  },
  "avg_kpl": 7.79,
  "data_points": 50
}
```

### GET /api/v1/drive-score *(Pro only)*
Driving smoothness score with letter grade.

**Response:**
```json
{
  "score": 99, "grade": "A",
  "breakdown": { "hardBrakes": 4, "hardAccels": 0, "hardCorners": 0, "totalReadings": 1000 }
}
```

## Tier Restrictions
- **Free tier:** /me, /summary, /status, /trips, /location
- **Pro tier:** All of the above + /health, /fuel, /drive-score
- Pro-only endpoints return `403` with `{"error": "This endpoint requires a Pro account."}`

## Error Codes
| Status | Meaning |
|--------|---------|
| 200 | Success |
| 401 | Missing or invalid API key |
| 403 | Account suspended or Pro feature on Free tier |
| 500 | Server error |

## Example Usage

**Daily car briefing prompt for an AI agent:**
> Using my cOBD API key, call GET https://obd.cakcan.com/api/v1/summary and give me a natural language summary of my car's status, health, fuel level, and recent trips.

**Quick status check:**
> Call GET https://obd.cakcan.com/api/v1/status with my API key and tell me my car's current RPM, coolant temp, and battery voltage.

**Where's my car:**
> Call GET https://obd.cakcan.com/api/v1/location and tell me where my car is parked right now.