API Reference

Welcome to the API documentation. Below you’ll find details on how to interact with our RESTful endpoints.

Base URL

https://api.example.com/v1

Authentication

All requests require a Bearer token passed in the Authorization header.

Authorization: Bearer <YOUR_TOKEN>

GET /users

Retrieve a paginated list of users.

Request

GET /users?page=1&limit=20 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_TOKEN

Response (200)

{
  "page": 1,
  "limit": 20,
  "total": 342,
  "data": [
    {
      "id": "u_01",
      "name": "Alice Johnson",
      "email": "alice@example.com"
    },
    // ...
  ]
}

POST /users

Create a new user.

Request Body

{
  "name": "Bob Smith",
  "email": "bob@example.com",
  "password": "StrongP@ssw0rd"
}

Response (201)

{
  "id": "u_12345",
  "name": "Bob Smith",
  "email": "bob@example.com",
  "created_at": "2025-09-17T12:34:56Z"
}

Error Handling

The API returns standard HTTP status codes. Error payloads follow this structure:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request payload is invalid.",
    "details": [
      {"field":"email","issue":"Invalid format"}
    ]
  }
}