Overview

Welcome to the v2 of our public REST API. This version introduces improved naming conventions, richer filtering options, and standardized pagination.

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

All responses are in application/json format.

Authentication

All endpoints require an API Key passed in the Authorization header as a Bearer token.

Authorization: Bearer YOUR_API_KEY

Example using curl:

curl -H "Authorization: Bearer abc123def456" https://api.example.com/v2/users

Endpoints

Users

MethodEndpointDescription
GET/usersList all users (paginated)
POST/usersCreate a new user
GET/users/{id}Retrieve a single user
PUT/users/{id}Update a user
DELETE/users/{id}Delete a user

List Users

GET /users?limit=20&page=2&status=active

Response:

{
  "data": [
    {"id":"u_1","email":"alice@example.com","status":"active"},
    {"id":"u_2","email":"bob@example.com","status":"active"}
  ],
  "meta": {
    "total": 145,
    "limit": 20,
    "page": 2,
    "pages": 8
  }
}

Orders

MethodEndpointDescription
GET/ordersList orders with filters
POST/ordersCreate a new order
GET/orders/{id}Retrieve order details
PUT/orders/{id}Update order status

Create Order

POST /orders
Content-Type: application/json

{
  "user_id": "u_1",
  "items": [
    {"product_id":"p_123","quantity":2},
    {"product_id":"p_456","quantity":1}
  ],
  "currency":"USD"
}

Response (201 Created):

{
  "id":"o_789",
  "status":"pending",
  "total_amount": 149.97,
  "currency":"USD",
  "created_at":"2025-09-16T12:34:56Z"
}

Error Codes

HTTPCodeMessage
400invalid_parameterOne or more request parameters are invalid.
401unauthorizedMissing or invalid authentication credentials.
403forbiddenAuthenticated but not allowed to perform this action.
404not_foundThe requested resource does not exist.
429rate_limitedToo many requests – try again later.
500server_errorUnexpected server error – contact support.

Changelog