> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casexchange.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Overview

> How to use the CaseXchange API reference and Postman collection

## API Reference

This section is powered by the OpenAPI schema in `api-reference/openapi.yml`. Every endpoint, request schema, response schema, and status code shown in the **API Reference** tab is generated from the source of truth.

### Postman Collection

The fastest way to explore and test the API is with the pre-built Postman collection. Every request includes automated test scripts that validate responses and chain environment variables (IDs, tokens) between requests.

<CardGroup cols={2}>
  <Card title="Download Collection" icon="download" href="/postman/CaseXchange-Public-API.postman_collection.json">
    All Public API endpoints with examples, tests, and variable chaining.
  </Card>

  <Card title="Download Environment" icon="gear" href="/postman/CaseXchange-Public-API.postman_environment.production.json">
    Production environment with pre-configured variables.
  </Card>
</CardGroup>

### What is covered

* The Public API (`/api/public/v1`) provides endpoints for sent cases, received referrals, firms, documents, routing rules, analytics, and network management — all authenticated via `X-API-Key`.
* The Internal API (`/api/v1`) covers authentication, session management, and API key administration — authenticated via JWT bearer tokens.
* Shared request/response schemas and standardized error envelopes across both API layers.

### Base URLs

| API              | Base URL                                    | Auth               |
| ---------------- | ------------------------------------------- | ------------------ |
| **Public API**   | `https://api.casexchange.com/api/public/v1` | `X-API-Key` header |
| **Internal API** | `https://api.casexchange.com/api/v1`        | JWT Bearer token   |

### Authentication

**Public API** — include your API key in every request:

```
X-API-Key: cxp_std_your_key_here
```

**Internal API** — use JWT bearer tokens (relative to `/api/v1`):

1. `POST /api/v1/auth/login`
2. `GET /api/v1/auth/me`
3. `POST /api/v1/auth/refresh-session` (when the access token expires)
4. Continue requests with `Authorization: Bearer <accessToken>`

See the [JWT Guide](/auth/jwt) for full details.

### Response conventions

Public API responses use a consistent envelope with `data`, `meta` (requestId + timestamp), and optional `pagination`. Errors use `error.code` + `error.message`. See:

* [Response Format](/api-reference/response-format) for the full envelope specification
* [Error Handling](/api-reference/error-handling) for error codes, status codes, and troubleshooting

### Rate limiting

Public API endpoints are rate limited per API key. Rate limit headers are included on every response:

| Header                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Remaining requests in the current window       |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets          |

When you exceed the limit, you will receive a `429 Too Many Requests` response. Implement exponential backoff and respect the `X-RateLimit-Reset` header before retrying.

### Webhooks

Webhooks are not currently available. To detect new referrals or status changes, poll `GET /received-referrals` or `GET /status-updates` with date range filters. We recommend polling intervals of 1-5 minutes depending on your use case.

### Versioning

The Public API is currently at `v1`. New fields may be added to response objects without a version bump — your client should ignore unknown fields. Breaking changes (removed fields, changed types, removed endpoints) will be communicated in advance and will result in a new version path (`/v2`).

### OpenAPI spec

The full OpenAPI 3.0 spec is available for download to generate client libraries or import into tools:

* [Download openapi.yml](/api-reference/openapi.yml)

### How to navigate the endpoints

* Use the **API Reference** tab for autogenerated endpoint docs from OpenAPI tags.
* Open any endpoint page to inspect required headers, path/query params, request body schema, and documented responses.
* Use the **Postman collection** to run real requests against your environment with one click.

<CardGroup cols={2}>
  <Card title="Examples" icon="terminal" href="/api-reference/examples">
    Representative cURL requests and success/error responses.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/error-handling">
    Troubleshooting patterns for validation, auth, permissions, and conflicts.
  </Card>

  <Card title="Response Format" icon="brackets-curly" href="/api-reference/response-format">
    Response envelope, pagination, and common schema conventions.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/api-reference/workflows">
    End-to-end implementation flows across multiple endpoints.
  </Card>
</CardGroup>