REST API Endpoints

Overview

This page documents all available REST API endpoints. The API follows RESTful conventions with JSON request and response bodies. All endpoints require authentication unless otherwise noted.

Base URL

All API requests should be made to the following base URL:

https://api.example.com/v1

For development and testing, use the sandbox environment:

https://sandbox.api.example.com/v1

Authentication

All requests must include an API key in the Authorization header:

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

See the Authentication Overview for details on obtaining and managing API keys.

Users Endpoints

List All Users

Retrieve a paginated list of all users in your organization.

GET /users

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.example.com/v1/users?page=1&limit=10&sort=name&order=asc"

Example Response

{
  "data": [
    {
      "id": "usr_abc123",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "admin",
      "created_at": "2024-01-15T09:30:00Z"
    },
    {
      "id": "usr_def456",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "member",
      "created_at": "2024-02-20T14:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "total_pages": 5
  }
}

Get a Single User

Retrieve details for a specific user by ID.

GET /users/:id

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/v1/users/usr_abc123

Example Response

{
  "id": "usr_abc123",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "role": "admin",
  "created_at": "2024-01-15T09:30:00Z",
  "last_login": "2024-03-10T18:45:00Z",
  "preferences": {
    "theme": "dark",
    "notifications": true,
    "language": "en"
  }
}

Create a User

Create a new user in your organization.

POST /users

Request Body

Example Request

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

Example Response

{
  "id": "usr_ghi789",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "role": "member",
  "created_at": "2024-03-13T10:00:00Z"
}

Products Endpoints

List All Products

Retrieve a paginated list of products.

GET /products

Query Parameters

Example Response

{
  "data": [
    {
      "id": "prod_001",
      "name": "Documentation Theme",
      "category": "themes",
      "price": 49.00,
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "total_pages": 1
  }
}

Get a Single Product

GET /products/:id

Returns the full product object including description, images, and metadata.

Create a Product

POST /products

Request Body

Error Codes

All API errors return a consistent JSON structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The email field is required.",
    "details": [
      {
        "field": "email",
        "message": "This field is required"
      }
    ]
  }
}

HTTP Status Codes

Error Codes

Rate Limiting

API requests are rate-limited to prevent abuse:

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1710324000