# API Reference

## Overview
{API description and base URL}

## Authentication
{Auth methods}

## Endpoints

### {Resource}
- [GET /{resource}](#get-resource)
- [POST /{resource}](#post-resource)
- [GET /{resource}/{id}](#get-resource-id)
- [PUT /{resource}/{id}](#put-resource-id)
- [DELETE /{resource}/{id}](#delete-resource-id)

## Error Handling
{Error format and codes}

## Rate Limiting
{Rate limit info}

## Overview

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

**Content Type:** `application/json`

**API Version:** v1 (2025-01-15)

### Request Format

All requests should include:
- `Content-Type: application/json` header
- Authentication header (see Authentication section)
- Request body as JSON for POST/PUT requests

## Authentication

### Bearer Token

Include the token in the Authorization header:

```http
Authorization: Bearer {token}

X-API-Key: {api_key}

POST /auth/token
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "secret"
}

{
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_at": "2025-01-16T12:00:00Z"
}

### Endpoint Template

```markdown
## {HTTP Method} /{path}

{Brief description of what this endpoint does}

### Request

**URL:** `{HTTP Method} /api/v1/{path}`

**Authentication:** Required / Optional

#### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `{param}` | {type} | Yes/No | {description} |

#### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `{param}` | {type} | {default} | {description} |

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `{field}` | {type} | Yes/No | {description} |

**Example Request:**

```http
{METHOD} /api/v1/{path}
Authorization: Bearer {token}
Content-Type: application/json

{
    "field": "value"
}

{
    "id": "123",
    "field": "value",
    "created_at": "2025-01-15T10:00:00Z"
}

### Error Handling Section

```markdown
## Error Handling

### Error Response Format

All errors follow this format:

```json
{
    "error": {
        "code": "ERROR_CODE",
        "message": "Human-readable error message",
        "details": {
            "field": ["Specific field error"]
        }
    }
}

### Rate Limiting Section

```markdown
## Rate Limiting

API requests are rate limited per API key:

| Plan | Limit | Window |
|------|-------|--------|
| Free | 100 | per hour |
| Pro | 1000 | per hour |
| Enterprise | 10000 | per hour |

### Rate Limit Headers

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests allowed |
| `X-RateLimit-Remaining` | Requests remaining |
| `X-RateLimit-Reset` | Unix timestamp when limit resets |

### Rate Limit Response

When rate limited, you'll receive:

```http
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705320000

{
    "error": {
        "code": "RATE_LIMITED",
        "message": "Rate limit exceeded. Retry after 60 seconds."
    }
}

## Complete Endpoint Example

```markdown
## POST /orders

Create a new order for the authenticated user.

### Request

**URL:** `POST /api/v1/orders`

**Authentication:** Required

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `items` | array | Yes | Order items |
| `items[].product_id` | string | Yes | Product UUID |
| `items[].quantity` | integer | Yes | Quantity (1-100) |
| `shipping_address` | object | Yes | Delivery address |
| `shipping_address.street` | string | Yes | Street address |
| `shipping_address.city` | string | Yes | City name |
| `shipping_address.postal_code` | string | Yes | Postal/ZIP code |
| `shipping_address.country` | string | Yes | ISO 3166-1 alpha-2 |
| `coupon_code` | string | No | Discount code |

**Example Request:**

```http
POST /api/v1/orders
Authorization: Bearer eyJhbGci...
Content-Type: application/json

{
    "items": [
        {
            "product_id": "550e8400-e29b-41d4-a716-446655440000",
            "quantity": 2
        }
    ],
    "shipping_address": {
        "street": "123 Main St",
        "city": "New York",
        "postal_code": "10001",
        "country": "US"
    },
    "coupon_code": "SAVE10"
}

{
    "id": "ord_123456",
    "status": "pending",
    "items": [
        {
            "product_id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Widget Pro",
            "quantity": 2,
            "unit_price": {"amount": 2999, "currency": "USD"},
            "total": {"amount": 5998, "currency": "USD"}
        }
    ],
    "subtotal": {"amount": 5998, "currency": "USD"},
    "discount": {"amount": 600, "currency": "USD"},
    "total": {"amount": 5398, "currency": "USD"},
    "shipping_address": {
        "street": "123 Main St",
        "city": "New York",
        "postal_code": "10001",
        "country": "US"
    },
    "created_at": "2025-01-15T10:30:00Z"
}

## Generation Instructions

When generating API documentation:

1. **Identify** all endpoints from routes or actions
2. **Document** request parameters (path, query, body)
3. **Document** response fields with types
4. **Provide** realistic example requests/responses
5. **List** all possible error responses
6. **Include** authentication requirements
7. **Group** endpoints by resource