> ## 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

> Base URLs, authentication, conventions and rate limits — read this before the endpoint reference

## Start here

This tab is the reference for the CaseXchange Public API. Read this page and the three that follow it for the conventions every endpoint shares — the response envelope, the error codes, and the end-to-end flows — then open **Endpoints** in the sidebar for the operation-by-operation reference, which is generated from the OpenAPI schema and is 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

CaseXchange can push referral lifecycle events — new referrals, acknowledgements, status changes, notes, documents — to an HTTPS endpoint you control, so you do not have to poll. Subscriptions are managed through `POST /webhooks` and its sibling endpoints with a `standard`-tier key; every delivery is signed with HMAC-SHA256 and retried on failure.

Webhooks are a signal that something changed, not a synchronisation feed: keep reconciling against `GET /status-updates` and `GET /received-referrals`, which remain the source of truth. See the [Webhooks](/webhooks) tab for the setup guide, event catalog, signature verification, and delivery guarantees.

### 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

* Open **Endpoints** in the sidebar and expand the group you need — the groups match the OpenAPI tags and stay collapsed until you click one.
* 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.