TypeScript 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

npm install @kortix/sdk

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

Create a client

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

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 in your own settings, at Settings → API keys (/settings/tokens). The key starts with kortix_pat_ and shows only once. Store it as a secret and return it from getToken. See Auth for token types and scopes.

Call a Connector

A Connector defines callable tools. A Connection stores one account — one authorization — for that Connector; a Connector can hold several accounts side by side. Credentials stay server-side.

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.

A call that names no account resolves to a default automatically. To run as a specific one, list connectors.accounts(slug) and pass a connection_id, label, or me / project as options.account on call(). See Accounts and the call-time gate.

Start your first session

1. Create a session in your project.

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

2. Wait for the sandbox to accept work.

   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.

3. Send a message to the agent.

   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.