# HMS Doc Processing Service — API Reference

**Version:** 0.5.0
**Base URL:** `https://docs.hostmerchantservices.com`

## Authentication

All endpoints (except `/health`) require a Bearer token:
```
Authorization: Bearer your_api_key_here
```

Two key tiers:
- **Master key** — full access, can create/revoke sub keys
- **Sub keys** — scoped to specific endpoints, rate-limited, usage-tracked

---

## POST `/analyze`

Analyze

**Query Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `ocr` | No | off|auto|force (default: `auto`) |
| `max_pages` | No |  (default: `20`) |
| `return_provenance` | No |  (default: `True`) |
| `profile` | No | e.g., merchant_statement_v1 |

**Custom Headers:**

- `X-Skip-Cache`: 

---

## POST `/classify`

Classify File

Upload a file for classification.
- With doc_type: human-labels the file, teaches the classifier
- Without doc_type: auto-classifies using learned patterns

---

## GET `/classify/stats`

Classify Stats

---

## GET `/doc-types`

List Doc Types

---

## POST `/doc-types`

Create Doc Type

---

## POST `/extract-tables`

Extract Tables

**Query Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `ocr` | No | off|auto|force (default: `auto`) |
| `max_pages` | No |  (default: `200`) |
| `page_range` | No | e.g., 1-3,5,8-10 |
| `format` | No | json|csv|xlsx|html (default: `json`) |

**Custom Headers:**

- `X-Skip-Cache`: 

---

## GET `/health`

Health

---

## POST `/keys`

Create Api Key

Create a new sub API key. Master key required. The full key is only shown once.

---

## GET `/keys`

List Api Keys

List all sub API keys with usage summaries. Master key required.

---

## DELETE `/keys/{key_id}`

Revoke Api Key

Revoke (deactivate) a sub API key. Master key required.

---

## GET `/keys/{key_id}/usage`

Get Key Usage

Get usage details for a specific key. Master key required.

**Query Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `days` | No |  (default: `30`) |

---

## GET `/pipedrive/deals`

Pipedrive Deals

**Query Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `limit` | No |  (default: `50`) |
| `offset` | No |  (default: `0`) |

---

## POST `/pipedrive/sync`

Pipedrive Sync

---

## GET `/pipedrive/sync/status`

Pipedrive Sync Status

---

## Response Headers (Processing Endpoints)

| Header | Description |
|--------|-------------|
| `X-Cache` | `HIT` or `MISS` |
| `X-Cache-Id` | UUID of the cache entry |
| `X-Content-SHA256` | SHA-256 hash of the submitted file |

## Cache Bypass

Send `X-Skip-Cache: true` header to force reprocessing even if a cached result exists.

---
*Auto-generated from the live OpenAPI spec. Fetch the full schema at `/openapi.json`.*