Kaiban TypeScript SDK

Official TypeScript SDK for the Kaiban API.

Install

npm install @kaiban-sdk

Quickstart

import { createKaibanClient } from '@kaiban-sdk';

const client = createKaibanClient({
  tenant: 'agi',
  token: process.env.KAIBAN_TOKEN,
});

const agents = await client.agents.list();

Auth and tenancy

• Uses Authorization: Bearer <token> automatically when provided
• Sends x-tenant with the configured tenant
• Default base URL: https://{tenant}.kaiban.io

Resources

• agents: list, get, update, feedback
• teams: list, get
• team-members: list, get
• boards: list, get
• cards: list, get, create, update, delete, moveToColumn
• activities: list, create, updateBulk
• resources: list, get, publish
• benchmarks: list, get, create, update, execute
• benchmark-executions: list, get, create, update, delete, test-cases CRUD
• external-channels: list, get
• supervisor-feedback: list by agent

Types

Types are published under the package and re-exported from @kaiban-sdk (e.g., Agent, Card, BenchmarkExecution).

Configuration

createKaibanClient({
  tenant: 'agi',
  token: '...optional...',
  baseUrl: 'https://custom-host',
  timeoutMs: 30000,
});

Per-call options

All resource methods accept optional per-call overrides:

// Headers, query params, timeout override, and AbortSignal
await client.cards.list({
  headers: { 'x-request-id': 'abc-123' },
  query: { status: 'doing' },
  timeoutMs: 10_000,
  signal: new AbortController().signal,
});

Error handling

import { createKaibanClient, HttpError } from '@kaiban-sdk';

try {
  await client.cards.get({ id: 'non-existent' });
} catch (err) {
  if (err instanceof HttpError) {
    console.error('HTTP error', err.status, err.url, err.body);
  } else {
    console.error('Unexpected error', err);
  }
}

Examples by resource

Agents

// List agents
const agents = await client.agents.list();

// Get agent by id
const agent = await client.agents.get({ id: 'agent_123' });

// Update agent
const updated = await client.agents.update({ id: 'agent_123', body: { description: 'New desc' } });

// Create agent feedback
await client.agents.createFeedback({ id: 'agent_123', feedback: { rating: 5, comment: 'Great' } });

Teams

const teams = await client.teams.list();
const team = await client.teams.get({ id: 'team_123' });

Team Members

const members = await client.teamMembers.list();
const member = await client.teamMembers.get({ id: 'member_123' });

Boards

const boards = await client.boards.list();
const board = await client.boards.get({ id: 'board_123' });

Cards

import type { CreateCardInput, UpdateCardInput } from '@kaiban-sdk';

// Create a card
const createBody: CreateCardInput = {
  team_id: 'team_123',
  board_id: 'board_123',
  owner_id: 'user_123',
  agent_id: 'agent_123',
  title: 'Investigate issue',
  status: 'backlog',
  column_key: 'inbox',
  priority: 'medium',
  member_ids: [],
};
const newCard = await client.cards.create({ body: createBody });

// Get a card
const card = await client.cards.get({ id: newCard.id });

// Update a card
const updateBody: UpdateCardInput = { status: 'doing', priority: 'high' };
const updatedCard = await client.cards.update({ id: card.id, body: updateBody });

// List cards
const cards = await client.cards.list();

// Delete a card
await client.cards.delete({ id: card.id });

// Activities
const activities = await client.activities.list({ card_id: card.id });
await client.activities.create({
  card_id: card.id,
  body: {
    board_id: card.board_id,
    team_id: card.team_id,
    card_id: card.id,
    type: 'card_comment_added',
    description: 'FYI',
    actor: { id: 'user_1', type: 'user', name: 'Alice' },
  },
});
await client.activities.updateBulk({ card_id: card.id, body: activities });

Resources

const resources = await client.resources.list();
const resource = await client.resources.get({ id: 'resource_123' });
await client.resources.publish({ resource_id: 'resource_123', userId: 'user_123' });

Benchmarks

import type { CreateBenchmarkInput, UpdateBenchmarkInput } from '@kaiban-sdk';

const created = await client.benchmarks.create({
  body: { name: 'My Benchmark' } satisfies CreateBenchmarkInput,
});
const benchmark = await client.benchmarks.get({ id: created.id });
await client.benchmarks.update({
  id: benchmark.id,
  body: { description: 'Updated' } satisfies UpdateBenchmarkInput,
});

// Execute a benchmark
await client.benchmarks.execute({
  benchmark_id: benchmark.id,
  body: { agentConfig: { id: 'agent_123' }, maxTests: 5 },
});

Benchmark Executions

import type { CreateBenchmarkExecutionInput } from '@kaiban-sdk';

// Create execution
const execution = await client.benchmarkExecutions.create({
  body: {
    benchmark_id: 'bench_123',
    agent_id: 'agent_123',
  } satisfies CreateBenchmarkExecutionInput,
});

// Get / update / delete
const fetched = await client.benchmarkExecutions.get({ id: execution.id });
await client.benchmarkExecutions.update({ id: fetched.id, body: { status: 'running' } });
await client.benchmarkExecutions.delete({ id: fetched.id });

// Test cases
const testCase = await client.benchmarkExecutions.createTestCase({
  execution_id: execution.id,
  body: { test_index: 1, input: 'hello', agent_output: 'world', execution_time: 1000 },
});
const testCases = await client.benchmarkExecutions.listTestCases({ execution_id: execution.id });
const oneTestCase = await client.benchmarkExecutions.getTestCase({
  execution_id: execution.id,
  test_case_id: testCase.id,
});
await client.benchmarkExecutions.updateTestCase({
  execution_id: execution.id,
  test_case_id: testCase.id,
  body: { passed: true },
});
await client.benchmarkExecutions.deleteTestCase({
  execution_id: execution.id,
  test_case_id: testCase.id,
});

External Channels

const channels = await client.externalChannels.list();
const channel = await client.externalChannels.get({ id: 'ext_123' });

Supervisor Feedback

const feedback = await client.supervisorFeedback.listByAgent({ agent_id: 'agent_123' });