# API Contract

## Endpoint: {METHOD} {/path}

### Description
{What this endpoint does in one sentence.}

### Authentication
- **Required**: Yes / No
- **Method**: Bearer token / API key / Session cookie / None
- **Permissions**: {required roles or scopes}

### Request

#### Headers
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer {token} |
| Content-Type | Yes | application/json |
| X-Request-ID | No | Client-generated request ID for tracing |

#### Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| {param} | {type} | {description} |

#### Query Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| {param} | {type} | {Yes/No} | {default} | {description} |

#### Request Body
```json
{
  "field_name": "string — Description of this field",
  "nested_object": {
    "inner_field": "number — Description of this field"
  },
  "optional_field?": "string — This field is optional"
}
```

**Validation Rules**:
- `field_name`: {min/max length, format, allowed values}
- `nested_object.inner_field`: {range, constraints}

### Response

#### Success Response (200 / 201)
```json
{
  "data": {
    "id": "uuid — Unique identifier",
    "field_name": "string — Description",
    "created_at": "ISO 8601 timestamp"
  }
}
```

#### Error Responses

| Status | Error Code | Description | Response Body |
|--------|-----------|-------------|---------------|
| 400 | VALIDATION_ERROR | Invalid request body | `{"error": {"code": "VALIDATION_ERROR", "message": "...", "details": [{"field": "...", "issue": "..."}]}}` |
| 401 | UNAUTHORIZED | Missing or invalid auth token | `{"error": {"code": "UNAUTHORIZED", "message": "..."}}` |
| 403 | FORBIDDEN | Insufficient permissions | `{"error": {"code": "FORBIDDEN", "message": "..."}}` |
| 404 | NOT_FOUND | Resource does not exist | `{"error": {"code": "NOT_FOUND", "message": "..."}}` |
| 409 | CONFLICT | Resource already exists | `{"error": {"code": "CONFLICT", "message": "..."}}` |
| 429 | RATE_LIMITED | Too many requests | `{"error": {"code": "RATE_LIMITED", "message": "...", "retry_after": 60}}` |
| 500 | INTERNAL_ERROR | Server error | `{"error": {"code": "INTERNAL_ERROR", "message": "..."}}` |

### Example

#### Request
```bash
curl -X {METHOD} {base_url}{/path} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "field_name": "example value"
  }'
```

#### Response
```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "field_name": "example value",
    "created_at": "2025-01-15T10:30:00Z"
  }
}
```

---

## Endpoint: {METHOD} {/next-path}

{Repeat the same structure for each endpoint.}