# API Overview
How Klarefi's public API is organized for hosted intake and review-ready case files
Source: https://www.klarefi.com/docs/api/overview

The Klarefi API lets customer systems create hosted intake sessions, read
current case state, receive signed webhooks, and erase document-derived data.

> **Canonical API base URL**
>
> Production integrations use the canonical host below. A workspace-specific
> `https://<deployment>.convex.site` URL from **Settings → Developer** also
> remains valid for direct regional access.

Examples use this illustrative value:

```text
https://www.klarefi.com
```

Download the [OpenAPI 3.1 specification](/docs/api/openapi.yaml) for the full
machine-readable contract.

For TypeScript integrations, install the SDK and verify your credentials:

```bash
npm install @klarefi/node
export KLAREFI_API_KEY="sk_test_..."
npx klarefi doctor
```

## Versioning

Public endpoints live under `/api/v1`. Additive response fields may appear over
time. Integrations should ignore unknown fields and use documented IDs,
statuses, and event names for control flow.

## Integration Model

Hosted Intake is the integration path. Klarefi owns the applicant-facing flow:
form steps, uploads, follow-up questions, and submission. Create a session,
redirect the applicant to `signed_url`, then consume the case through webhooks
or case reads.

<Mermaid
  title="Default API flow"
  chart={`flowchart TD
  Session[POST /api/v1/sessions]
  Redirect[Redirect applicant to signed_url]
  Intake[Applicant completes hosted intake]
  Case[Case record]
  Events[Signed webhooks]
  Package[Review-ready package]

Session --> Redirect
Redirect --> Intake
Intake --> Case
Case --> Facts[Facts with evidence]
Case --> Events[Signed webhooks]
Case --> Package
`}
/>

## Common Conventions

- Requests and responses are JSON unless an endpoint says otherwise.
- API keys are sent with `Authorization: Bearer sk_live_...` or
  `Authorization: Bearer sk_test_...`.
- `POST /api/v1/sessions` requires an `idempotency_key` in the JSON body or an
  `Idempotency-Key` header.
- Authenticated success responses include `X-RateLimit-*` headers.
- Error responses use the shared `{ "error": { ... } }` envelope.