API Overview

Architecture

Hopshift uses Next.js API routes (App Router) for its backend API. Routes are organized under apps/web/app/api/.

Authentication

All API routes require authentication via Supabase Auth. Requests must include a valid JWT in the Authorization header.

Authorization: Bearer <supabase-jwt>

API Conventions

Request Format

JSON request bodies
Query parameters for filtering and pagination

Response Format

All responses follow a consistent format:

{
  "data": { ... },
  "error": null
}

Error Handling

Errors return appropriate HTTP status codes with descriptive messages:

{
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Employee not found"
  }
}

Pagination

The employee list endpoint uses page-based pagination and accepts up to 500 records per page:

GET /api/v1/employees?page=2&limit=100

Rate Limiting

Authenticated public employee API endpoints allow 200 requests per minute per API key. A 429 Too Many Requests response includes Retry-After in seconds.