Standard REST API Endpoint Technical Documentation Template

# POST /api/v1/documents/compress

Asynchronously processes and optimizes an uploaded document payload according to specified compression parameters.

---

### 🌐 ENDPOINT OVERVIEW
- **Method:** `POST`
- **Path:** `/api/v1/documents/compress`
- **Authentication:** Bearer Token (`Authorization: Bearer <API_KEY>`)
- **Rate Limit:** 120 requests / minute per API key
- **Content-Type:** `application/json`

---

### 🔑 REQUEST HEADERS

| Header Name | Type | Required | Description |
| :--- | :---: | :---: | :--- |
| `Authorization` | String | **Yes** | `Bearer <jwt_or_api_token>` |
| `Content-Type` | String | **Yes** | Must be `application/json` |
| `X-Request-Id` | String | No | Unique client UUID for distributed trace correlation |

---

### 📦 REQUEST BODY PARAMETERS

| Parameter | Type | Required | Default | Description |
| :--- | :---: | :---: | :---: | :--- |
| `fileUrl` | String | **Yes** | - | Public or signed S3/GCS URL to source document |
| `compressionLevel` | String | No | `medium` | Accepted values: `low`, `medium`, `aggressive` |
| `targetMaxKb` | Integer | No | `null` | Maximum desired output threshold in Kilobytes |
| `stripMetadata` | Boolean | No | `true` | Strips Exif, author, and creation timestamp metadata |

#### Example Request Payload:
```json
{
  "fileUrl": "https://storage.example.com/uploads/annual-report-2026.pdf",
  "compressionLevel": "aggressive",
  "targetMaxKb": 200,
  "stripMetadata": true
}
```

---

### 📥 RESPONSE DEFINITIONS

#### Success Response (`200 OK`):
```json
{
  "status": "success",
  "data": {
    "jobId": "job_8f2910fa_c4e1",
    "downloadUrl": "https://cdn.docswift.xyz/out/annual-report-compressed.pdf",
    "originalSizeKb": 1420.5,
    "compressedSizeKb": 184.2,
    "reductionRatio": "87.03%",
    "processingTimeMs": 314
  }
}
```

#### Error Responses:

| Status Code | Error Code | Description / Resolution |
| :---: | :--- | :--- |
| `400 Bad Request` | `INVALID_PAYLOAD` | Missing required `fileUrl` or malformed JSON structure. |
| `401 Unauthorized` | `AUTH_EXPIRED` | Provided Bearer token is invalid or expired. |
| `413 Payload Too Large` | `FILE_EXCEEDS_50MB` | Input file exceeds the 50MB tier limit. |
| `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED` | Limit of 120 req/min exceeded. Retry after `Retry-After` header seconds. |

---

### 💻 CURL REPRODUCTION EXAMPLE
```bash
curl -X POST https://api.docswift.xyz/v1/documents/compress \
  -H "Authorization: Bearer dck_live_992f00a881" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://storage.example.com/doc.pdf",
    "compressionLevel": "aggressive",
    "targetMaxKb": 200
  }'
```