API Overview

Sunday exposes a RESTful API for all operations. All endpoints are under /api/.

Base URL

http://localhost:3000/api

In production:

https://your-domain.com/api

Most endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Get a token via the /api/auth/signin endpoint.

All POST/PATCH requests should use JSON:

Content-Type: application/json

Responses are JSON with consistent structure:

{
  "success": true,
  "data": { ... }
}

{
  "error": "Error message",
  "details": ["Field-specific errors"]
}

Code	Meaning
200	Success
201	Created
400	Bad Request (validation error)
401	Unauthorized (invalid/missing token)
403	Forbidden (insufficient permissions)
404	Not Found
429	Too Many Requests (rate limited)
500	Internal Server Error

API endpoints are rate limited to prevent abuse:

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 2025-01-15T12:00:00.000Z

When rate limited, you'll receive:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
 
{
  "error": "Too many requests",
  "message": "Rate limit exceeded. Please try again later."
}

All inputs are validated using Zod schemas. Invalid requests return 400 with details:

{
  "error": "Validation failed",
  "details": [
    {
      "path": ["email"],
      "message": "Invalid email format"
    }
  ]
}

List endpoints support pagination:

GET /api/tasks?page=1&limit=20

Response includes:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}