API Endpoints

Reference for the HTTP API. Start with the conventions below, then jump to a resource.

Base URL & versioning

All endpoints are prefixed with /api/v1. Paths in the resource docs are written relative to that prefix (e.g. POST /orders means POST /api/v1/orders). Responses are always JSON.

A liveness probe is available at /health.

Authentication

Auth uses bearer tokens. Send the token on every protected request:

Authorization: Bearer {token}

There are two token types:

Roles & access

A single user may be a customer, a driver, or both. Protected non-admin routes are further gated by role:

Common errors

Any protected endpoint may return these. They are not repeated in each resource doc.

Validation error shape (422):

{
  "error": "ValidationError",
  "details": {
    "fieldErrors": {
      "phone": ["The phone field format is invalid."]
    }
  }
}

Domain errors are returned by individual endpoints as a machine-readable error code plus an optional human message, with an appropriate status (commonly 409 Conflict):

{ "error": "ActiveOrderExists", "message": "Ya tienes un pedido activo." }

Pagination

List endpoints use one of three shapes (page-based, cursor-based, or flat). See Pagination.

Resources

Every resource is documented; follow a link for its endpoints, request fields, responses, and errors. All resources share the conventions above.

Auth & profile

Customer

Driver

Admin (back office)