SDK reference

Every @kortix/sdk entry point, client member, project and session handle method, and framework-free module, grouped by domain.

This page lists the public surface of @kortix/sdk: each entry point, each member of the client, each method of the project and session handles, and the framework-free modules. It is for developers who already have a client and need the exact method name and arguments. The client table gives the route prefix of each member. To install the package and run a first session, start at SDK.

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

const kortix = createKortix({ backendUrl: 'https://api.kortix.com/v1', getToken });

const p = kortix.project(projectId);           // every project resource, id bound
const s = kortix.session(projectId, sessionId); // one session, both ids bound
await p.secrets.list();
await s.send('Run the tests.');

Each client method calls the Kortix API. Session runtime methods reach the session’s sandbox through the API at {backendUrl}/p/…. Route paths on this page are relative to backendUrl, which ends in /v1. Each route is in the REST reference. A failed call throws an ApiError with status, code and details.

Entry points and stability

Deprecated subpaths and names resolve until the next major version. The package also ships two browser bundles, dist/kortix.esm.min.js and dist/kortix.global.js (window.Kortix). See Install.

@kortix/sdk/server

App viewers are described in Know who is looking.

The client

createKortix(config) returns one client. A second call with a different backendUrl or getToken re-points every earlier client and logs one warning. The options are in Create the client.

kortix.projects

Send idempotency_key (1 to 200 characters of A–Z a–z 0–9 . _ : -, one UUID per create) when a retry is possible. A repeat with the same key returns the first project (201, same project_id). A repeat while the first call still runs returns 409 provision_in_flight: retry with the same key. The key identifies the attempt, not the payload.

kortix.github and kortix.gitBackend

Repositories, branches and change requests are explained in Git.

kortix.marketplace and kortix.sandboxShares

To install an item into a project, see Install from the marketplace.

Accounts, IAM, billing and notifications

kortix.auth

Methods: signUp, signInWithPassword, sendMagicLink, verifyOtp, signInWithProvider, exchangeCode, refresh, resetPassword, updatePassword, updateUserMetadata, signInWithSso, mfa.enroll, mfa.challenge, mfa.verify, mfa.unenroll, user, signOut.

session(options) returns a session store. It saves the tokens through a storage adapter you supply. It refreshes them 60 seconds before they expire. Pass its getToken to createKortix. See Headless sign-in.

kortix.accounts

Account features are explained in Accounts & access, keys in API keys and tokens.

kortix.iam

Kortix has one grant record, the assignment: one principal (user, group, service_account, pending or project), one role, one scope (account or one project), an optional object (agent, skill, secret, app, trigger or connection) and an optional expiresAt.

Gate a control in your UI with can or canBatch on the action the route checks, not on a role name. PROJECT_ACTIONS (root export) names every project action the API answers about, for example PROJECT_ACTIONS.PROJECT_GITOPS_MERGE is project.gitops.merge. The API answers an unknown action with 400. For triggers, probe TRIGGER_CONTROL_ACTIONS and pass the result to triggerControlsFrom(cans): it returns { canCreate, canFire, canUpdate, canDelete }, one flag per trigger route, each false until the probe allows it. Create, update and delete also need project.write, because their routes load the project for write first.

For change requests and the review inbox, probe REVIEW_CONTROL_ACTIONS. changeRequestControlsFrom(cans) returns { canOpen, canMerge, canClose }: open needs project.write + project.gitops.push, merge needs project.write + project.gitops.merge, close and reopen need project.write. reviewVerdictAllowed(item, verdict, cans) says whether to offer one verdict on one review item. Approving a change request merges it, so it follows canMerge. Every other verdict on a change request or a native item needs project.write + project.review.act. A connector call offers approve and reject to the viewer the API lets decide it: a project manager, or the person who launched the session when a person started it (not an API token or a service account). The API says so per call: can_resolve on each SessionAuditAction (getSessionAudit, and the session snapshot’s audit leg), and canResolve on a connector call’s review action (mapApiReviewItem). Show Approve and Deny only when it is not false. A viewer the API would refuse gets the review item with status waiting. resolvers (both shapes) says who decides instead: managers for a session started with an API token or a service account, else managers_and_launcher.

kortix.accountInvites

listMine() lists pending invites addressed to your email. describe(inviteId), accept(inviteId) and decline(inviteId) act on one invite. They need no account membership.

acceptAndLand(inviteId, invite?) accepts and returns { accepted, landing }. landing is where to open: { kind: 'project', projectId, accountId } for the first project the invite granted, or { kind: 'account', accountId } for a workspace invite. Pass the invite you already read (from listMine() or describe()): an accept that grants nothing, such as an admin invite, then lands in the first project the invite names. accountInviteLanding(accepted, invite?) is the same rule without the request, for an invite accepted earlier.

kortix.billing

Before you render a purchase control, ask canOfferTopup(state) (root export) about the account state: true only when the plan may buy credits and the caller may change billing. canManageBilling(state) answers the second half alone. Both return false while state is undefined or null, so a member never sees a control the API answers with 403.

Plans and credits are explained in Plans & credits.

kortix.notifications

Every method needs a person’s credential. A service account gets 403.

Kinds (INBOX_NOTIFICATION_KINDS): turn_done, turn_error, question, permission, shared, automation_failed, automation_recovered. Defaults are in DEFAULT_NOTIFICATION_PREFERENCES. The inbox writes rows only for projects with the notification_center feature flag on. The flag is off by default. While it is off, s.watch() and s.setWatch() return 403 feature_disabled. The session handle adds watch(), setWatch(watching) and presence(…). See Notifications.

kortix.capture

Capture belongs to the account, not to a project. kortix.capture.account(accountId) binds one account. Every account call answers 403 capture_disabled while Capture is off for the account. Each member reads their own devices and timeline. Reading another member needs the capture.read_all permission and writes a capture.member_view audit event. Account owners and admins have it by default. See Capture.

React (@kortix/sdk/react): useCaptureWorkspace, useSetCaptureEnabled, useCaptureDevices (polls every 10 s), useRevokeCaptureDevice, useCapturePolicy, useSetCapturePolicy, useCaptureDays, useCaptureTimeline, useCaptureTimelineItems, useCaptureSearch, useCaptureChunkMedia, useCaptureDeviceGrant, useApproveCaptureDevice, useDenyCaptureDevice. Each account hook takes the account id first. A null id sends no request.

The project handle

kortix.project(projectId) returns p, with the project id bound to every method. Creating the handle sends no request.

Project

Sessions

Each row carries parent_session_id and initiator: { type: 'member' | 'trigger' | 'channel' | 'api' | 'system', id, label }. sessionParentId(session) reads the parent.

Files, git and change requests

These methods read the project repository. To read and write files in a running session, use s.files.

Read a large folder page by page:

let cursor: string | undefined;
do {
  const page = await p.files.listDirectory({ path: 'src', limit: 500, cursor });
  render(page.entries);
  cursor = page.next_cursor ?? undefined; // null or absent ends the loop
} while (cursor);

Routes: /projects/{projectId}/files, /commits, /branches, /version-diff, /change-requests. See Git.

Review and approvals

Policies and approvals are explained in Policies and approvals.

Secrets, tokens and setup links

Exposure policies and flags are explained in Secrets.

Connectors and policies

Accounts, the account a call uses, typed calls and errors are explained in Connectors and Call connectors from code.

Triggers and reminders

Every field of create is in Triggers & reminders.

Apps

Apps are generally available in every project. Apps routes still require project membership and the appropriate Apps permission. Routes: /projects/{projectId}/apps/…. See Build on Apps from TypeScript.

Gateway and models

Routing, fallback and budgets are explained in Models.

Channels

See Slack, Teams & email.

Access

See Project access and Grant access to one object.

Sandbox

See Sandboxes & previews.

Settings and feature flags

p.updateFeatureFlag(key, enabled) sets one flag for the project with PATCH /projects/{projectId}/features. key is one of FEATURE_FLAG_KEYS (type FeatureFlagKey). enabled: null clears the override. The caller needs project.settings.write. A route behind a flag that is off returns 403 { error, code: 'feature_disabled', feature }: test it with isFeatureDisabledError(error) and read the key with featureDisabledKey(error). See Feature flags.

The session handle

kortix.session(projectId, sessionId) (or p.session(sessionId)) returns s. Creating the handle sends no request. Runtime methods call ensureReady() first. Each one is explained in Sessions from code.

Framework-free modules

The root @kortix/sdk exports these modules next to the client. Use them for one operation without the facade, or for pure helpers.

Files

import { FileExistsError, files } from '@kortix/sdk';

const { content } = await files.read('/workspace/README.md');
await files.upload(file, '/workspace/uploads', file.name, {
  onProgress: ({ loadedBytes, totalBytes }) => console.log(loadedBytes, '/', totalBytes),
});

try {
  await files.create('/workspace/notes.md');
} catch (error) {
  if (error instanceof FileExistsError) console.log('exists:', error.path);
  else throw error;
}

• upload sends a file of 8 MiB or less in one request. A larger file goes in 8 MiB chunks, and each chunk is checked on arrival. onProgress runs after each chunk.
• write(path, blob) replaces the file at path. It fails when path is a folder.
• create(path) makes an empty file and never overwrites. When anything exists at path it throws FileExistsError (status 409, code FILE_EXISTS).
• uploadNativeFile({ uri, name, type? }, targetPath?, baseUrl?) uploads a React Native device file in one request. The bytes stream from uri and never enter the JS heap.

Session health

getSessionHealth() never throws on a non-2xx status. It returns { status, ok, health, body, hop, upstreamStatus }. isRuntimeReady(health) is true when the runtime accepts work. s.health() is the same probe for one session.

Custom transcript rendering

Pure functions that turn session messages into renderable parts. Use them to build your own chat view. They have no React and no DOM.

Classify parts and turns

classifyPart(part) turns one part of the Kortix transcript format (kortix.transcript.v1, KORTIX_TRANSCRIPT_SCHEMA) into a ClassifiedPart, keyed by kind:

ToolView fields: name, kind (from toolKind), title, status (pending, running, done, error), input, output, error, outputParsed (the parsed JSON output, for output up to 256 KiB), outputText, files, diff, diagnostics, answers, childSessionId. A tool that reports success: false inside a completed state has status: 'error'. toToolView(part) builds a ToolView from one tool part or one session-log ToolCallBlock. Read these fields, not a harness’s own metadata: the same card then renders every harness.

classifyTurn(message) returns { parts, error?, isEmpty } for one assistant message. isEmpty is true when the turn has no error and no visible part.

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

for (const part of classifyTurn(message).parts) {
  if (part.kind === 'text' && !part.synthetic) render(part.text);
  if (part.kind === 'tool') {
    const view = toolViewModel(part.tool);
    if (view.kind === 'shell') render(view.command, view.stdout, view.exitCode);
  }
}

Tools

• toolKind(name) maps any harness’s tool name to one ToolKind: read, list, glob, grep, write, edit, apply_patch, bash, pty, web_search, webfetch, media, show, task, delegate, sessions, todowrite, question, memory, connectors, automations, projects, skill, context, retired or other.
• toolInfo(name) returns { label, category }. getToolInfo(name, input) returns { icon, title, subtitle } for a tool card. An unknown name falls back to humanizeToolName(name).
• inputPath(input) reads a file tool’s path from filePath, file_path or path.
• toolViewModel(tool) returns one shape per tool family:

Turns, status and helpers

The grouping and status functions accept the structural types PartLike, MessageInfoLike, TurnLike, ToolStateLike and SessionStatusLike, so your own message shapes work. Never mint a message id by hand: use mintWireMessageId().

Session log types

The root exports the types of the Kortix session log, the harness-neutral record of a session, schema kortix.session/2. Kortix stores every session as a session log. The SDK exports the types and three constants, with no validators. In React, useSessionLog and useSessionLogThread return a session’s log once the session reads it: see Read the session log.

A text over 256 kB is stored by reference. This applies to a TextBlock and to a text item of a tool result (ToolResultContent). Its text holds the first 16 kB, bytes holds the UTF-8 length of the full text, and ref is kortix-attachment://<project_id>/<session_id>/<attachment_id>. kortix.session(projectId, sessionId).attachments.read(attachmentId) returns the full text as a Blob (text/plain; charset=utf-8), also while the sandbox is stopped. The v1 transcript reads return the full text.

import type { SessionLog, SessionLogBlock } from '@kortix/sdk';

function toolCalls(log: SessionLog): SessionLogBlock[] {
  return log.threads.flatMap((t) => t.messages.flatMap((m) => m.blocks)).filter((b) => b.type === 'tool_call');
}

Tool calls from v1 parts (transitional)

Three functions bridge a host that renders blocks while its rows are still v1 (useSessionMessages). All three are transitional.

toToolView, getChildSessionId, partOutcome, contextToolTrigger and shouldShowToolPart accept a ToolCallBlock as well as a v1 tool part, and return the same answer for both.

import { getChildSessionId, toolCallBlock, toolCallMetadata } from '@kortix/sdk';

const call = toolCallBlock(part); // part: a v1 tool part from useSessionMessages
const child = getChildSessionId(call); // a running task's child session
const command = toolCallMetadata(call).command; // bash

Reading a tool call

What a host draws a ToolCallBlock with. Block-native: they stay.

Block turns

The turn model over session-log blocks: what a transcript renders a thread from. Each name replaces a v1 helper over MessageWithParts (see Turns, status and helpers); the v1 helpers stay until the next major.

A pending permission or question matches a call by call.call_id: getPermissionForTool(permissions, call.call_id), getQuestionForTool(questions, call.call_id). freshSendHint and fallbackBusyRowAfterTurnId accept a SessionLogTurn[] as well as v1 turns, and stepLabel any session-log block (a non-call block reads by its type).

import { sessionLogTurns, sessionLogTurnSegments, sessionLogCallStatus } from '@kortix/sdk';

const turns = sessionLogTurns(thread, { busy, liveMessageId: working.turnId, held: heldIds, threads: log.threads });
for (const turn of turns) {
  for (const segment of sessionLogTurnSegments(turn.blocks)) {
    if (segment.kind === 'standalone') render(segment.block, sessionLogCallStatus(segment.block, turn.live));
  }
}

Deprecated names

Each name below is marked @deprecated and stays until the next major version. Your editor flags each call.

Other deprecated root names wrap routes that the API does not serve. They reject with ENDPOINT_RETIRED, resolve null, or return 404, and they have no replacement.