API Reference

Base URL

https://api.example.com/v1

Authentication

Include your API key in the header:

Authorization: Bearer YOUR_API_KEY

Endpoints

GET /users Auth Required

Retrieve a list of users.

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

Response:

{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 10
  }
}

POST /users Auth Required

Create a new user.

Request Body:

Field	Type	Required	Description
`name`	string	Yes	User’s full name
`email`	string	Yes	Email address
`role`	string	No	User role (default: `user`)

curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@example.com"}'

GET /users/:id Auth Required

Retrieve a single user.

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

Error Codes

Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limited
`500`	Server Error

Error Response Format:

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

Rate Limits

Standard: 100 requests/minute
Premium: 1000 requests/minute