# TypeScript SDK

Install, authenticate, and send your first message with the typed SDK.

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

`@kortix/sdk` is the typed client for the Kortix platform. It wraps the Kortix
REST API and OpenCode REST runtime in one interface. The core client is
fetch-based and runs in Node, Bun, and browsers.

## Install

```bash
npm install @kortix/sdk
```

`react` (18+) and `@tanstack/react-query` (5.75+) are optional peers, needed only for [React hooks](/docs/sdk/react).

## Create a client

Call `createKortix` once, with your API base URL and a function that returns your token.

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

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

`backendUrl` and `getToken` are the only required fields. The SDK calls `getToken` on every request and caches nothing — your host owns token storage and refresh.

Create an API key at **User settings → API keys**. The key starts with `kortix_pat_` and shows only once. Store it as a secret and return it from `getToken`. See [Auth](/docs/sdk/auth) for token types and scopes.

## Call a Connector

A Connector defines callable tools. A Connection stores one authorization for
that Connector. Credentials stay server-side.

```ts
const connectors = kortix.project(projectId).connectors;

await connectors.catalog();
await connectors.search('send email');
await connectors.describe('gmail.send_email');
await connectors.call('gmail.send_email', { to, subject, body });
```

An agent-minted session token already carries its project scope. Use
`kortix.connectors` when the agent does not have a separate `projectId` value.

## Start your first session

1. Create a session in your project.

   ```ts
   const created = await kortix.project(projectId).sessions.create();
   const session = kortix.session(projectId, created.session_id);
   ```

2. Wait for the sandbox to accept work.

   ```ts
   await session.ensureReady();
   ```

   `ensureReady()` starts or resumes the session sandbox. It polls the session's `/start` endpoint — each call long-polls up to 30 s — until the runtime is ready, hits a terminal stage, or its deadline elapses (default ~3 min, configurable via `{ readyTimeoutMs }`). On a cold boot it keeps polling while the sandbox reports `retriable: true`; it only throws an `ApiError` with `code: 'RUNTIME_UNAVAILABLE'` if the runtime is still not ready when the deadline expires. See [Sessions](/docs/sdk/sessions).

3. Send a message to the agent.

   ```ts
   await session.send('Add a README');
   ```

   `send()` calls `ensureReady()` for you, then sends the message.

`createKortix` gives you an imperative client: call methods for every action, like projects, sessions, secrets, and triggers. `@kortix/sdk/react` gives you hooks for live UI data — `useSession` runs a whole session in one hook.

- [Full example](/docs/sdk/example)
Zero to a streaming agent reply.
- [Auth](/docs/sdk/auth)
API keys and Supabase JWTs.
- [Sessions](/docs/sdk/sessions)
Lifecycle, streaming, and error handling.
- [React hooks](/docs/sdk/react)
`useSession` and other reactive hooks.
- [Reference](/docs/sdk/reference)
The full client, modules, turns, and distribution.