# API Quickstart
Create a hosted intake session, redirect an applicant, and read the resulting case
Source: https://www.klarefi.com/docs/api/quickstart

> **Canonical API base URL**
>
> Production integrations use `https://www.klarefi.com`. A workspace-specific
> Convex HTTP URL shown in **Settings → Developer** remains valid for direct
> regional access.

Set your API key:

```bash
export KLAREFI_API_KEY="sk_test_..."
export KLAREFI_BASE_URL="https://www.klarefi.com"
export KLAREFI_API_BASE_URL="https://www.klarefi.com"
```

`@klarefi/node` reads `KLAREFI_BASE_URL`. The CLI and curl examples use
`KLAREFI_API_BASE_URL`; set both to the dashboard value.

## Install

```bash
npm install @klarefi/node
npx klarefi doctor
```

## Hosted intake

Create a session when Klarefi should own the applicant-facing intake. Run this
from trusted server-side code, then redirect the applicant to `signed_url`.

```ts
import { Klarefi } from "@klarefi/node";

const klarefi = new Klarefi({
  apiKey: process.env.KLAREFI_API_KEY!,
});

const session = await klarefi.sessions.create({
  case_type_id: "motor_claim",
  external_case_id: "claim_12345",
  external_applicant_id: "applicant_789",
  idempotency_key: "session_claim_12345",
  ttl_hours: 168,
  locale: "nl",
});

return Response.redirect(session.signed_url, 303);
```

For a CLI smoke test:

```bash
npx klarefi sessions create \
  --case-type motor_claim \
  --external-case-id claim_12345 \
  --external-applicant-id applicant_789 \
  --url-only
```

The same request over HTTP:

```bash
curl -X POST "$KLAREFI_API_BASE_URL/api/v1/sessions" \
  -H "Authorization: Bearer $KLAREFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "case_type_id": "motor_claim",
    "idempotency_key": "session_claim_12345",
    "external_case_id": "claim_12345",
    "external_applicant_id": "applicant_789",
    "ttl_hours": 168,
    "locale": "nl"
  }'
```

Example response:

```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "signed_url": "https://app.klarefi.com/s/550e8400-e29b-41d4-a716-446655440000?token=...",
  "access_token": "1751879000.9f2c4e...",
  "access_token_expires_at": "2026-01-22T10:30:00.000Z",
  "expires_at": "2026-01-22T10:30:00.000Z",
  "agent": {
    "api_base": "https://your-deployment.convex.site/api/v1",
    "manifest_url": "https://your-deployment.convex.site/api/v1/sessions/550e8400-e29b-41d4-a716-446655440000/manifest",
    "access_token": "1751879000.9f2c4e..."
  },
  "snippet": "<script>window.location.href=\"https://app.klarefi.com/s/...\";</script>",
  "idempotent_replay": false
}
```

For v1 hosted sessions, the session ID is also the case ID used by case reads.

```ts
const caseFile = await klarefi.cases.retrieve(session.session_id);
const events = await klarefi.cases.events(session.session_id, {
  afterCursor: 0,
  limit: 100,
});
const pkg = await klarefi.cases.getPackage(session.session_id);
```

CLI equivalents:

```bash
npx klarefi cases get 550e8400-e29b-41d4-a716-446655440000
npx klarefi cases events 550e8400-e29b-41d4-a716-446655440000 --after-cursor 0
npx klarefi cases package 550e8400-e29b-41d4-a716-446655440000
```