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

List endpoints support cursor-based pagination:

GET /api/employees?cursor=abc123&limit=20

Rate Limiting

API endpoints are rate-limited per organization. Current limits:

• 100 requests/minute for read operations
• 20 requests/minute for write operations

See Also

• API Reference: Detailed endpoint documentation