stack/docs/4-api/1-conventions/1-endpoints.md

API Endpoint Conventions

Standard patterns for all Mosaic Stack API endpoints.

Base URL

• Development: http://localhost:3001
• Production: https://api.example.com

Standard REST Endpoints

GET    /api/{resource}           # List resources (with pagination)
GET    /api/{resource}/:id       # Get single resource
POST   /api/{resource}           # Create new resource
PATCH  /api/{resource}/:id       # Update resource (partial)
PUT    /api/{resource}/:id       # Replace resource (full)
DELETE /api/{resource}/:id       # Delete resource

Response Format

Success Response

{
  "data": {
    "id": "uuid",
    "name": "Example",
    "createdAt": "2026-01-28T12:00:00.000Z"
  }
}

List Response (with pagination)

{
  "data": [
    { "id": "1", "name": "Item 1" },
    { "id": "2", "name": "Item 2" }
  ],
  "meta": {
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "email": "Invalid email format"
    }
  }
}

HTTP Status Codes

Code	Meaning	Usage
200	OK	Successful GET, PATCH, PUT
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Invalid input
401	Unauthorized	Missing/invalid auth token
403	Forbidden	Valid token, insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Resource already exists
422	Unprocessable Entity	Validation failed
500	Internal Server Error	Server error

Pagination

All list endpoints support pagination via query parameters:

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

Parameters:

• page — Page number (default: 1)
• limit — Items per page (default: 10, max: 100)

Response includes:

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

Filtering

Use query parameters for filtering:

GET /api/tasks?status=active&priority=high
GET /api/events?start_date=2026-01-01&end_date=2026-01-31

Supported operators:

• = — Equals
• _gt — Greater than (e.g., created_at_gt=2026-01-01)
• _lt — Less than
• _gte — Greater than or equal
• _lte — Less than or equal
• _in — In array (e.g., status_in=active,pending)

Sorting

Use sort parameter:

GET /api/tasks?sort=created_at           # Ascending
GET /api/tasks?sort=-created_at          # Descending (minus prefix)
GET /api/tasks?sort=-priority,created_at # Multiple fields

Field Selection

Request specific fields to reduce payload size:

GET /api/tasks?fields=id,title,status

Response:

{
  "data": [{ "id": "1", "title": "Task 1", "status": "active" }]
}

Relationships

Include related resources:

GET /api/tasks?include=assignee,project

Response:

{
  "data": {
    "id": "1",
    "title": "Task 1",
    "assignee": {
      "id": "user-1",
      "name": "John Doe"
    },
    "project": {
      "id": "proj-1",
      "name": "Project Alpha"
    }
  }
}

Authentication

All authenticated endpoints require Bearer token:

Authorization: Bearer {session_token}

See Authentication Endpoints for details.

Request Headers

Required:

Content-Type: application/json

Optional:

Authorization: Bearer {token}
X-Workspace-ID: {workspace-uuid}  # For multi-tenant requests

Validation Errors

Validation errors return 422 with detailed field errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "details": {
      "email": "Invalid email format",
      "password": "Must be at least 8 characters"
    }
  }
}

Rate Limiting

API endpoints are rate-limited:

• Anonymous: 60 requests/hour
• Authenticated: 1000 requests/hour

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1643723400

When exceeded, returns 429 Too Many Requests.

CORS

CORS is configured for frontend origin:

// Allowed origins
const origins = [process.env.NEXT_PUBLIC_APP_URL, "http://localhost:3000", "http://localhost:3001"];

Versioning

Currently v1 (implicit). Future versions will use URL versioning:

/api/v2/tasks

Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2026-01-28T12:00:00.000Z",
  "uptime": 123456
}

Examples

Create Task

curl -X POST http://localhost:3001/api/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "title": "Complete API documentation",
    "description": "Write comprehensive API docs",
    "priority": "high",
    "targetDate": "2026-01-30"
  }'

Response (201):

{
  "data": {
    "id": "task-uuid",
    "title": "Complete API documentation",
    "status": "pending",
    "priority": "high",
    "createdAt": "2026-01-28T12:00:00.000Z"
  }
}

List Tasks with Filters

curl "http://localhost:3001/api/tasks?status=active&sort=-created_at&limit=5" \
  -H "Authorization: Bearer {token}"

Update Task

curl -X PATCH http://localhost:3001/api/tasks/task-uuid \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "status": "completed"
  }'

Next Steps

• Authentication — Authentication Endpoints
• Type Definitions — API Types
• Implementation — Development Workflow