SDK

@kortix/sdk: one typed client for projects, sessions, connectors and the session runtime, for browsers, Node, Bun and edge runtimes.

@kortix/sdk is the TypeScript client for the Kortix API. It covers projects, sessions, connectors, secrets, accounts and the live runtime of each session. Use it to start and drive sessions from your own app, server, script or CI job.

Install

npm install @kortix/sdk

Import from the root. Two other subpaths are stable. @kortix/sdk/wire-message-id holds the wire-id clock in one module with no imports, and the root exports the same names. @kortix/sdk/workspace-search adds ranked file search over a session workspace, and the root does not export it. The other subpaths (@kortix/sdk/turns, @kortix/sdk/projects-client and similar) are deprecated aliases of root names. The full list is in Entry points and stability.

For a page with no build step, load the browser bundle. It defines window.Kortix with the same names as the root, for example Kortix.createKortix:

<script src="https://cdn.jsdelivr.net/npm/@kortix/sdk@<version>/dist/kortix.global.js"></script>

The package also ships an ES module bundle at dist/kortix.esm.min.js. Replace <version> with a published version.

A browser page calls the Kortix API directly only from an origin the API allows. Kortix Cloud allows its own origins. From your own site, send browser calls through your server, for example the same-origin proxy of Sign in with Kortix. A self-hosted instance adds origins with the API’s CORS_ALLOWED_ORIGINS setting.

Create the client

Call createKortix once per host, with the API base URL and a function that returns a token.

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

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

The client holds one configuration for the whole process. A second createKortix() call with a different backendUrl or getToken re-points every earlier client and logs one console warning. A server that acts for many people at the same time uses createScopedKortix() from @kortix/sdk/server. See Authentication.

The client exposes these handles:

The full map is in the SDK reference.

Get an API key

A script, a CI job or a server uses a personal access key (kortix_pat_, Settings → Personal access keys or kortix tokens new). Unattended automation uses a service account key (kortix_sa_, Account settings → API keys). Every credential: Choose a credential.

Kortix shows the key once. Store it as a secret and return it from getToken. Never put a personal access key in a browser bundle: a browser app signs people in with Sign in with Kortix instead.

Your first session

A session is one unit of agent work, on its own sandbox and branch. From code, it takes six steps.

The same calls work on both session harnesses, OpenCode and pi. See Harnesses.

A complete script

This file lists your projects, creates a session, waits for one turn, and prints the transcript.

import { classifyTurn, createKortix, narrowChatEvent } from '@kortix/sdk';

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

async function main() {
  // 1. Pick a project, or create one.
  const projects = await kortix.projects.list();
  const project = projects[0] ?? (await kortix.projects.provision({ name: 'my-project' }));

  // 2. Create a session. The sandbox starts to provision now.
  const { session_id } = await kortix.project(project.project_id).sessions.create({
    name: 'sdk first session',
  });
  const session = kortix.session(project.project_id, session_id);

  // 3. Wait for the runtime. runtimeSessionId names the root conversation.
  const { runtimeSessionId } = await session.ensureReady();

  // 4. Open the stream before you send, so no event is lost.
  let sent = false;
  let finish!: () => void;
  const turnDone = new Promise<void>((resolve) => (finish = resolve));
  const stream = await session.stream({
    onEvent: (raw) => {
      const event = narrowChatEvent(raw);
      if (!event || !sent) return;
      if (event.type === 'session.error' && (!event.sessionID || event.sessionID === runtimeSessionId)) {
        console.error('session error:', event.error);
        finish();
      }
      if (event.type === 'session.idle' && event.sessionID === runtimeSessionId) finish();
    },
  });

  // 5. Send the prompt and wait for the turn to end.
  sent = true;
  await session.send('List the files in this repository.');
  await turnDone;
  stream.close();

  // 6. Print the transcript.
  const { messages } = await session.messages();
  for (const message of messages) {
    for (const part of classifyTurn(message).parts) {
      if (part.kind === 'text' && !part.synthetic) console.log(`[${message.info.role}] ${part.text}`);
    }
  }
  console.log(`session: ${session_id}`);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Run it with tsx or Bun:

KORTIX_API_KEY=kortix_pat_... npx tsx first-session.ts

KORTIX_API_KEY=kortix_pat_... bun first-session.ts

Each run creates a new session, so ensureReady() waits while its sandbox boots. The session also appears in the web app, with the same transcript.

• narrowChatEvent reduces the raw runtime events to the set a chat needs: message and part updates, session status, idle and error, questions, permissions and todos.
• send(text, { model, agent }) overrides the model ({ providerID, modelID }) or the agent for one prompt. Model ids come from kortix.projects.modelPicker(projectId). Agent names come from kortix.projects.detail(projectId), in config.agents.
• To print text while it streams, to answer questions and permission requests, or to handle errors, see Sessions from code.

Versions and stability

• @kortix/sdk publishes to npm with each Kortix platform release and carries the release’s version number.
• Exported names, including types, are the public contract. A renamed export keeps a @deprecated alias that works until the next major version.
• The deprecated subpaths resolve until the next major version.
• @kortix/sdk/internal/* serves the Kortix web app and is outside semver. It can change in any release.
• Changes per release: the CHANGELOG.
• Runnable examples, from one projects.list() call to a multi-tenant server: packages/sdk/examples on GitHub. The npm package does not include them.

Next steps