Getting Started

Install the SDK, create a client, and make your first API call in under two minutes.

Installation

bun add @kapable/sdk

[dependencies]
kapable-sdk = { git = "https://git.kapable.dev/kapable/kapable-sdk-rs.git" }

Create a Client

import { KapableClient } from '@kapable/sdk';

const client = new KapableClient({
  baseUrl: 'https://api.kapable.ai',
  apiKey: 'sk_live_...',
});

use kapable_sdk::KapableClient;

let client = KapableClient::new("https://api.kapable.ai")
    .api_key("sk_live_...")
    .build();

Constructor Options

Option	Type	Description
`baseUrl`	`string`	API base URL (e.g. `https://api.kapable.ai`)
`apiKey`	`string?`	API key for `x-api-key` header auth
`token`	`string?`	JWT bearer token (mutually exclusive with apiKey)
`timeout`	`number?`	Request timeout in ms (default: 30000)

First API Call

The SDK exposes typed sub-clients for each service: client.board, client.store, client.data, client.comms, and client.knowledge. Each method maps 1:1 to a REST endpoint.

// List all stories with status "active"
const { data: stories, total } = await client.board.listStories({
  status: 'active',
  limit: 10,
});

console.log(`${total} active stories, showing first ${stories.length}`);
for (const story of stories) {
  console.log(`  ${story.code}: ${story.title}`);
}

// Rust SDK
use kapable_sdk::board::types::ListStoriesQuery;

let query = ListStoriesQuery {
    status: Some("active".into()),
    limit: Some(10),
    ..Default::default()
};
let result = client.board().list_stories(query).await?;

println!("{} active stories, showing first {}", result.total, result.data.len());
for story in &result.data {
    println!("  {}: {}", story.code, story.title);
}

Pagination

List endpoints return a ListResponse<T> with data and total. Use limit and offset for manual pagination, or the built-in async generators for automatic iteration:

// Auto-paginate through all stories
for await (const story of client.board.paginateStories({ status: 'active' })) {
  console.log(story.code, story.title);
}

// Rust SDK -- manual pagination
let mut offset = 0;
loop {
    let query = ListStoriesQuery {
        status: Some("active".into()),
        limit: Some(50),
        offset: Some(offset),
        ..Default::default()
    };
    let page = client.board().list_stories(query).await?;
    for story in &page.data {
        println!("{} {}", story.code, story.title);
    }
    offset += page.data.len() as i64;
    if offset >= page.total { break; }
}

Error Handling

All SDK methods throw a KapableError on non-2xx responses. The error includes the HTTP status, a machine-readable code, and a human message.

import { KapableError } from '@kapable/sdk';

try {
  await client.board.getStory('nonexistent');
} catch (err) {
  if (err instanceof KapableError) {
    console.error(`${err.status} ${err.code}: ${err.message}`);
    // 404 not_found: Story not found
  }
}

// Rust SDK
use kapable_sdk::KapableError;

match client.board().get_story("nonexistent").await {
    Ok(story) => println!("Found: {}", story.title),
    Err(KapableError::Api { status, code, message }) => {
        eprintln!("{status} {code}: {message}");
        // 404 not_found: Story not found
    }
    Err(e) => eprintln!("Other error: {e}"),
}

Next Steps

Authentication

API keys, JWT tokens, and org context.

Board API

Stories, sprints, plans, and products.

Data API

Dynamic tables and row CRUD.