API Documentation (Example)

Updated on March 24, 2026

Base URL

Base URL
https://api.example.com/v1

All endpoints are prefixed with /v1. All requests require an API key in the Authorization header:

Authorization
Authorization: Bearer YOUR_API_KEY_HERE

List Users

Retrieve a paginated list of user records.

Example Request
GET /v1/users
Host: api.example.com
Authorization: Bearer YOUR_API_KEY_HERE
Accept: application/json

Query Parameters

NameTypeRequiredDescription
pageintegerNoPage number (default: 1).
per_pageintegerNoItems per page (default: 20, max: 100).
sortstringNoField to sort by (e.g. created_at).
orderstringNoasc or desc(default: asc).

Response

{
  "data": [
    {
      "id": "1234",
      "name": "Alice Nguyen",
      "email": "alice@example.com",
      "created_at": "2025-06-01T14:22:30Z"
    },
    {
      "id": "1235",
      "name": "Bob Smith",
      "email": "bob@example.com",
      "created_at": "2025-06-02T09:15:10Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total_pages": 5,
    "total_items": 100
  }
}
{
  "error": {
    "code": "validation_error",
    "message": "One or more fields failed validation.",
    "details": {
      "email": ["This field is required."],
      "password": ["Must be at least 8 characters."]
    }
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "Authorization token is missing from the request headers."
  }
}
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource."
  }
}
{
  "error": {
    "code": "not_found",
    "message": "User with ID '12345' was not found."
  }
}
{
  "error": {
    "code": "email_exists",
    "message": "A user with this email address already exists."
  }
}

Response Fields

  • data (array of user objects)
    • id (string): Unique user ID.
    • name (string): Full name.
    • email (string): Email address.
    • created_at (string, ISO 8601): Timestamp of creation.
  • meta (object)
    • page (integer): Current page.
    • per_page (integer): Items per page.
    • total_pages (integer): Total pages.
    • total_items (integer): Total user count.

Next