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>
httpOnly cookie (refreshToken) on successful login or signup.
See Authentication for the full token lifecycle.
All request bodies must be JSON. Set the Content-Type header accordingly:
Content-Type: application/json
{
"success": true,
"message": "Operation completed successfully",
"data": { ... }
}
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
}
| 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) |
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:
Example request:
curl http://localhost:5000/health
{
"success": true,
"message": "Server is running"
}
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).