# Klaudija: integration guide for developers and agents

Canonical guide: https://klaudija.io/developers
OpenAPI 3.1: https://klaudija.io/examples/klaudija.openapi.json
TypeScript client example: https://klaudija.io/examples/klaudija-client.ts
Contract review: 2026-09-05. Examples were checked against source and mocked locally, not executed against production.

## Scope and prerequisites

This guide covers the documented managed-agent API subset: 13 operations with authentication, asynchronous jobs, results, history, usage and platform-user administration. OpenAPI servers are placeholders. The client is illustrative, not an official released SDK. No public direct-chat, voice or training endpoint is defined by this contract.

Obtain these values through onboarding:

- KLAUDIJA_API_BASE: provisioned API root for /admin and /me.
- KLAUDIJA_RUN_BASE: full provisioned /uni-agent endpoint.
- KLAUDIJA_REGISTERED_ORIGIN: the exact registered application origin.
- PLATFORM_KEY: administrative platform credential, backend only.
- KLAUDIJA_ACCESS_TOKEN: user-scoped access token obtained through the backend identity exchange.

https://klaudija.io is the marketing website, not an API base. Never send credentials to example or inferred endpoints. A documentation visit is not permission to submit production jobs or change users, budgets or agents.

## 1. Connect an identity on your backend

```sh
curl --fail-with-body "$KLAUDIJA_API_BASE/admin/platform-users" \
  -H "X-Platform-API-Key: $PLATFORM_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"user_id":"dev_customer_42","platform_slug":"dev_your_platform","email":"dev_customer_42@example.com","plan_code":"YOUR_CONFIGURED_PLAN","provision_memory_store":true}'

curl --fail-with-body -X POST \
  "$KLAUDIJA_API_BASE/admin/platform-users/dev_customer_42/auth" \
  -H "X-Platform-API-Key: $PLATFORM_KEY"
```

The user body requires user_id and platform_slug (or source). Use an existing configured plan. Token exchange needs an email and linked authentication identity. Keep administrative keys on the backend. Customer calls use Authorization: Bearer <access_token>.

The broker can reuse a token pair across concurrent exchanges. Cache the access token until near expiry and re-exchange. Independent services should not rotate a shared refresh token. The canonical business identity can represent a team; do not assume the authentication UUID equals the product's customer ID.

## 2. Submit asynchronous work

```sh
curl --fail-with-body "$KLAUDIJA_RUN_BASE" \
  -H "Authorization: Bearer $KLAUDIJA_ACCESS_TOKEN" \
  -H "Origin: $KLAUDIJA_REGISTERED_ORIGIN" \
  --form-string 'query=Summarize this document.' \
  --form-string 'session_id=dev_conversation_42' \
  --form-string 'async=1' \
  -F 'file=@document.pdf'
```

The multipart body accepts query, session_id, async and one optional file. Provide a query or a file. Keep the session ID for subsequent turns. Agent selection comes from configuration; public callers cannot choose arbitrary agents. Browser requests carry their origin; server integrations must send the registered Origin. Let the client set the multipart boundary and Content-Length.

async=1 is essential: submission otherwise defaults to synchronous execution. Acceptance still includes authentication, budget checks, upload and session provisioning.

Example acceptance, HTTP 200:

```json
{"job_id":"example-job-id","session_id":"dev_conversation_42","status":"pending","anthropic_session_id":"example-provider-session","memory_status":"attached"}
```

## 3. Follow status and handle every terminal state

```sh
curl --fail-with-body "$KLAUDIJA_RUN_BASE/status/$JOB_ID" \
  -H "Authorization: Bearer $KLAUDIJA_ACCESS_TOKEN"
```

Public statuses are pending, done, error and cancelled. A job error can arrive with HTTP 200; inspect the JSON body. Poll at bounded intervals with a deadline. On completion inspect response and file_download_available. Cancellation may retain partial results. Save the job ID after client timeout; stopping a client wait does not cancel the server job.

Serialize conversation turns unless implementing the queue protocol. Plain submission has no general idempotency-key contract. Reconcile an ambiguous POST outcome before resubmitting to avoid duplicate work.

## 4. Retrieve or cancel work

```sh
curl --fail-with-body "$KLAUDIJA_RUN_BASE/result/$JOB_ID" \
  -H "Authorization: Bearer $KLAUDIJA_ACCESS_TOKEN" -o result.bin

curl --fail-with-body --get "$KLAUDIJA_RUN_BASE/result/$JOB_ID" \
  -H "Authorization: Bearer $KLAUDIJA_ACCESS_TOKEN" \
  --data-urlencode "file=$FILE_ID" -o selected-output.bin

curl --fail-with-body -X POST "$KLAUDIJA_RUN_BASE/cancel/$JOB_ID" \
  -H "Authorization: Bearer $KLAUDIJA_ACCESS_TOKEN"
```

Only retrieve output when available. Result success is binary and errors are JSON. Inspect Content-Type and Content-Disposition instead of assuming a format. A selected file must belong to the job. Signed download links are temporary bearer credentials. Cancellation records intent and requests a provider interrupt; it is a state-changing operation.

## Live events

Klaudija persists events in juris_session_events and uses Supabase Realtime. There is no public /stream SSE endpoint in this contract. Configure the provisioned client with the user JWT, subscribe to the authorized job_id filter, await readiness, fetch existing events, and deduplicate by event ID. Reconcile after reconnects, retain bounded polling as recovery, and remove subscriptions on teardown. A connected subscription does not prove job completion.

## Endpoint index

| Method | Relative path | Authentication |
| --- | --- | --- |
| POST | RUN_BASE | User JWT |
| GET | RUN_BASE/status/{job_id} | User JWT |
| GET | RUN_BASE/result/{job_id} | User JWT or signed download token |
| POST | RUN_BASE/cancel/{job_id} | User JWT |
| GET | API_BASE/me/threads | User JWT |
| GET | API_BASE/me/threads/{id}/messages | User JWT |
| GET | API_BASE/me/usage | User JWT |
| GET | API_BASE/me/mods | User JWT |
| POST | API_BASE/admin/platform-users | Platform key |
| GET | API_BASE/admin/platform-users | Platform key |
| POST | API_BASE/admin/platform-users/{userId}/auth | Platform key |
| PATCH | API_BASE/admin/platform-users/{userId}/plan | Platform key |
| POST | API_BASE/admin/platform-users/{userId}/credits | Platform key |

Refer to OpenAPI for request schemas, response shapes and exact parameters. Administrative and operator surfaces have different permissions; a platform key is not global operator authority.

Limits, recovery and budget handling: https://klaudija.io/docs/operations.md