API Introduction

Base URL, authentication, request/response format, error handling, rate limiting, and CORS for the Hayon REST API.

Base URL

All API requests are made to the following base URL:

http://localhost:5000/api

The default port is 5000 (configurable via the PORT environment variable). In production, replace http://localhost:5000 with your deployed backend hostname. All routes are prefixed with /api.

API versioning

Hayon’s API is currently unversioned. Breaking changes will be communicated through the changelog before they are deployed.

Authentication

Most endpoints require a valid JWT access token. Pass the token in the Authorization header as a Bearer token:

Authorization: Bearer <access_token>

Access tokens are short-lived. Use the token refresh endpoint to obtain a new access token when yours expires. A refresh token is issued as an httpOnly cookie (refreshToken) on successful login or signup.

See Authentication for the full token lifecycle.

Request format

All request bodies must be JSON. Set the Content-Type header accordingly:

Content-Type: application/json

The maximum request body size is 50 MB.

Response format

All responses return JSON. Successful responses follow this structure:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... }
}

The data field is present only when the endpoint returns a payload. Some endpoints return only success and message.

Error responses

Errors follow a consistent structure:

{
  "success": false,
  "message": "Unauthorized",
  "statusCode": 401
}

Common HTTP status codes:

Status	Meaning
400	Bad request — invalid or missing input
401	Unauthorized — missing or invalid token
403	Forbidden — action not permitted
404	Not found
429	Too many requests — rate limit exceeded
500	Internal server error

Rate limiting

Certain endpoints enforce per-identifier rate limits backed by Redis. When a limit is exceeded the API responds with 429 Too Many Requests.

Rate limit metadata is returned in response headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds until the rate limit resets (only on 429 responses)

Specific limits are documented on each endpoint. The rate limit identifier is the request’s email address (for unauthenticated endpoints) or user ID (for authenticated endpoints).

Rate limit windows are fixed (not sliding). Exceeding the limit blocks subsequent requests until the window resets — not for a rolling period from your last request.

Health check

A health check endpoint is available without authentication:

GET /health

Example request:

curl http://localhost:5000/health

Example response:

{
  "success": true,
  "message": "Server is running"
}

This endpoint is useful for uptime monitoring and load balancer health probes.

CORS

The API enforces strict CORS. Requests are accepted only from:

• The configured FRONTEND_URL environment variable (typically http://localhost:3000 in development, your production domain otherwise)
• http://localhost:3001 (hardcoded secondary local development origin)

Requests from any other origin are rejected with a CORS error. The Retry-After header is included in the list of exposed headers, so clients can read it after a 429 response.

Cookies are supported cross-origin — requests from allowed origins may include credentials (credentials: 'include' in fetch, or withCredentials: true in Axios).