JockeyBox API Reference

This is the REST API that powers the JockeyBox self-hosted server. The mobile app talks to these endpoints to sync your vehicles, service records, fuel logs, and everything else.

Coming soon. The server container is actively being built. This documents the planned API surface — once it ships, every endpoint here will have full examples and response schemas.

Base URL

Everything is relative to your server's base URL:

Response Format

Everything comes back as JSON. Successful responses give you the data directly. Errors include a detail message and status_code so you know what went wrong.

Base URL

http://localhost:16399/api/v1

Success Response

{
  "id": "abc-123",
  "name": "My Truck",
  "year": 2019
}

Error Response

{
  "detail": "Vehicle not found",
  "status_code": 404
}

Authentication

Auth is handled with Bearer tokens. Hit the Login endpoint to get a token, then pass it in the Authorization header on every request after that.

Tokens are good for 24 hours. When one expires, use Refresh Token to grab a new one without making the user log in again.

Request Header

Authorization: Bearer YOUR_API_TOKEN

curl example

curl -X GET \
  http://localhost:16399/api/v1/vehicles \
  -H "Authorization: Bearer eyJhbGc..."

Health Check

Quick pulse check — is the server alive and can it talk to the database? No auth needed.

GET /api/v1/health

Request

curl http://localhost:16399/api/v1/health

Response 200

{
  "status": "healthy",
  "version": "1.0.0",
  "database": "connected"
}

Server Info

Tells you what version the server is running and what it's configured to allow. No auth needed.

GET /api/v1/info

Response 200

{
  "version": "1.0.0",
  "registration_enabled": true,
  "max_vehicles": 50,
  "max_upload_size": "10MB"
}

Login

POST /api/v1/auth/login

Parameters

Parameter	Type	Description
`email`	String	User's email address
`password`	String	User's password

Request

curl -X POST \
  http://localhost:16399/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response 200

{
  "access_token": "eyJhbGci...",
  "refresh_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86400
}

Register

Create a new account on the server. Only works when ENABLE_REGISTRATION is true — if you've locked that down, this returns a 403.

POST /api/v1/auth/register

Parameters

Parameter	Type	Description
`email`	String	Email address
`password`	String	Password (min 8 characters)
`name`	String	Display name

Request

curl -X POST \
  http://localhost:16399/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepass123",
    "name": "Shane"
  }'

Response 201

{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "Shane",
  "created_at": "2026-03-02T12:00:00Z"
}

Refresh Token

Swap a refresh token for a fresh access token. Keeps the user logged in without re-entering credentials.

POST /api/v1/auth/refresh

Parameters

Parameter	Type	Description
`refresh_token`	String	The refresh token from login

Response 200

{
  "access_token": "eyJhbGci...",
  "expires_in": 86400
}

List Vehicles

Get all vehicles in the logged-in user's garage.

GET /api/v1/vehicles

Response 200

[
  {
    "id": "veh_abc123",
    "year": 2019,
    "make": "Toyota",
    "model": "Tacoma",
    "mileage": 45230,
    "health_score": 92
  }
]

Create Vehicle

Add a vehicle to your garage. Year, make, and model are the only required fields — everything else is optional.

POST /api/v1/vehicles

Parameters

Parameter	Type	Required	Description
`year`	Integer	Yes	Model year
`make`	String	Yes	Manufacturer
`model`	String	Yes	Model name
`trim`	String	No	Trim level
`mileage`	Integer	No	Current mileage
`vin`	String	No	VIN number
`license_plate`	String	No	License plate

Request

curl -X POST \
  http://localhost:16399/api/v1/vehicles \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 2019,
    "make": "Toyota",
    "model": "Tacoma",
    "trim": "TRD Off-Road",
    "mileage": 45230
  }'

Response 201

{
  "id": "veh_abc123",
  "year": 2019,
  "make": "Toyota",
  "model": "Tacoma",
  "trim": "TRD Off-Road",
  "mileage": 45230,
  "health_score": 100,
  "created_at": "2026-03-02T12:00:00Z"
}

Get Vehicle

Fetch a single vehicle by its ID.

GET /api/v1/vehicles/:id