Getting Started

Welcome to the API documentation. This API provides a RESTful interface to manage users. All requests and responses use JSON format.

Base URL

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

Quick Start

Make your first API call by listing all users:

cURL 
curl -X GET "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Format

All responses follow a consistent structure:

JSON 
{
  "status": "success",
  "data": {},
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  }
}

HTTP Status Codes

CodeDescription
200Success
201Resource created
400Bad request - invalid parameters
401Unauthorized - invalid or missing API key
404Resource not found
429Rate limit exceeded
500Internal server error

Authentication

All API requests require an API key passed via the Authorization header using the Bearer scheme.

API Keys — Generate your API key from the Dashboard → Settings → API Keys.

Header Format

Header 
Authorization: Bearer YOUR_API_KEY

Rate Limits

PlanRequests / minuteRequests / day
Free601,000
Pro60050,000
Enterprise6,000Unlimited
GET /users

Retrieve a paginated list of all users.

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number (default: 1)
per_pageintegerNoItems per page, max 100 (default: 20)
sortstringNoSort by field: created_at, name, email
orderstringNoasc or desc (default: desc)

Request

cURL 
curl -X GET "https://api.example.com/v1/users?page=1&per_page=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

JSON 
{
  "status": "success",
  "data": [
    {
      "id": "usr_a1b2c3d4",
      "name": "Alice Martin",
      "email": "alice@example.com",
      "role": "admin",
      "created_at": "2025-12-01T10:30:00Z"
    },
    {
      "id": "usr_e5f6g7h8",
      "name": "Bob Johnson",
      "email": "bob@example.com",
      "role": "member",
      "created_at": "2025-12-05T14:20:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 2,
    "total": 48
  }
}
POST /users

Create a new user account.

Request Body

FieldTypeRequiredDescription
namestringYesFull name of the user (2-100 chars)
emailstringYesUnique email address
rolestringNoadmin or member (default: member)
avatar_urlstringNoURL to user avatar image

Request

cURL 
curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Charlie Davis",
    "email": "charlie@example.com",
    "role": "member"
  }'

Response 201 Created

JSON 
{
  "status": "success",
  "data": {
    "id": "usr_i9j0k1l2",
    "name": "Charlie Davis",
    "email": "charlie@example.com",
    "role": "member",
    "avatar_url": null,
    "created_at": "2026-01-15T09:45:00Z"
  }
}
Validation — Email must be unique. Attempting to create a user with an existing email returns 400 Bad Request.
GET /users/:id

Retrieve a single user by their unique ID.

Path Parameters

ParameterTypeRequiredDescription
idstringYesUser ID (e.g. usr_a1b2c3d4)

Request

cURL 
curl -X GET "https://api.example.com/v1/users/usr_a1b2c3d4" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

JSON 
{
  "status": "success",
  "data": {
    "id": "usr_a1b2c3d4",
    "name": "Alice Martin",
    "email": "alice@example.com",
    "role": "admin",
    "avatar_url": "https://avatars.example.com/alice.jpg",
    "created_at": "2025-12-01T10:30:00Z",
    "updated_at": "2026-01-10T08:15:00Z"
  }
}

Error Response 404 Not Found

JSON 
{
  "status": "error",
  "error": {
    "code": "not_found",
    "message": "User with ID 'usr_a1b2c3d4' not found."
  }
}
DELETE /users/:id

Permanently delete a user account. This action is irreversible.

Destructive action — This permanently deletes the user and all associated data. This cannot be undone.

Path Parameters

ParameterTypeRequiredDescription
idstringYesUser ID (e.g. usr_a1b2c3d4)

Request

cURL 
curl -X DELETE "https://api.example.com/v1/users/usr_a1b2c3d4" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

JSON 
{
  "status": "success",
  "data": {
    "id": "usr_a1b2c3d4",
    "deleted": true
  }
}