# TypeScript SDK

@kortix/sdk — one typed client for the Kortix platform: projects, sessions, and the live agent runtime, behind a single session-scoped facade.

Canonical page: https://kortix.com/docs/sdk

`@kortix/sdk` is the single, opinionated data layer for the Kortix platform. One
typed client wraps both the **Kortix REST API** and the **OpenCode runtime**, so a
host app — web, mobile, or your own — imports **only `@kortix/sdk`** and never
touches the raw API, `authenticatedFetch`, or `@opencode-ai/sdk` directly.

```ts
import { createKortix } from '@kortix/sdk';

const kortix = createKortix({
  backendUrl: 'https://api.kortix.com/v1',
  getToken: async () => process.env.KORTIX_API_KEY!, // your Kortix API key
});

const projects = await kortix.projects.list();

const s = kortix.session(projectId, sessionId);
await s.ensureReady(); // provision/resume, long-poll until ready
await s.health(); // is the runtime ready?
s.previewUrl(3000, '/docs'); // proxy URL for a port the agent exposed
```

## Philosophy

- **One token.** Auth is a single Kortix token — a Supabase JWT or a `kortix_pat_…` — supplied once via `getToken`. Keys never leave the server.
- **Session-scoped.** You hold a _session_ and ask it about its own runtime: `session.health()`, `session.previewUrl()`. The sandbox is an implementation detail you never name.
- **Mutations own their side-effects** — server-side. You state intent; the SDK doesn't orchestrate side-effects client-side.
- **One import.** No `@opencode-ai/sdk`, no raw `backendApi`, no `authenticatedFetch` in host code — everything is reachable through `createKortix` or a `@kortix/sdk/*` subpath.

## Two layers

The SDK gives you an **imperative** client for actions and **reactive** hooks for live UI data:

- `createKortix(config)` → the facade. Call methods: `kortix.projects.list()`, `kortix.session(pid, sid).start()`.
- `@kortix/sdk/react` → hooks. **`useSession(projectId, sessionId)` runs a whole session** in one hook — messages, `send`, status, the boot `phase` — with the runtime (start, SSE, readiness) handled for you. Plus models, config, and PTY.

- [Getting started](/docs/sdk/getting-started)
Install, configure, authenticate, and make your first calls.
- [Full example](/docs/sdk/full-example)
Zero to a streaming agent reply in one framework-free file.
- [Auth](/docs/sdk/auth)
API keys vs Supabase JWTs — the two ways to authenticate the SDK.
- [The client](/docs/sdk/the-client)
The full `createKortix` facade — accounts, projects, and the project handle.
- [Sessions](/docs/sdk/sessions)
The session handle: lifecycle, runtime health, previews, and the typed opencode runtime.
- [Streaming](/docs/sdk/streaming)
Live events, the readiness handshake, and the runtime support matrix.
- [React hooks](/docs/sdk/react)
`@kortix/sdk/react` — reactive data: live messages, events, config, PTY.
- [Modules](/docs/sdk/modules)
The functional areas — files, session runtime, the opencode client, auth, turns — all on the
root entry.
- [Distribution](/docs/sdk/distribution)
npm, the CDN bundles, version lockstep, and the entry-point stability tiers.

> **Note**
> The Kortix REST API also has an auto-generated reference at
> [api.kortix.com/v1/docs](https://api.kortix.com/v1/docs) (OpenAPI). The SDK wraps it with types
> and ergonomics — prefer the SDK in application code.