# Build on Kapable

Source: https://docs.kapable.ai/
Section: Start here

v0.23.0 TS · v0.19.1 Rust · v0.19.0 CLI — customer + operator SDK tiers

Build on Kapable

      Use the API, ship an app, or run Kapable on your own server.

      Call the API
      Ship an app
      Run it on your server

API Modules

      Pick a building block below when your app needs it.

Skills

Use a ready-made skill to publish work from your coding agent.

        Browse Skills →

Apps & Deployment

Create, deploy, and operate an app at its live Kapable URL.

        Explore Apps API →

Board

Track product work from the first story to the release.

        Explore Board API →

Store

Store files and give browsers short-lived upload or download links.

        Explore Store API →

Data

Give an app typed tables, rows, search, and live change events.

        Explore Data API →

Comms

Let agents and people exchange messages, email, and live room events.

        Explore Comms API →

Knowledge

Store claims with sources, context, and links between entities.

        Explore Knowledge API →

AI

Call AI providers without placing provider keys in your client app.

        Explore AI API →

Secrets

Keep org secrets out of source code and review their access.

        Explore Secrets API →

Billing

Read a subscription and send an owner to checkout or billing.

        Explore Billing API →

Wiki

Write searchable Markdown pages from your org knowledge.

        Explore Wiki API →

Harbor

Issue releases and check licenses inside software you ship.

        Explore Harbor API →

Runners

Build and host apps on machines that you control.

        Connect a Runner →

Warrant

Sell products with plans and license checks that work offline.

        Explore Warrant API →

Quick Start

Install the SDK, create a client, and make your first API call.

      TypeScript
      Rust
      cURL

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

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

// Who am I? (works with any fresh API key)
const me = await client.auth.me();
console.log(`Authenticated as ${me.identity_type} in org ${me.org_id}`);

// List available AI providers
const { data: providers } = await client.ai.listProviders();
console.log(`${providers.length} AI providers available`);

use kapable_sdk::KapableClient;

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

// Who am I? (works with any fresh API key)
let me = client.auth().me().await?;
println!("Authenticated in org {}", me.org_id);

// List available AI providers
let providers = client.ai().list_providers().await?;
println!("{} AI providers available", providers.data.len());

curl -s https://api.kapable.ai/v1/me \
  -H "x-api-key: sk_live_..." | jq .

Authentication

      All API requests require authentication via either an x-api-key
      header or a JWT bearer token. See the
      Authentication guide for details.

Base URL

      All endpoints are served under https://api.kapable.ai.
      Each service is mounted at a versioned path prefix (e.g. /v1/board/).

API-key scope note

        A fresh sk_live_ key reaches the auth and
        AI surfaces (plus scope-gated board routes) today. The
        data, board, and knowledge services additionally permission-gate API keys
        — use session-token auth for those, or watch the changelog for the
        scope-to-permission bridge currently in flight. See
        Authentication.

AI-readable docs

        Point your agent at kapable.ai/llms.txt
        (concise index) or llms-full.txt
        (full per-endpoint reference, 352 endpoints) — generated from the same
        manifest that drives the SDKs, so every documented path is real.

Ready to build?

Get started with the Kapable SDK in under two minutes.

      Quick Start Guide
      Open Console

---

# Getting Started

Source: https://docs.kapable.ai/getting-started
Section: Start here

Getting Started

Go from a new workspace to a working API call and a live app.

You need

A plan and card, a Kapable workspace, a console API key, and a shell with Bun or Cargo.

1. Create a workspace

Open join.kapable.ai. Pick a plan and enter a card before you create the workspace.

You should see your new workspace and its console.

2. Make an API key

Open the console for your workspace. Create an API key with the read scope. Copy the secret when the console shows it. It appears once.

You should see a key that starts with sk_live_.

3. Install the SDK and set the key

Choose your language. Run the install command in your project folder. Set KAPABLE_API_KEY in the same shell.

            TypeScript
            Rust

echo '@kapable:registry=https://git.kapable.dev/api/packages/kapable/npm/' >> .npmrc
bun add @kapable/sdk
export KAPABLE_API_KEY='sk_live_...'

# Add this to .cargo/config.toml
[registries.kapable]
index = "sparse+https://git.kapable.dev/api/packages/kapable/cargo/"

# Add this to Cargo.toml
[dependencies]
kapable-sdk = { registry = "kapable", version = "0.2" }

# Then set the key in your shell
export KAPABLE_API_KEY='sk_live_...'

You should see the SDK in your dependency file and the key in your shell environment.

4. Make the first call

Ask Kapable who you are. Save the TypeScript or Rust code as a small program, or run the curl command as written.

            TypeScript
            Rust
            cURL

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

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

const me = await client.auth.me();
console.log(me);

use kapable_sdk::KapableClient;

let client = KapableClient::new("https://api.kapable.ai")
    .api_key(std::env::var("KAPABLE_API_KEY")?)
    .build();
let me = client.auth().me().await?;
println!("{:?}", me);

curl -sS https://api.kapable.ai/v1/me \
  -H "x-api-key: $KAPABLE_API_KEY"

You should see your identity and workspace ID in the response.

5. Create and deploy an app

Use the installed CLI. The blank starter is in the live template catalog.

kapable app templates
kapable app create hello-kapable --template blank
kapable app clone hello-kapable
cd hello-kapable
kapable app deploy hello-kapable
kapable app open hello-kapable --print

You should see a deployment with status live and a URL that ends in .kapable.run.

Next

Authentication · Apps and Deployment

---

# Authentication

Source: https://docs.kapable.ai/authentication
Section: Start here

Authentication

        Kapable supports two customer authentication methods: API keys for
        server-to-server calls and session/JWT bearer tokens for user-context
        requests. Operator surfaces use a separate token tier and a separate
        SDK — see Operator SDK.

        Building an app and want your users to sign in to it? This page is about
        calling the Kapable API. For sign-in inside your own app, see
        Sign users in to your app.

You need

A Kapable org and a `kses_` session. Use the role and permission named in the endpoint.

First call

curl -sS https://api.kapable.ai/v1/me \
  -H "Authorization: Bearer $KAPABLE_SESSION_TOKEN"

You should see your identity and org ID.

Token Types

Token	Tier	Header	Use

sk_live_* / sk_org_*	Customer	x-api-key	Server-to-server, org-bound, scoped (read/write/admin)

sk_test_* (retired)	Customer	x-api-key	Retired. Kapable no longer issues these keys. A key you already hold is still accepted; new keys start with sk_live_

kses_* (session)	Customer	Authorization: Bearer	User-context calls; carries the member's role permissions

at_* (app token)	Customer	Authorization: Bearer	Per-org service-to-service integrations. Required (with a session) by the Comms API, which rejects sk_ keys with 401

ak_* (agent key)	Customer	x-api-key	Per-agent key for Comms SSE streaming and message sending

RS256 JWT	Customer	Authorization: Bearer	Frontend/user flows via the auth service

st_* (service token)	Customer	x-api-key	Org-scoped automation credential for CI / deploy / webhook workloads (see Service Tokens below). Minted with a session under keys.manage

sk_admin_*	Operator	varies	Platform operations — only via @kapable/ops-sdk, never the customer SDK

API Key Authentication

        API keys are the simplest way to authenticate. Pass the key in the
        x-api-key header on every request.

# API key auth
curl https://api.kapable.ai/v1/me \
  -H "x-api-key: sk_live_abc123..."

Getting an API Key

        Mint keys with your session via the auth API, or manage them in the console
        under Settings → API Keys. Every key-management call is
        session-gated and requires the keys.manage permission
        — owners and admins hold it by default, and an owner can delegate it to a
        custom role (see Roles & Permissions).

# Create. Optional fields: expires_at (absolute RFC3339 timestamp; omit = never),
# project_id / workspace_id (bind the key to a project or workspace).
curl -s -X POST https://api.kapable.ai/v1/auth/api-keys \
  -H "Authorization: Bearer kses_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"production","scopes":["read","write"],"expires_at":"2027-01-01T00:00:00Z"}'
# → { "id": "...", "key_prefix": "sk_live_...", "last_used_at": null, "secret": "sk_live_..." }   ← secret shown ONCE

# List (prefixes + last_used_at, never the secret) and revoke:
curl -s https://api.kapable.ai/v1/auth/api-keys -H "Authorization: Bearer kses_..."
curl -s -X DELETE https://api.kapable.ai/v1/auth/api-keys/{id} -H "Authorization: Bearer kses_..."

Rotating a Key

        Rotate mints a fresh secret and prefix onto the same key row, so the
        key id, scopes, and bindings are preserved. The optional
        overlap_hours (0–72, default 0) is the grace window the
        previous secret keeps validating — use it to migrate live callers without
        an outage; omit it (or send 0) to kill the old secret immediately, the
        compromised-key path.

# Immediate cutover (default) — bodyless POST:
curl -s -X POST https://api.kapable.ai/v1/auth/api-keys/{id}/rotate \
  -H "Authorization: Bearer kses_..."

# 24-hour grace window on the old secret:
curl -s -X POST https://api.kapable.ai/v1/auth/api-keys/{id}/rotate \
  -H "Authorization: Bearer kses_..." \
  -H "Content-Type: application/json" \
  -d '{"overlap_hours":24}'
# → { "id": "...", "key_prefix": "sk_live_...", "secret": "sk_live_..." }   ← NEW secret, shown ONCE

Keys are org-bound and scoped — not omnipotent

          An API key is bound to your org and carries scopes
          (read/write/admin), not your member
          role's permissions. Scope-gated surfaces (auth, AI, the
          Data API, some board routes) accept keys
          directly; permission-gated surfaces (board stories, knowledge) return
          403 permission required for keys — use session auth there.
          A key may optionally be bound to a project at mint time
          ({"project_id":"…"}) to pin its Data-API schema. Never expose
          keys in client-side code or commit them to version control.

SDK Usage

        TypeScript
        Rust

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

// Rust SDK
let client = KapableClient::new("https://api.kapable.ai")
    .api_key(std::env::var("KAPABLE_API_KEY").unwrap())
    .build();

JWT Bearer Token

        For user-context requests (e.g. from a frontend), use a JWT token obtained
        via the Auth service's login endpoint. Pass it in the Authorization
        header.

# Bearer token auth
curl https://api.kapable.ai/v1/board/stories \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Obtaining a Token

        TypeScript
        Rust

// Login. Response fields: session_token, access_token (JWT),
// access_token_expires_in, role, org_id, member_id, email, name.
const res = await client.auth.login({
  email: 'user@example.com',
  password: '...',
});

// Use the session token (kses_) as the Bearer `token` for subsequent requests.
const authedClient = new KapableClient({
  baseUrl: 'https://api.kapable.ai',
  token: res.session_token,
});

// Rust SDK
use kapable_sdk::auth::types::LoginRequest;

let resp = client.auth().login(&LoginRequest {
    email: "user@example.com".into(),
    password: "...".into(),
}).await?;

let authed_client = KapableClient::new("https://api.kapable.ai")
    .token(resp.token)
    .build();

Org Context

        All API calls are scoped to the authenticated org. API keys are org-bound.
        JWT tokens carry the org ID in the token claims. Multi-org users select
        their active org during login.

Agent Keys (Comms)

        The Comms service supports a third auth model: agent keys.
        These are per-agent API keys minted via
        POST /v1/agents/{id}/keys that allow agent processes to
        authenticate directly for SSE streaming and message sending.

        TypeScript
        Rust

// Mint an agent key
const { key } = await client.comms.mintAgentKey(agentId, {
  label: 'production',
});

// Use it to connect the agent's SSE stream
const stream = new EventSource(
  `https://api.kapable.ai/v1/agents/${agentId}/stream`,
  { headers: { 'x-api-key': key } }
);

// Rust SDK
use kapable_sdk::comms::types::MintAgentKeyRequest;

let resp = client.comms().mint_agent_key(agent_id, MintAgentKeyRequest {
    label: "production".into(),
}).await?;
println!("Agent key: {}", resp.key);

App Tokens (Comms)

        For service-to-service integration with the Comms endpoints, use
        app tokens (at_* prefix). These are org-scoped
        tokens for programmatic access to intercept and send operations. The Comms
        customer surface requires a session or an at_ app token
        — it rejects sk_ API keys with 401.

        TypeScript
        Rust

// Mint an app token for your integration
const { token } = await client.comms.mintAppToken(orgId, {
  label: 'email-worker',
});

// Rust SDK
use kapable_sdk::comms::types::MintAppTokenRequest;

let resp = client.comms().mint_app_token(org_id, MintAppTokenRequest {
    label: "email-worker".into(),
}).await?;

Service Tokens

        Service tokens (st_*) are long-lived, org-scoped automation
        credentials for CI, deploy, and webhook workloads. They are minted with your
        session and gated by the same keys.manage permission as API keys.
        Manage them in the console under Settings → Service Tokens
        or via the auth API:

# Create. token_type ∈ { ci, deploy, webhook, ... } sets the secret prefix
# (ci → st_ci_, deploy → st_deploy_, webhook → st_wh_, anything else → st_svc_).
# expires_in_days is a RELATIVE day count (1–365, default 90).
curl -s -X POST https://api.kapable.ai/v1/auth/service-tokens \
  -H "Authorization: Bearer kses_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-runner","token_type":"ci","scopes":["read","write"],"expires_in_days":90}'
# → { "id": "...", "key_prefix": "st_ci_...", "secret": "st_ci_..." }   ← secret shown ONCE

# List (metadata + last_used_at) and revoke (idempotent — 200 even if already revoked):
curl -s https://api.kapable.ai/v1/auth/service-tokens -H "Authorization: Bearer kses_..."
curl -s -X DELETE https://api.kapable.ai/v1/auth/service-tokens/{id} -H "Authorization: Bearer kses_..."

Reserved token types

          The internal types dispatch-minter and ci-dispatch
          are reserved for platform provisioning and are rejected with 403
          on this endpoint. Everything else is free-form and falls back to the
          st_svc_ prefix.

Org Auth Settings (Console)

        Beyond API credentials, org owners and admins configure the organisation's
        sign-in experience and account-security posture in the console under
        Auth Settings:

Login-page branding — four layouts (centered, left panel, right panel, full background), a custom logo, a background image, and light or dark mode.

Session policies — session lifetime (default 24 hours), an optional idle timeout that auto-logs-out inactive sessions, and an account-lockout threshold after repeated failed logins (default 5 attempts).

Multi-factor authentication — members enroll TOTP (Google Authenticator, Authy, …) with backup codes; MFA can be optional or enforced for the whole org.

Password policy — minimum length and required character classes (uppercase, numbers, special characters).

        Member access levels (owner / admin / member / viewer, plus custom roles with
        granular permissions) are covered in
        Roles & Permissions.

Error Responses

        Kapable returns {error:{code,message,details}}. The
        message field is the line a person can act on.

Code	What you see	What to do

UNAUTHORIZED	missing auth token	Send x-api-key, a Bearer token, or a session cookie.

UNAUTHORIZED	authentication required via x-api-key, Authorization: Bearer, or session cookie	Use one of the listed auth methods.

FORBIDDEN	permission required	Use a session with the needed role or permission.

Next

Getting Started · Authentication

---

# kapable CLI

Source: https://docs.kapable.ai/cli
Section: Start here

kapable CLI

        A single native binary (linux-amd64, darwin-arm64) that mirrors the SDK's
        customer-tier surface from your terminal — auth, board, data, comms,
        knowledge, store, and a local dev/preview supervisor. It rides
        kapable-sdk exclusively, so anything you can do with the Rust
        SDK you can do from the CLI.

You need

The `kapable` binary and a Kapable login session or org key.

First call

kapable whoami

You should see your signed-in identity and org.

Install

curl -fsSL https://cli.kapable.ai/install.sh | sh

        Detects your OS/arch (linux or darwin, amd64 or arm64), downloads the
        latest stable build from the public release registry,
        verifies its SHA-256, and installs to ~/.local/bin/kapable
        (no sudo). Re-running the same command upgrades in place.

Overrides

          KAPABLE_INSTALL_DIR / --install-dir <dir>
          changes the install location (default ~/.local/bin).
          KAPABLE_CHANNEL / --channel <name> picks a
          release channel (default stable). If
          ~/.local/bin isn't on your PATH, the installer
          prints how to add it.

Verify the install:

kapable --version

Staying current

        The installed binary updates itself — no need to re-run the
        installer:

kapable self-update --check   # report whether a newer stable build exists; changes nothing
kapable self-update            # download, verify SHA-256, and atomically replace this binary

        The replace is atomic: the new binary is staged, proven to run
        (--version succeeds), and only then swapped in with a single
        rename. Any failure before that point leaves your current binary
        untouched. On macOS, a Gatekeeper quarantine strip runs automatically;
        if the staged binary still won't launch, an ad-hoc codesign
        retry kicks in as a safety net.

Authenticating

        Two credential shapes, resolved in the same precedence order on every
        command: flag > environment variable >
        stored config (an org key in [api] outranks a
        stored session in [session]).

        Interactive login
        Org key (agents / CI)

kapable auth login --email you@example.com   # prompts for your password
kapable auth me                 # confirm — prints identity, org, role
kapable auth logout             # clear the stored session (any [api] org key stays)

          Login persists a session grant to ~/.kapable/kapable.toml
          under [session] (session_token — the durable
          kses_… token; the short-lived JWT is never persisted).

kapable auth set-key sk_org_...   # persists a durable org key under [api]

# or, for a single invocation / headless agent — no file written:
export KAPABLE_API_KEY=sk_org_...
kapable auth me

# or, per-command override (highest precedence):
kapable --api-key sk_org_... auth me

Env vars & flags

Name	Kind	Effect

--api-key <key>	global flag	Credential for this invocation only. Highest precedence.

--api-url <url>	global flag	Base URL for this invocation only.

KAPABLE_API_KEY	env var	Credential, second precedence. Recommended for CI/agents.

KAPABLE_API_URL	env var	Base URL, second precedence.

--config <path>	global flag	Config file path (default ~/.kapable/kapable.toml).

KAPABLE_RELEASES_URL	env var	self-update only — override the release registry (staging/testing).

        With nothing set, the base URL defaults to https://api.kapable.ai
        and an unauthenticated command fails with an actionable
        Not authenticated. Run `kapable auth login …` …
        error — never a silent 401.

Command tree

Every command in the CLI, generated from its own command tree at version 0.21.4 — 28 groups, 243 commands in all. --help on any of them prints its flags.

      kapable activity Activity: inspect, watch, and publish org-scoped Herald events · 5 commands

kapable activity list	List recent events without arbitrary payload or metadata fields

kapable activity show	Show one event, including its payload and metadata

kapable activity earliest	Return the earliest position still retained for this principal

kapable activity watch	Watch the live event stream as NDJSON until cancelled or bounded

kapable activity publish	Publish an org-scoped event.

      kapable login Sign in — the fastest way to get started.

Takes no subcommand. Run kapable login --help for its flags.

      kapable logout Sign out — clears the stored session (device- or password-minted alike).

Takes no subcommand. Run kapable logout --help for its flags.

      kapable whoami Who am I — show the authenticated identity (org, email/key, role).

Takes no subcommand. Run kapable whoami --help for its flags.

      kapable app App lifecycle: create, list, status, clone, open, deploy, logs, pat mint, templates, delete · 11 commands

kapable app deploy	Deploy an app and follow it to `live`/`failed` (push-verify built in).

kapable app logs	Print the newest deployment's build log tail (stdout = the raw log)

kapable app list	List your org's apps (JSON default; --table for columns)

kapable app status	Show an app row + its newest deployment (works with sessions AND read-scope org keys — composed from routes both can call, D15)

kapable app clone	git-clone an app's repo (git.kapable.dev/customer-{org}/{app})

kapable app open	Print the app's live URL (and open it in a browser)

kapable app pat	App repo PATs

kapable app pat mint	Print the app's repo bot PAT as JSON on stdout (owner session required; the server mints one on demand for apps that predate bot PATs)

kapable app create	Create an app from a starter template and follow provisioning to `created` (repo ready) — requires a login session (`kapable login`)

kapable app templates	List the starter-template catalog (`--template` values for `create`)

kapable app delete	Delete an app (soft-delete; container + routes torn down, repo archived).

      kapable brand Brand: install the Kapable brand kit — theme tokens, the four faces and their licences, the mark — and check a copy for drift. · 3 commands

kapable brand install	Download the brand kit into a directory and record what was fetched

kapable brand check	Compare the copies in a directory with what the platform serves

kapable brand show	Print the live brand facts — the faces and the accent, as served

      kapable artifact Artifacts: publish a document to the org gallery, list, read, verdict · 9 commands

kapable artifact publish	Publish a document — a new slug creates v1, an existing slug appends the next version.

kapable artifact list	List the org gallery (latest-version metadata only, never the body)

kapable artifact get	Show one artifact's metadata and its full version list

kapable artifact html	Fetch a published document's rendered body

kapable artifact skill	Install the artifact-publishing doctrine as a Claude Code skill, so an agent on a fresh machine publishes to taste without being told how

kapable artifact skill install	Write the skill into a Claude Code skills directory

kapable artifact skill show	Print the skill to stdout instead of writing it

kapable artifact skill status	Report the embedded version and what is installed, without writing

kapable artifact verdict	Read a decided ballot's verdict.

      kapable agent Agent: LLM-powered agentic TUI over the platform (bare `agent` or `agent -p "…"` headless); `run`/`swap`/`status` remain the local worker supervisor · 3 commands

kapable agent run

kapable agent swap

kapable agent status

      kapable auth Auth: login, orgs, API keys, apps · 21 commands

kapable auth login	Login: with --email (password prompted, or read from stdin when piped), with --email/--password for classic command-line credentials, or with neither to sign in via the browser (device login) and persist the session for future commands.

kapable auth set-key	Persist a durable org API key (`sk_org_…`) as the stored credential

kapable auth clear-key	Remove the stored org API key (leaves any stored login session intact).

kapable auth logout	Remove the stored login session (leaves any stored org key intact)

kapable auth me	Show current authenticated user info

kapable auth orgs	Manage organisations

kapable auth orgs get	Get an organisation by ID

kapable auth orgs members	List members of an organisation

kapable auth keys	Manage API keys

kapable auth keys list	List API keys for the current org

kapable auth keys create	Create a new API key

kapable auth keys rotate	Rotate an API key: mint a fresh secret onto the same key row.

kapable auth keys revoke	Revoke an API key

kapable auth service-tokens	Manage service tokens (`sig_st_*` and legacy `st_*`) — automation credentials

kapable auth service-tokens list	List service tokens for the current org

kapable auth service-tokens create	Create a new Signet service token (`sig_st_*`).

kapable auth service-tokens rotate	Rotate a service token; Signet keeps its id and reveals a new value once

kapable auth service-tokens revoke	Revoke a service token (idempotent)

kapable auth apps	List apps in an organisation

kapable auth apps list	List apps in an organisation

kapable auth apps get	Get app detail (with deployments)

      kapable board Board: stories, sprints, plans, products, comments · 30 commands

kapable board stories	Manage stories

kapable board stories list	List stories with optional filters

kapable board stories get	Get a story by UUID or code

kapable board stories create	Create a new story

kapable board stories update	Update an existing story

kapable board stories delete	Delete a story

kapable board stories transition	Transition a story to a new status

kapable board sprints	Manage sprints

kapable board sprints list	List sprints with optional filters

kapable board sprints get	Get a sprint by UUID or code (includes attached stories)

kapable board sprints create	Create a new sprint

kapable board sprints start	Start a planned sprint

kapable board sprints complete	Complete an active sprint

kapable board sprints attach	Attach a story to a sprint

kapable board sprints detach	Detach a story from a sprint

kapable board plans	Manage plans

kapable board plans list	List plans with optional filters

kapable board plans get	Get a plan by UUID or code

kapable board plans create	Create a new plan

kapable board plans update	Update an existing plan

kapable board plans revisions	List revisions for a plan

kapable board products	Manage products

kapable board products list	List all products

kapable board products get	Get a product by slug or UUID

kapable board products create	Create a new product

kapable board products update	Update an existing product

kapable board comments	Manage comments

kapable board comments list	List comments for a target

kapable board comments create	Create a comment

kapable board comments delete	Delete a comment

      kapable builder Designer: live previews for the design.kapable.ai workspace · 2 commands

kapable builder preview	Manage live preview sources for designer sessions

kapable builder preview register	Register a preview tunnel URL so the workspace iframe can load it

      kapable comms Comms: agents, rooms, messages, email · 13 commands

kapable comms agents	Manage agents

kapable comms agents list	List all agents in the org

kapable comms agents create	Create (or upsert) an agent

kapable comms agents get	Get agent detail by ID

kapable comms agents delete	Delete an agent

kapable comms rooms	Manage rooms

kapable comms rooms list	List rooms

kapable comms rooms create	Create a new room

kapable comms rooms get	Get room details (with participants)

kapable comms rooms messages	List messages in a room

kapable comms rooms post	Post a message to a room

kapable comms email	Send email via a mailbox

kapable comms email send	Send an email via a mailbox

      kapable conductor Conductor: run the agent daemon on this Mac — install, setup, status, uninstall · 4 commands

kapable conductor install	Download the daemon and (unless --no-setup) run the full setup

kapable conductor setup	Platform-side setup only — re-runnable for repair

kapable conductor status	Report what is installed, running, and registered.

kapable conductor uninstall	Stop and remove the launchd job.

      kapable data Data: tables, rows, search · 10 commands

kapable data tables	Manage tables

kapable data tables list	List all tables

kapable data tables create	Create a new table (columns as JSON array)

kapable data tables drop	Drop a table

kapable data rows	Manage rows

kapable data rows list	List rows in a table

kapable data rows get	Get a single row by UUID

kapable data rows create	Create one or more rows (JSON object or array)

kapable data rows delete	Delete a row

kapable data search	Full-text search within a table

      kapable dev Dev: spawn the local dev server + open a preview tunnel

Takes no subcommand. Run kapable dev --help for its flags.

      kapable feedback Feedback: file a bug report or propose an idea (IMP-2190) · 2 commands

kapable feedback bug	Report a bug (files a `ticket_type: "bug"` ticket)

kapable feedback idea	Propose an idea (files a `ticket_type: "feature"` ticket)

      kapable knowledge Knowledge: sources, claims, predicates, tensions · 13 commands

kapable knowledge sources	Manage knowledge sources

kapable knowledge sources list	List knowledge sources

kapable knowledge sources create	Create a new knowledge source

kapable knowledge sources delete	Delete a knowledge source

kapable knowledge claims	Manage knowledge claims

kapable knowledge claims list	List claims with optional filters

kapable knowledge claims get	Get a single claim by UUID

kapable knowledge claims create	Create a new claim

kapable knowledge claims search	Search claims (lexical, vector, or hybrid)

kapable knowledge predicates	List predicates in the ontology

kapable knowledge predicates list	List all predicates

kapable knowledge predicates ontology	Show ontology info for a predicate

kapable knowledge tensions	Detect tensions (contradictions) in the knowledge graph

      kapable inbox Inbox: notification feed, unread count, read receipts, and previews · 5 commands

kapable inbox list	List unread notifications (or history with --include-read)

kapable inbox count	Return the unread badge count without fetching feed rows

kapable inbox read	Mark explicit notification ids read, or mark everything through an instant

kapable inbox replay	Replay an existing stored audio render on an org sink

kapable inbox preview	Preview how many stored notifications a subscription pattern matches

      kapable kap Kaps: create, list, versions, triggers, runs, tokens, secrets, db · 33 commands

kapable kap list	List your org's kaps

kapable kap get	Show one kap with its files, version and triggers

kapable kap create	Create a kap from local files; prints the address and the bypass token once

kapable kap save	Save a whole new file snapshot to a kap

kapable kap versions	List a kap's versions, newest first

kapable kap diff	Show what changed between two versions

kapable kap restore	Restore an old version as a new version

kapable kap delete	Delete a kap (recoverable for a while afterwards)

kapable kap recover	Recover a deleted kap

kapable kap recovery	List deleted kaps that can still be recovered

kapable kap token	Bypass tokens: skip the audience check for one kap

kapable kap token list	List a kap's bypass tokens

kapable kap token create	Mint a bypass token; the token is printed once

kapable kap token revoke	Revoke a bypass token

kapable kap secret	Per-kap secrets: values come from stdin or a file, never the command line

kapable kap secret list	List a kap's secret names (values never come back)

kapable kap secret set	Set a secret's value; read from stdin, or --value-file

kapable kap secret delete	Delete a secret

kapable kap trigger	Triggers: request, schedule and inbox

kapable kap trigger list	List a kap's triggers

kapable kap trigger add-schedule	Attach a schedule trigger that runs a file on a cadence

kapable kap trigger add-inbox	Attach an inbox trigger that runs a file when mail arrives

kapable kap trigger pause	Pause a trigger

kapable kap trigger resume	Resume a paused trigger

kapable kap trigger delete	Delete a trigger

kapable kap trigger run-now	Run a schedule trigger now, even while paused

kapable kap runs	List a kap's runs, newest first

kapable kap disable	Switch a kap off; it refuses calls until enabled

kapable kap enable	Switch a kap back on

kapable kap usage	What your org consumed, per kap, per day, for the last 30 days

kapable kap db	The kap's own PostgreSQL database

kapable kap db query	Run one SQL statement against the kap's database

kapable kap db tables	List the kap's tables and columns

      kapable model Model catalogue: facts, freshness, and role-based model recommendations · 5 commands

kapable model list	List catalogue models with bounded filtering, sorting, and pagination

kapable model show	Show the full facts for one canonical model id or exact alias

kapable model status	Show catalogue freshness, source health, and latest published diff

kapable model roles	List the work roles in an org's public model roster

kapable model recommend	Return the org-approved ranked model fallback for a work role.

      kapable notify Notify: send a one-liner update to the operator (the D8 agent surface)

Takes no subcommand. Run kapable notify --help for its flags.

      kapable self-update Self-update: replace this binary with the channel's latest published build

Takes no subcommand. Run kapable self-update --help for its flags.

      kapable drop Drops: one-time secret handoff — mint a link, claim it, check its state · 3 commands

kapable drop claim	Claim a drop and put the secret somewhere that is not your screen

kapable drop mint	Mint a drop and print the one link that can claim it

kapable drop status	What is the state of a drop I minted? Never reveals the secret

      kapable store Store: buckets, objects · 9 commands

kapable store buckets	Manage buckets

kapable store buckets list	List all buckets

kapable store buckets create	Create a new bucket

kapable store objects	Manage objects

kapable store objects list	List objects in a bucket

kapable store objects upload	Upload a file to a bucket

kapable store objects download	Download an object from a bucket

kapable store objects delete	Delete an object from a bucket

kapable store objects head	Check if an object exists

      kapable todo Todos: the obligation primitive — list, add, claim, complete, dependencies (IMP-2715) · 15 commands

kapable todo list	List todos.

kapable todo summary	The launchpad-badge summary counts (open/blocked/overdue/… + by-kind)

kapable todo add	File (add) a new todo

kapable todo show	Show a todo's detail, including its dependency edges

kapable todo wait	Wait until a todo is completed, dropped, or deleted.

kapable todo update	Update an existing todo.

kapable todo delete	Soft-delete a todo

kapable todo done	Mark a todo done.

kapable todo drop	Drop (abandon) a todo.

kapable todo reopen	Reopen a closed (done/dropped) todo

kapable todo claim	Claim shared (unassigned, or workspace-assigned) work.

kapable todo release	Release a held claim.

kapable todo dep	Manage prerequisite (dependency) edges

kapable todo dep add	Add prerequisites: `id` waits on every id in --depends-on (max 50 per call, D20)

kapable todo dep remove	Remove a prerequisite edge

      kapable vault Vault: secrets, forwarded to the operator CLI (`kapable-ops vault …`)

Takes no subcommand. Run kapable vault --help for its flags.

      kapable voice Voice: talk to the platform agent — local web console, spoken results

Takes no subcommand. Run kapable voice --help for its flags.

      kapable workspace Workspaces: collaboration containers, membership, roles, and audit · 19 commands

kapable workspace list	List workspaces visible to the current principal

kapable workspace show	Show a workspace, its member role assignments, and bound resources

kapable workspace create	Create a workspace

kapable workspace update	Rename or re-describe a workspace

kapable workspace delete	Delete a workspace (workspace-owner only)

kapable workspace member	Manage workspace members

kapable workspace member add	Add an existing org user by user id

kapable workspace member set-role	Change an existing member's role

kapable workspace member remove	Remove a member from the workspace

kapable workspace invite	Manage workspace invitations

kapable workspace invite create	Create an invitation.

kapable workspace invite list	List invitations with email addresses masked

kapable workspace invite revoke	Revoke an unused invitation

kapable workspace role	Manage fixed and custom workspace roles

kapable workspace role list	List built-in and custom roles

kapable workspace role create	Create a custom role

kapable workspace role update	Replace a custom role's capability set

kapable workspace role delete	Delete a custom role

kapable workspace audit	Read the org audit trail, optionally narrowed to one workspace

        Every subcommand supports --help. Output defaults to JSON
        (scriptable); this mirrors the SDK's ListResponse<T>
        shape for list endpoints (data + total).

Publishing artifacts — kapable artifact

        The document is read from a file, never from an argument. That is the
        point of the command: prose passed through a shell string can break an interpolation on
        an apostrophe or a $, leaving the previous content in the payload — and
        the publish still returns 200. Use - to read stdin.

kapable artifact publish --slug q3-report --title "Q3 Delivery" \
  --kind report --markdown report.md \
  --summary "…" --favicon "🧾" --grounding repo:platform/kapable-artifacts

# a ballot — see the Artifacts guide for the grammar and its bounds
kapable artifact publish --slug the-call --title "The call" \
  --kind decision --html body.html --decision ballot.json
kapable artifact publish --slug the-call --title "…" --kind decision \
  --html body.html --decision carry        # forward the existing ballot unchanged

kapable artifact list --kind decision -t
kapable artifact get   <slug>
kapable artifact html  <slug> --version 2 -o old.html
kapable artifact verdict <slug>           # 'still open' until a member rules

        --dry-run validates locally and stops. Every mechanically checkable publish
        rule runs before the network call — the 2 MiB cap, external resource loads,
        forbidden <iframe>/<object>/<embed>,
        meta refresh, and a full-page wrapper where a fragment belongs — and
        each error names the fix. Publish warnings go to stderr, so piping the
        JSON cannot hide an unstyled-document.

--markdown and --html are not interchangeable

          --markdown is server-rendered in the platform’s house reading
          register — the right default, and impossible to publish slop through, since you
          never author CSS. But the register has its own palette, so a markdown artifact
          cannot carry your org’s brand accent. Only --html
          can, and only if it inherits the platform theme tokens rather than restating colours.
          Deciding is always a member action in the browser; agent keys get a 403.

Example session

curl -fsSL https://cli.kapable.ai/install.sh | sh
kapable auth login --email you@example.com   # prompts for your password
kapable auth me
kapable board stories list --status active
kapable data tables list

Two binaries: kapable vs. kapable-ops

          kapable is the customer/developer surface documented here.
          kapable-ops is a separate, privileged operator binary
          (deploy, vault, caddy, migrate) — it is not published on this
          registry and is not what cli.kapable.ai/install.sh
          installs.

Next Steps

Getting Started

SDK quick start, if you're building against the API instead.

Authentication

API keys, JWT tokens, and org context.

Board API

Stories, sprints, plans, and products.

Next

Getting Started · Authentication

---

# Operator SDK

Source: https://docs.kapable.ai/ops-sdk
Section: Start here

Operator SDK

        @kapable/ops-sdk (TypeScript) and kapable-ops-sdk (Rust)
        wrap the operator/platform tier: the deploy, CI, hosting, and
        admin surfaces that the customer SDK deliberately excludes. It mirrors the
        kapable (customer) vs kapable-ops (operator) CLI trust split.

You need

The operator CLI, the access named in this guide, and the role needed for the action.

First call

kapable-ops --help

You should see the operator command list.

Trust perimeter is enforced at construction

          The operator client is constructed only with a service token
          (st_*), a shared infra token, or an sk_admin_
          platform key. It rejects customer keys
          (sk_live_/sk_test_) at construction time —
          fail-fast, so an operator credential can never be swapped for a customer
          one by accident. The reverse is also true: operator endpoints are never
          reachable from @kapable/sdk.

Installation

        TypeScript
        Rust

# One-time: point the @kapable scope at the Kapable registry
echo '@kapable:registry=https://git.kapable.dev/api/packages/kapable/npm/' >> .npmrc

bun add @kapable/ops-sdk

# One-time: .cargo/config.toml
[registries.kapable]
index = "sparse+https://git.kapable.dev/api/packages/kapable/cargo/"

# Cargo.toml
[dependencies]
kapable-ops-sdk = { registry = "kapable", version = "0.1" }

What It Wraps

Module	Surface

berth	Process manager: binaries, deploys (Ed25519-signed, signing helper included), slots, canary/rollout, freeze, audit

foreman	CI: runners, recipes, recipe runs, tasks, metrics

host	Container/app hosting lifecycle

gateway	Route management (gateway_services)

harbor	Admin release/product/feature/tier mutations

data	The PlatformAdmin SQL query proxy

burrow	Reverse-tunnel registry

auth	launchpad/admin, metrics, beta, provisioning

        Full module/method listing ships in the package READMEs; the customer-facing
        endpoint reference at llms-full.txt
        deliberately excludes this tier.

Quick Start

        TypeScript
        Rust

import { OpsClient } from '@kapable/ops-sdk';

const ops = new OpsClient({
  baseUrl: 'http://localhost:3100',   // berth, on the platform host
  token: process.env.BERTH_API_TOKEN, // st_* / sk_admin_ / platform_staff kses_
});

const binaries = await ops.berth.listBinaries();
console.log(`${binaries.length} managed services`);

use kapable_ops_sdk::OpsClient;

// Fallible constructor — errors on sk_live_/sk_test_ credentials
let ops = OpsClient::new(
    "http://localhost:3100",
    &std::env::var("BERTH_API_TOKEN").unwrap(),
)?;

let binaries = ops.berth().list_binaries().await?;
println!("{} managed services", binaries.len());

Operator endpoints are not on api.kapable.ai

          The public gateway serves the customer tier only (operator paths return 404
          at the edge). Operator clients run on or tunnel to the platform host and
          target each control-plane service directly.

Next

Getting Started · Authentication

---

# Apps & Deployment

Source: https://docs.kapable.ai/apps
Section: Build

Apps & Deployment

        The platform's core story: create an app from a template, push code to the
        built-in Git remote, request a deploy, and it's live at
        {app}.{org}.kapable.run. The full lifecycle — environments,
        env vars, deployment lanes, logs, pause/resume — is part of the
        auth SDK module today (the methods live on client.auth).

Token tier: session required

          App lifecycle endpoints are permission-gated: authenticate with a
          kses_ session token (org role owner/member).
          A bare sk_live_ API key passes authentication but is rejected by the
          permission layer on app mutations.

The deploy flow

Create an app from a template with createAppChoice (use the elysia starter — see the template note below).

Authenticate & push your code to the app's Forgejo remote (see "Pushing your code" below).

Deploy with requestDeploy. The CI pipeline builds and starts the app.

Your app is live at https://{app}.{org}.kapable.run.

        Create, push, deploy, and serve an app

          Create
          Push
          Deploy
          Live

Fresh apps: use requestDeploy, not deployToLane

          deployToLane targets an existing lane and returns 404 on a freshly
          created app that has never deployed. The verified first-deploy path is
          requestDeploy; lanes come into play once the app exists in an environment.

Template note (2026-06-09)

          The elysia starter builds and deploys (~90s). The ts-hono
          template is listed in GET /v1/templates but its build image is currently
          missing (Image "kapable-tpl-ts-hono" not found, surfaces as a "checkout
          failed" deploy error) — use elysia until that's fixed.

Pushing your code

        The app's repo lives at git.kapable.dev. Mint a scoped bot token for it,
        then push over HTTPS with the bot username embedded in the URL:

# 1. Mint a per-app Forgejo PAT (token shown once)
curl -X POST -H "Authorization: Bearer kses_..." \
  https://api.kapable.ai/v1/apps/{app_id}/bot-pat
# → { "token": "...", "bot_username": "kbot-{app}" }   (bot_username is also on the app detail)

# 2. Push using bot_username:token@ (repo_url is returned when the app is created)
git remote add kapable https://kbot-myapp:PAT@git.kapable.dev/{org}/{repo}.git
git push kapable main

Watching a deploy

        requestDeploy returns 202 {"status":"requested"}. Poll
        GET /v1/apps/{app_id} (getAppDetail) to watch progress:

current_step / step_index / total_steps — live build progress.

deployment.status passes through requested → building → live_pending_tls. On failure, build_log_tail + failed_step tell you why.

Heads-up: the app's top-level status can stay created even while the deployment is serving. Confirm liveness by requesting the public_url directly (it returns 200 over TLS once live).

        In the console UI, the same states surface on the app card and detail page:
        Pending (repository provisioning) → Created
        (repo ready, awaiting first deploy) → Building →
        Live, with Failed (check the logs) and
        Paused (manually stopped) as the off-ramps. Prefer clicking?
        The browser walkthrough covers
        the create-and-deploy loop without touching the API.

Apps & templates

Method	Path	SDK (client.auth)

GET	/v1/templates	listTemplates

POST	/v1/app-choices	createAppChoice

GET	/v1/app-choices/{id}	getAppChoice

POST	/v1/app-choices/fork	forkAppChoice

POST	/v1/app-choices/{id}/publish-as-template	publishAppAsTemplate

GET	/v1/orgs/{org_id}/apps	listOrgApps

GET	/v1/apps/{app_id}	getAppDetail

PATCH	/v1/apps/{app_id}	renameApp

DELETE	/v1/apps/{app_id}	deleteApp

SDK Examples

        TypeScript
        Rust

// 1. Create an app from the elysia starter template
const choice = await client.auth.createAppChoice({
  user_id: me.user.id,
  org_id: me.org.id,
  org_slug: 'acme',
  template_slug: 'elysia',
  app_name: 'my-api',
});

// 2. Push code to the app's Forgejo remote, then:

// 3. Request the first deploy
await client.auth.requestDeploy(choice.id);

// 4. Live at https://my-api.acme.kapable.run

// Same flow in Rust (methods on client.auth())
let choice = client.auth().create_app_choice(&CreateAppChoiceRequest {
    user_id: me.user.id,
    org_id: me.org.id,
    org_slug: "acme".into(),
    template_slug: "elysia".into(),
    app_name: "my-api".into(),
}).await?;

client.auth().request_deploy(choice.id).await?;

Deployments & runtime control

Method	Path	SDK (client.auth)

POST	/v1/apps/{app_id}/deploy	requestDeploy

POST	/v1/apps/{app_id}/rebuild	rebuildApp

POST	/v1/apps/{app_id}/deployments/{deployment_id}/retry	retryDeployment

POST	/v1/apps/{app_id}/pause	pauseApp

POST	/v1/apps/{app_id}/resume	resumeApp

POST	/v1/apps/{app_id}/abort	abortPendingApp

GET	/v1/apps/{app_id}/logs	appLogs

Environments & env vars

        Apps have named environments (e.g. production), each with its own
        env-var set and deployment lanes. A simpler app-level env API
        (listAppEnv / upsertAppEnv / deleteAppEnv)
        also exists at /v1/apps/{app_id}/env. Values are encrypted at
        rest, and changes take effect on the next deployment — see
        Environment Variables for
        built-ins and best practices.

Method	Path	SDK (client.auth)

GET	/v1/apps/{app_id}/environments	listAppEnvironments

POST	/v1/apps/{app_id}/environments	createAppEnvironment

GET	/v1/apps/{app_id}/environments/{env}	getAppEnvironment

DELETE	/v1/apps/{app_id}/environments/{env}	deleteAppEnvironment

GET	/v1/apps/{app_id}/environments/{env}/env_vars	listAppEnvVars

POST	/v1/apps/{app_id}/environments/{env}/env_vars	createAppEnvVar

PUT	/v1/apps/{app_id}/environments/{env}/env_vars/{name}	updateAppEnvVar

DELETE	/v1/apps/{app_id}/environments/{env}/env_vars/{name}	deleteAppEnvVar

Deployment lanes

        Lanes are parallel deployment tracks within an environment (blue/green,
        canary). Promote a lane to make it the live one; drain it to stop routing traffic.

Method	Path	SDK (client.auth)

GET	/v1/apps/{app_id}/environments/{env}/lanes	listLanes

POST	/v1/apps/{app_id}/environments/{env}/lanes	createLane

GET	/v1/apps/{app_id}/environments/{env}/lanes/{lane}	getLane

PATCH	/v1/apps/{app_id}/environments/{env}/lanes/{lane}	updateLane

DELETE	/v1/apps/{app_id}/environments/{env}/lanes/{lane}	deleteLane

POST	/v1/apps/{app_id}/environments/{env}/lanes/{lane}/deploy	deployToLane

POST	/v1/apps/{app_id}/environments/{env}/lanes/{lane}/promote	promoteLane

POST	/v1/apps/{app_id}/environments/{env}/lanes/{lane}/drain	drainLane

SDK Examples

        TypeScript
        Rust

// Set an env var on production, then deploy to a canary lane
await client.auth.createAppEnvVar(appId, 'production', {
  name: 'FEATURE_FLAG_X',
  value: 'on',
});

await client.auth.deployToLane(appId, 'production', 'canary');

// Happy with the canary? Promote it.
await client.auth.promoteLane(appId, 'production', 'canary');

// Tail recent logs
const logs = await client.auth.appLogs(appId, { lines: 200 });

client.auth().upsert_app_env(app_id, "FEATURE_FLAG_X",
    &EnvVarUpsertRequest { value: "on".into() }).await?;
client.auth().promote_lane(app_id, "production", "canary").await?;
let logs = client.auth().app_logs(app_id, Some(200)).await?;

Heads-up: these methods live under client.auth

          The app surface is part of the auth module today because apps are
          org-owned resources managed by kapable-auth. A first-class
          client.apps namespace (same methods, better discoverability)
          is on the SDK roadmap.

Custom domains

        Any live app can serve on your own domain: add the domain in the app's
        settings, point a CNAME at the app's .kapable.run address, and
        the TLS certificate is provisioned automatically. Full flow, DNS details,
        and troubleshooting: Custom Domains.

Health checks

        Every app should serve GET /health returning any
        2xx — fast and dependency-free (no DB calls). The platform's
        lane prober uses it for granular health detection, and the deploy pipeline
        health-gates new containers on it.

2xx — healthy; the lane routes traffic.

404 — treated as alive but unmonitored: your app keeps serving, it just loses granular health detection. You will never be taken down for lacking the route.

Other non-2xx — the app is considered alive but unhealthy; the router routes away from the lane until it recovers.

        Public /health on {app}.{org}.kapable.run proxies straight
        through to your app like any other path. New scaffolds and the seed templates
        ship the route by default. For React Router, it's a resource route:

// app/routes/health.ts
export function loader() {
  return new Response(JSON.stringify({ status: "ok" }), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
}

// app/routes.ts
import { type RouteConfig, index, route } from "@react-router/dev/routes";
export default [
  route("health", "routes/health.ts"),
  index("routes/home.tsx"),
] satisfies RouteConfig;

        Static sites (the blank stack) can commit a plain file named
        health at the repo root — it's served at /health with a
        200. Other stacks: any one-line GET /health handler works.

WebSockets

        Your app can accept WebSocket connections at its normal address:
        wss://{app}.{org}.kapable.run/your-path. Nothing needs turning on.
        The platform passes the connection straight through to your app, so your
        framework's own WebSocket support (Bun, ws, Socket.IO, and others)
        works as it does locally. Subprotocols and compression are agreed between the
        browser and your app.

Idle limit: a connection with no traffic either way for 5 minutes is closed. Send a ping every 30 seconds or so to keep a quiet connection open. Most client libraries do this already.

Maximum length: any connection is closed after 4 hours.

Deploys: a new deploy replaces your app's container, so open connections close. Clients must reconnect, ideally with a short random delay.

Limits: up to 256 open connections per app and 1,024 per organisation. Past that, a new connection is refused with 429 and a message naming the limit.

Sleeping apps: an open connection counts as activity, so an app is not put to sleep under it. A connection to a sleeping app wakes it first.

        Which pages may connect. Only pages on your app's own addresses: its
        kapable.run address and its custom domains. A page anywhere else,
        including another app on kapable.run or your app's staging
        environment, is refused with 403. Browsers treat all of
        kapable.run as one site, so without this rule another page could open
        a connection that carries your visitors' cookies. Clients that send no
        Origin header, such as servers and command-line tools, are allowed.
        A website elsewhere cannot connect to your app's WebSocket from the browser yet.

        If the app uses Kapable sign-in, a connection is only
        accepted when the visitor is signed in. A signed-out connection gets 401, not a
        redirect, because a WebSocket client cannot follow one: sign in with a normal page
        load first.

Next

Getting Started · Authentication

---

# Sign users in to your app

Source: https://docs.kapable.ai/app-sign-in
Section: Build

Sign users in to your app

        Members of your organisation sign in to your app with their Kapable
        account. You write no callback and store no secret. Turn sign-in on,
        then one call reads the user and one call checks a permission.

You need

          An app on Kapable, served at {app}.{org}.kapable.run
          or your own domain. It must be a Bun or Node app, and use
          @kapable/sdk 0.23.0 or later.

First call

import { currentUser } from "@kapable/sdk/app-auth";

const user = currentUser(request); // { memberId, orgId, email, role }

With sign-in on, you should see the member's id, org id, email and role.

What you get

Anyone in your organisation can sign in with the Kapable account they already have.

The Kapable router runs the sign-in. Your app gets no callback route and holds no secret.

Your code reads who is signed in from the request. The SDK makes no network calls.

You decide what each role may do in your app, in one small map.

Turn on Kapable sign-in

        Do this once per app, in the console. Any member of your organisation
        can. Your code does not change.

Open the app, then Settings, then the Authentication section.

Tick Require Kapable sign-in at the edge.

Press Save authentication.

        On a new app, Sign in with Kapable is already ticked
        and Kapable audience is already
        Org members only. On an older app, check both before
        you save.

        From then on, every visitor signs in before a request reaches your app.
        Someone outside your organisation cannot open it. After sign-in, the
        visitor lands on the page they asked for.

        The same settings are at GET and PUT
        /v1/apps/{app_id}/auth-config, for a member session of the
        app's organisation (see Authentication).
        Each console control maps to one field:

Console control	API field and value

Require Kapable sign-in at the edge	"kapable_auto_adopt": true

Sign in with Kapable	"kapable" in "providers"

Kapable audience: Org members only	"kapable_audience": "org_members"

        The PUT replaces all the app's sign-in settings, and any
        field you leave out goes back to its default. Read the settings with
        GET first and send them all back with your change.

Set up your app

        The calls work in any Bun or Node app. The examples on this page use
        Hono. To start fresh, create an app from
        the Elysia (bun) template, then add Hono and the SDK:

bun add hono @kapable/sdk@^0.23.0

        Apps created by Kapable already carry an .npmrc that points
        the @kapable scope at the Kapable registry.

        Split the app into three files. Your routes go in
        src/app.ts, which exports app. Two small entry
        files serve it: one for production and one for your laptop.

src/app.ts: your routes

import { Hono } from "hono";
import { html } from "hono/html";
import {
  currentUser,
  requireUser,
  defineAccess,
  signOutUrl,
  KapableAuthRequired,
  KapableForbidden,
} from "@kapable/sdk/app-auth";

export const access = defineAccess({
  roles: {
    owner: ["*"],
    admin: ["notes.read", "notes.write"],
    member: ["notes.read"],
    "Key keeper": ["notes.read"],
  },
});

export const app = new Hono();

app.onError((err, c) => {
  if (err instanceof KapableAuthRequired || err instanceof KapableForbidden) {
    return err.response;
  }
  console.error(err);
  return c.json({ error: { code: "internal", message: "Something went wrong." } }, 500);
});

app.get("/health", (c) => c.json({ status: "ok" }));

app.get("/", (c) => {
  const user = currentUser(c.req.raw);
  if (user === null) return c.text("Hello. Sign-in is off for this app.");
  return c.html(html`<p>Hello, ${user.email}. <a href="${signOutUrl()}">Sign out</a></p>`);
});

app.get("/me", (c) => {
  const user = requireUser(c.req.raw);
  return c.json({ email: user.email, role: user.role });
});

app.post("/notes", async (c) => {
  const user = access.require(c.req.raw, "notes.write");
  // ... save the note for user.memberId
  return c.json({ saved: true, by: user.memberId }, 201);
});

src/index.ts: production

import { app } from "./app";

export default {
  port: Number(process.env.PORT ?? 3000),
  fetch: app.fetch,
};

src/dev.ts: your laptop only

        On your laptop there is no Kapable router, so nobody is signed in. The
        SDK never invents a user. This file sets the four headers the router
        would set. Production code never imports it.

import { app } from "./app";

const devUser: Record<string, string> = {
  "x-kapable-member-id": "dev-member",
  "x-kapable-org-id": "dev-org",
  "x-kapable-email": "dev@example.com",
  "x-kapable-role": process.env.DEV_ROLE ?? "owner",
};

export default {
  port: Number(process.env.PORT ?? 3000),
  fetch(request: Request) {
    const headers = new Headers(request.headers);
    for (const [name, value] of Object.entries(devUser)) headers.set(name, value);
    return app.fetch(new Request(request, { headers }));
  },
};

package.json scripts

Point start at the production file and dev at the laptop file:

{
  "scripts": {
    "start": "bun run src/index.ts",
    "dev": "bun --watch src/dev.ts"
  }
}

bun run dev                    # signed in as an owner
DEV_ROLE=member bun run dev    # signed in as a member
bun run start                  # nobody signed in

Read the user

        currentUser(request) tells you who is signed in. With
        sign-in on, every request carries a user. It returns null
        only when sign-in is off, or on your laptop without the dev headers.

The user has four fields:

Field	What it is

memberId	The member's id in your organisation. Use it as the user's key.

orgId	Your organisation's id.

email	The member's email, or null.

role	The member's role name, exactly as the console shows it, or null.

        currentUser accepts a Fetch Request, a Node
        IncomingMessage, or a Headers object.

Protect a route

        requireUser(request) returns the signed-in user, never
        null, so your code needs no null check. If there is no
        user, it throws KapableAuthRequired, a clear
        401.

        With sign-in on, this never throws: the router signs every visitor in
        first. So a 401 means sign-in is off for the app, or the
        request reached the app without passing the router. The error says so:

{
  "error": {
    "code": "sign_in_required",
    "message": "Sign-in isn't switched on for this app. Any member of your organisation can turn it on in the app's Authentication settings.",
    "details": {
      "how_to_fix": "Open {org}.kapable.ai/apps/{app_id}/settings → Authentication, tick \"Require Kapable sign-in at the edge\", then Save authentication. Or PUT /v1/apps/{app_id}/auth-config with {\"providers\":[\"kapable\"],\"kapable_audience\":\"org_members\",\"kapable_auto_adopt\":true}."
    }
  }
}

        {org} and {app_id} are placeholders. The SDK
        cannot know them. Put in your organisation's slug and your app's id.
        The app's settings address shows both.

Permissions

        Your app decides what each role may do. Write the map once with
        defineAccess, as in src/app.ts above. Check it
        with access.require(request, "notes.write").

No user: the same 401 as requireUser.

The role grants the permission: returns the user.

The role does not: throws KapableForbidden, a 403.

        Use access.can(user, "notes.write") when you need a yes or
        no, for example to hide a button. A null user gets
        false.

Console roles grant nothing until you list them

          A role you create in the console grants nothing in your app until you
          list it in defineAccess. Names match exactly, including
          capitals and spaces. A role the map does not list gets no permissions.

          "*" grants every permission, and only to the roles that
          list it. Built-in roles arrive as owner,
          admin, member and viewer.

          Changing a role's platform permissions in the console does not change
          your app's map. Moving a member to another role does.

        The 403 body names the permission and the member's role in
        details. So when a custom role is missing from your map,
        the response tells you which role to add.

{
  "error": {
    "code": "permission_denied",
    "message": "You don't have permission to notes.write. Ask an owner of your organisation.",
    "details": { "permission": "notes.write", "role": "Key keeper" }
  }
}

Sign out

        signOutUrl() returns /__kapable/auth/logout.
        Link to it, as the home page in src/app.ts does. Opening it
        ends the visitor's session in your app and sends them to /.

        It does not sign them out of Kapable. If they are still signed in
        there, opening your app again signs them straight back in.

Send the error response

        KapableAuthRequired and KapableForbidden each
        carry .response, a ready Fetch Response, plus
        .status and .message. Sending it is one line,
        as in the onError in src/app.ts.

Show a friendly page in the browser

        .response is JSON, which is right for API calls. A person
        in a browser sees raw JSON. To show them a page instead, answer
        browsers with HTML:

app.onError((err, c) => {
  if (err instanceof KapableAuthRequired || err instanceof KapableForbidden) {
    const wantsHtml = (c.req.header("accept") ?? "").includes("text/html");
    if (!wantsHtml) return err.response;
    const title = err instanceof KapableForbidden ? "You can't do that here" : "Sign-in needed";
    return c.html(
      html`<h1>${title}</h1><p>${err.message}</p><p><a href="/">Back to the start</a></p>`,
      err.status as 401 | 403,
    );
  }
  console.error(err);
  return c.json({ error: { code: "internal", message: "Something went wrong." } }, 500);
});

        API calls still get the JSON body with its code and
        details.

Elysia

Pass request from the handler context:

import { Elysia } from "elysia";
import { requireUser, KapableAuthRequired, KapableForbidden } from "@kapable/sdk/app-auth";

const app = new Elysia()
  .onError(({ error }) => {
    if (error instanceof KapableAuthRequired || error instanceof KapableForbidden) return error.response;
  })
  .get("/me", ({ request }) => requireUser(request));

React Router loaders and actions

import { requireUser, KapableAuthRequired, KapableForbidden } from "@kapable/sdk/app-auth";

export async function loader({ request }: Route.LoaderArgs) {
  try {
    const user = requireUser(request);
    return { email: user.email };
  } catch (err) {
    if (err instanceof KapableAuthRequired || err instanceof KapableForbidden) {
      throw err.response;
    }
    throw err;
  }
}

A thrown 401 or 403 reaches your error boundary.

How it works

A visitor opens your app. The Kapable router sends them to your organisation's sign-in page.

After sign-in, the router keeps the session in its own cookie on your app's host and sends the visitor back.

On every request, the router checks that session. If it is valid, the router adds four headers: x-kapable-member-id, x-kapable-org-id, x-kapable-email and x-kapable-role.

The SDK reads those headers. That is all it does.

        The router removes any x-kapable-* headers a visitor sends
        before it adds its own. A visitor cannot pretend to be someone else.

Trust model

          These headers only mean something behind the Kapable router. Never
          expose your app's port directly. If a request can reach your app
          without passing the router, anyone can set these headers.

Limits

This version signs in members of your organisation only.

This version protects the whole app. Every page needs sign-in. Public pages mixed with protected ones are coming.

App-only accounts, for customers outside your organisation, are coming. They will use the same calls.

Sign-out ends the session in your app only, not in Kapable.

Permissions live in your code. Changing the map means a new deploy.

Next

Apps & Deployment · Roles & Permissions · Authentication

---

# Kaps

Source: https://docs.kapable.ai/kaps
Section: Build

Kaps

        A kap is one folder of files that runs at its own address the moment you
        save it. It belongs to your organisation and is private to your
        organisation's signed-in members by default. No build step, no deploy
        pipeline, no containers to manage.

From code, not just the browser. Both SDKs and the CLI can do everything this page describes.
        Kaps lives on your org host, so build the client against it with a member session token:

import { KapableClient } from '@kapable/sdk';   // 0.22.0 or later
const client = new KapableClient({
  baseUrl: 'https://api.kapable.ai',
  orgBaseUrl: 'https://acme.kapable.ai',   // your org host
  token: 'kses_...',                        // a member session; an sk_org_ key is refused
});
const { kaps } = await client.kaps.listKaps(orgId);

Rust: client.kaps() on kapable-sdk 0.19.0 with .org_base_url(...).
        Terminal: kapable kap list after kapable login (CLI 0.21.3). The full route table is on
        Kaps API.

Your first kap

        Sign in at https://{org}.kapable.ai and open
        https://{org}.kapable.ai/ui/kaps. You see your organisation's
        kap list and a New kap button. Name it: it is born with a
        main.ts hello handler, a request trigger, and one machine
        token (shown once). Saving opens a single screen with the files, the
        rendered app, versions, log, triggers and audience side by side.

        Edit main.ts and press Save (or ⌘S). The app pane reloads and
        a new version appears. The kap's address is:

https://{kap}.{org}.kapable.run

        Prefer the API? The same thing as a script, with a member session:

curl -X POST https://acme.kapable.ai/v1/orgs/$ORG_ID/kaps \
  -H "X-Session-Token: kses_..." \
  -H "X-Kapable-Client: my-script" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello",
    "main_file": "main.ts",
    "files": [{"path": "main.ts", "content": "export default (request: Request): Response => new Response(\"Hello\")"}]
  }'
# → 201 with the kap, its first version, its address, and a once-only bypass_token

The handler contract

        The request trigger runs your main file for every request the kap
        receives. The contract is one default export that takes a web
        Request and returns a Response:

// main.ts
export default async (request: Request): Promise<Response> => {
  return new Response("Hello");
};

        Other trigger kinds hand your handler a different argument: a schedule
        gets { lastRunAt }, an inbox trigger gets the parsed email
        message. See Triggers below.

The std module

        Import the platform module for zero-config access to your kap's own
        database, file store, environment and caller identity. Deno resolves the
        import and the TypeScript directly; there is nothing to install:

import { db, files, env } from "https://kaps.kapable.ai/std/v1/mod.ts";

export default async (_request: Request): Promise<Response> => {
  await db.query("CREATE TABLE IF NOT EXISTS notes (id integer PRIMARY KEY, body text)");
  await db.query("INSERT INTO notes VALUES ($1,$2) ON CONFLICT(id) DO UPDATE SET body=EXCLUDED.body", [1, "hello"]);
  await files.put("note.txt", "hello", "text/plain");
  const row = await db.query("SELECT body FROM notes WHERE id=$1", [1]);
  const text = await (await files.get("note.txt")).text();
  return Response.json({ row: row.rows[0], text, configured: !!env.get("API_KEY") });
};

db.query(sql, params?) — one PostgreSQL statement; parameters support null, bool, numbers, text, UUID and JSON/JSONB.

files.get(key) returns a web Response; files.put, files.list and files.delete(key) cover the rest.

env.get(name) reads this kap's supplied environment (its secrets); a missing name is undefined. There is no write method.

identity.verify(request) tells your handler who the caller is — member, machine, colleague or anonymous.

        Keep store calls inside the handler: the first evaluation of your module
        runs before the kap's database exists, so a store call at the top of the
        file fails. Inside the handler it always works.

Versions, diff and restore

        Every save replaces the whole file set and creates an immutable version.
        Restoring never deletes anything: a restore creates another version. You
        can list versions, diff any two, and restore from the editor's Versions
        pane or the API:

GET /kaps/{id}/versions — complete snapshots, newest first.

GET /kaps/{id}/diff?from=&to= — exact before/after text per file.

POST /kaps/{id}/versions/{v}/restore — a new version with the old content.

        A save against a stale base is refused with 409 VERSION_CONFLICT and the
        current version id, so two people (or two scripts) editing at once never
        silently overwrite each other.

Triggers

        A file in your kap can run on its own, not only when a request arrives.
        Attach triggers from the Triggers pane or the API. A file supports one
        trigger of each kind.

Request — every request to the kap's address runs the main file.

Schedule — an interval (default minimum 15 minutes) or a five-field UTC cron.

Inbox — email sent to {kap}@{org}.kapable.email is parsed and handed to the file.

// schedule.ts
export default async (ctx: { lastRunAt: Date | null }) => {
  // null on the first run; otherwise the previous run's start time.
  console.log(ctx.lastRunAt?.toISOString() ?? "first run");
};

// inbox.ts
import { files } from "https://kaps.kapable.ai/std/v1/mod.ts";
export default async (msg) => {
  for (const attachment of msg.attachments) {
    const response = await files.get(attachment.key);
    const bytes = await response.arrayBuffer();
    // Work with the decoded attachment bytes here.
  }
};

        Triggers can be paused, resumed, removed, and run by hand; every run —
        including failed ones and every visit to the kap's web address — appears
        in the Runs pane with a plain-words outcome and its log.

Who can reach a kap

        A kap starts as members: only signed-in members of your organisation get in.
        The Audience pane (and the API) offers three settings:

members — signed-in members of your organisation.

invited — members plus an invite list of email addresses and domains.

public — anyone on the internet, no sign-in.

In practice:

A member visiting the kap's address goes through one sign-in round trip and lands in the app.

A non-member is redirected to the organisation's sign-in page.

A machine calls it with the kap's token: Authorization: Bearer kbt_…. Tokens are shown once when minted; mint and revoke them from the kap screen or the API.

        For an outside sender that cannot hold a token — Stripe or GitHub
        delivering a webhook — mint an endpoint secret on the Triggers
        pane. The sender then either calls a secret address
        (https://{kap}.{org}.kapable.run/__kaps/e/{secret}) or signs the request
        with an HMAC-SHA256 header. An endpoint secret does not change the kap's
        audience: a members-only kap stays invisible to everyone else. Your
        handler can check who is calling with
        identity.verify(request):

import { identity } from "https://kaps.kapable.ai/std/v1/mod.ts";

export default async (request: Request): Promise<Response> => {
  const caller = await identity.verify(request);
  return Response.json({ kind: caller.caller_kind, subject: caller.sub });
};

Next

Full route reference: Kaps API.

---

# Deployments

Source: https://docs.kapable.ai/deployments
Section: Build

Deployments

        Kapable handles the full build-and-deploy pipeline for your apps. Push
        your code, and Kapable builds, packages, and deploys it to production
        automatically.

How Deployments Work

The deployment pipeline follows these stages:

Requested — A deploy is triggered (manually or via git push)

Building — Your app is compiled and packaged

Deploying — The built artifact is pushed to the runtime environment

Live — Your app is running and serving traffic

        If any stage fails, the deployment is marked as failed
        and the previous version continues running.

Triggering a Deploy

From the Console

Open your app in the console

Click the Deploy button

The deployment starts immediately

From Git

        Push to your app's connected repository. Kapable detects the push and
        triggers a build automatically.

From the API (headless agents)

        An sk_org_ org API key can trigger and observe deploys of an
        existing app — no browser session needed (added 2026-07-14, IMP-2131).

          POST /v1/apps/{app_id}/deploy requires the key to carry the
          dedicated deploy scope. An org admin mints one via
          console → org → API keys with scopes
          ["read","deploy"]. Default read/write
          keys deliberately cannot trigger deploys.

          GET /v1/apps/{app_id}/deployments and
          GET /v1/apps/{app_id}/deployments/{deployment_id} need only the
          read scope — any org key can poll deploy status, including
          the KAPABLE_ORG_KEY auto-injected into every deployed app's
          environment.

          Send the key as x-api-key: sk_org_... or
          Authorization: Bearer sk_org_.... The org is resolved from the
          key itself — do not send X-Org-Id.

          Poll deployments until status live (not
          succeeded). App creation still requires a session.

Retry a Failed Deploy

If a deployment fails:

Open the app detail page

Find the failed deployment in the history

Click Retry to re-run the deployment

        Retrying uses the same source code but runs a fresh build. This can fix
        transient issues like network timeouts during dependency installation.

Deployment Statuses

Status	Icon	Meaning

Requested	Grey	Deploy triggered, waiting to start

Building	Blue (pulsing)	App is being compiled and packaged

Deploying	Blue (pulsing)	Artifact is being pushed to production

Live	Green	App is running and healthy

Failed	Red	Something went wrong — check logs

Cancelled	Grey	Deploy was cancelled before completion

Viewing Deployment History

Per-App History

        Open any app and scroll to the Deployments section.
        You'll see a timeline of recent deployments with status, version,
        duration, and timestamp.

Cross-App History

        Navigate to Deployments in the console sidebar to see
        deployments across all your apps. Use the filters to narrow by app or
        status.

Environment Variables

        Environment variables let you configure your app without changing
        code. They're injected at build time and runtime.

Setting Variables

Open your app → Settings → Environment Variables

Add a key-value pair (e.g. DATABASE_URL = postgres://...)

Click Save

        Changing environment variables triggers a fresh deployment so the new
        values take effect. See the dedicated
        Environment Variables
        guide for built-in variables, limits, and best practices.

Best Practices

Never commit secrets to your repository — use environment variables instead

Use descriptive names: STRIPE_API_KEY not KEY1

Prefix app-specific variables: MYAPP_FEATURE_FLAG

Kapable automatically sets some variables (like PORT and NODE_ENV)

Build Configuration

        Kapable auto-detects your app type and runs the appropriate build
        steps:

App Type	Detection	Build Command

Node.js	package.json	npm install && npm run build

React	react-scripts in dependencies	npm install && npm run build

Static	index.html in root	No build step

Custom Build Commands

        Override the default build command in your app settings if your project
        uses a non-standard setup.

Zero-Downtime Deploys

Kapable performs rolling deployments to minimise downtime:

The new version is started alongside the old one

Health checks confirm the new version is ready

Traffic is switched to the new version

The old version is gracefully shut down

        If the new version fails health checks, the deploy is marked as failed
        and the old version continues serving traffic.

Logs

View build and runtime logs for any deployment:

Open the app detail page

Click on a specific deployment

Build logs show the compilation output

Runtime logs show application output after deploy

        Logs are available for both successful and failed deployments, helping
        you diagnose issues.

Next Steps

Environment Variables

Built-in variables, limits, and rotation patterns.

Custom Domains

Serve your app from your own domain.

Apps & Deployment API

Drive deploys programmatically via the API.

Next

Getting Started · Authentication

---

# Environment Variables

Source: https://docs.kapable.ai/environment-variables
Section: Build

Environment Variables

        Configure your apps with environment variables for secrets, feature
        flags, and runtime settings.

Overview

        Environment variables let you pass configuration to your app without
        hardcoding values in source code. They're the standard way to manage
        secrets (API keys, database URLs) and per-environment settings (debug
        mode, log level).

On Kapable, environment variables are:

Encrypted at rest and only decrypted when injected into your app's process

Scoped per app — each app has its own set of variables

Applied on deploy — changes take effect on the next deployment

Setting Variables via Console

Go to Apps > {your app} > Settings

Scroll to the Environment section

Enter a key and value, then click Add

Click Rebuild to apply changes

        Variables are key-value pairs. Keys must be uppercase letters, digits,
        and underscores (e.g. DATABASE_URL,
        STRIPE_SECRET_KEY).

Bulk Import

You can paste a .env file format in the bulk import section:

DATABASE_URL=postgres://user:pass@host:5432/db
REDIS_URL=redis://localhost:6379
SECRET_KEY=your-secret-here

        Each KEY=VALUE line will be parsed and added. Lines
        starting with # are ignored.

Setting Variables via API

# Set a single variable
curl -X POST https://api.kapable.ai/v1/apps/{app_id}/env \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "DATABASE_URL", "value": "postgres://..."}'

# List all variables (values are masked)
curl https://api.kapable.ai/v1/apps/{app_id}/env \
  -H "Authorization: Bearer YOUR_API_KEY"

# Delete a variable
curl -X DELETE https://api.kapable.ai/v1/apps/{app_id}/env/DATABASE_URL \
  -H "Authorization: Bearer YOUR_API_KEY"

Built-in Variables

Kapable automatically provides these variables to every app:

Variable	Description	Example

PORT	Port your app must listen on	3000

KAPABLE_APP_ID	Your app's unique UUID	a1b2c3d4-...

KAPABLE_APP_SLUG	Your app's URL slug	my-app

KAPABLE_ORG_ID	Your organisation's UUID	e5f6g7h8-...

KAPABLE_ORG_SLUG	Your organisation's slug	acme

NODE_ENV	Set to production for Node.js apps	production

RUST_LOG	Default log level for Rust apps	info

Always use PORT

          Always use PORT for your listening port. Do not hardcode
          a port number.

        Node.js
        Rust

const port = process.env.PORT || 3000;
app.listen(port);

let port = std::env::var("PORT").unwrap_or_else(|_| "3000".into());

Best Practices

Never Commit Secrets

        Add .env to your .gitignore. Use environment
        variables for all sensitive values:

Database connection strings

API keys and tokens

Encryption keys

OAuth client secrets

Use Descriptive Names

Prefix variables by purpose:

DB_HOST=...
DB_PORT=...
DB_NAME=...
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...
SMTP_HOST=...
SMTP_PORT=...

Separate Environments

        Don't reuse the same variables across dev, staging, and production.
        Each Kapable app has its own environment, so create separate apps for
        each stage:

my-app-dev — development config, debug logging

my-app-staging — staging database, test payment keys

my-app — production config, live keys

Secret Rotation

To rotate a secret:

Generate the new secret value

Update the environment variable in App Settings > Environment

Click Rebuild to redeploy with the new value

Revoke the old secret in the external service

Zero-downtime rotation

          Some apps support reading multiple keys simultaneously. Set both
          API_KEY and API_KEY_OLD, deploy, then
          remove the old one in a second deploy.

Variable Size Limits

Key length: 1–256 characters

Value length: up to 32 KB

Total variables per app: 100

Total env size per app: 1 MB

Troubleshooting

Variable not available at runtime — ensure you redeployed after adding it. Variables are injected at process start, not live.

Value appears empty — check for trailing whitespace or newlines in the value. Use the console UI to verify.

Build-time vs runtime — some frameworks need variables at build time (e.g. NEXT_PUBLIC_* in Next.js). These must be set before the build step runs.

Next Steps

Deployments

How env changes reach your running app.

Secrets API

Org-level secret storage via strongbox.

Troubleshooting

Common issues and how to resolve them.

Next

Getting Started · Authentication

---

# Custom Domains

Source: https://docs.kapable.ai/custom-domains
Section: Build

Custom Domains

        Connect your own domain to any Kapable app. Visitors see your brand;
        Kapable handles hosting, SSL, and routing behind the scenes.

How It Works

        Every Kapable app gets a default URL at
        app-slug.kapable.run. Custom domains let you serve that
        same app from your own domain (e.g. app.yourcompany.com).

The flow:

You add a custom domain in app settings

You create a DNS record pointing to Kapable

Kapable verifies the DNS record

An SSL certificate is automatically provisioned via Let's Encrypt

Traffic to your domain is routed to your app

Adding a Custom Domain

Open your app in the console and navigate to Settings

Scroll to the Custom Domains section

Enter your domain (e.g. app.yourcompany.com)

Click Claim domain

Kapable will show you the DNS records you need to create.

DNS Configuration

        Kapable asks for two records: one that proves you own the
        name, and one that routes it. Both are shown on the Domains panel with
        the exact values for your app.

Type	Name	Value	Purpose

TXT	_kapable-verify.app.yourcompany.com	the token shown on the panel	ownership

CNAME	app	your-app-slug.your-org.kapable.run	routing (subdomain)

A	@	the IP address shown on the panel	routing (apex domain)

        For apex domains (e.g. yourcompany.com without a
        subdomain) use the A record, since CNAME records are not allowed at the apex.
        Providers with CNAME flattening (Cloudflare, Route 53) may use a CNAME instead.
        If you use Cloudflare, keep the record set to “DNS only” (grey cloud)
        so Kapable can issue the certificate.

DNS Propagation

        DNS changes can take up to 48 hours to propagate worldwide, though most
        providers update within minutes. Kapable will keep checking until the
        record is verified.

SSL Certificates

        Once DNS is verified, Kapable automatically provisions an SSL
        certificate via Let's Encrypt. This typically completes within a few
        minutes.

Certificates are issued for your exact domain

Renewal is automatic (certificates renew before expiry)

Both HTTP and HTTPS are supported; HTTP redirects to HTTPS by default

No configuration needed on your part

Certificate Rate Limits

        Let's Encrypt enforces rate limits (50 certificates per registered
        domain per week). This is rarely an issue, but if you're adding many
        subdomains at once, certificates may queue.

Verification and Troubleshooting

After adding a domain, check its status in app settings:

Status	Meaning

Pending	Waiting for your TXT and routing records to be detected (re-checked every few minutes, or click check now)

Verifying	DNS detected, verifying ownership

Provisioning SSL	Issuing the SSL certificate

Active	Domain is live and serving traffic

Error	Something went wrong — check the error message

Common Issues

DNS not detected:

Verify both records (dig TXT _kapable-verify.app.yourcompany.com and dig CNAME app.yourcompany.com, or dig A yourcompany.com for an apex)

Check for conflicting A or AAAA records on the same subdomain

Wait for DNS propagation (up to 48 hours)

SSL certificate failed:

Ensure no firewall or CDN is blocking the ACME challenge

If using Cloudflare, set the DNS record to "DNS only" (grey cloud) during provisioning

Check that port 80 and 443 are not blocked

Mixed content warnings:

Ensure your app loads all resources over HTTPS

Update any hardcoded http:// URLs to https:// or use protocol-relative URLs

Multiple Domains

        You can add multiple custom domains to a single app. All domains serve
        the same app content. This is useful for:

Regional domains (app.company.co.uk, app.company.de)

Brand aliases

Migration from old domains (keep both active during transition)

Each domain gets its own SSL certificate and verification status.

Removing a Domain

To remove a custom domain:

Go to app Settings → Custom Domains

Click the delete button next to the domain

Confirm the removal

        After removal, the domain stops routing to your app immediately.
        Remember to clean up the DNS record at your provider.

Next Steps

Deployments

How your app gets built and shipped.

Troubleshooting

Common issues and how to resolve them.

Apps & Deployment API

The full apps API reference.

Next

Getting Started · Authentication

---

# Runners

Source: https://docs.kapable.ai/runners
Section: Build

Runners

        Runners are machines you own that build and run your
        pipelines: a Mac mini in the office, a build server in your rack, a
        spare laptop. Instead of waiting on shared platform capacity, your
        pushes build on your own hardware — and your git credentials are
        never copied to it.

        The Runners page in
        the console shows every machine
        connected to your org and lets you manage the codes that connect new
        ones.

Deploy modes

        Every app has a deploy_mode — platform,
        artifact, or self — that decides how
        much of its pipeline runs on your hardware. It's set per app, at
        creation or later through the app settings:

Mode	Who builds	Who hosts

platform (default)	Kapable	Kapable — your app is live at {app}.{org}.kapable.run.

artifact	Your runner	Kapable — the build artifact uploads over a single-use token and the platform deploys it.

self	Your runner	Your infrastructure — the runner builds, then launches the app in an Incus container on its own machine; Kapable does not host the running app.

        In self mode, secrets you file in
        Secrets under the
        app:NAME scope are merged into the app's environment when
        its build is assigned to the runner. Receipts list secret
        names only, not values; on a name collision, your value wins.
        Self-deploy requires the incus capability chip —
        see the runner card below; capability
        matching selects an eligible runner automatically.

Builds without credentials

        Org runners hold no git credentials. The platform
        fetches your source server-side and gives the runner a single-use
        download token bound to one (org, repository, commit). The token is
        the whole address — the request itself carries no org,
        repository, or commit — and it is revoked when the task ends;
        it cannot authorize any other. This works from anywhere: a runner in
        your office or your own cloud makes outbound HTTPS connections
        to runner.kapable.ai only — no inbound
        ports, no VPN, no platform-network access.

The runner card

Each connected machine appears as a card:

Signal	Meaning

online (green)	Heartbeating now. Ready to pick up work.

stale (amber)	No heartbeat for 90+ seconds. The machine may be asleep, offline, or the runner stopped.

offline (red)	Gone quiet for long enough that the platform stopped offering it work.

Shield chip (e.g. container)	The isolation tier: work runs inside a sandbox of that kind.

UNSANDBOXED (amber badge)	This runner executes work directly on the host with no sandbox. The badge is always visible by design — you should always know which machines run unprotected.

Capability chips	What the machine can build: rust, node, bun, os:macos, arch:arm64, and so on. Pipelines are matched to runners by these.

Version	The runner software version, when the runner advertises it.

Tasks	Active work / the runner's concurrency limit.

        Every org member can see the runners page; connecting and revoking
        machines is for org owners and admins.

Enrollment codes

        A machine joins your org by presenting an enrollment
        code — a single-use, short-lived credential you mint from
        the Runners page.

Single use. One code connects exactly one machine, then it's spent.

Short-lived. Codes expire after 5–60 minutes (you pick at mint). An expired code is worthless; mint another.

Shown once. The raw code appears exactly one time, immediately after minting, with a copy button and a live expiry countdown. It cannot be recovered afterward — only its fingerprint is stored.

Revocable. A live code you no longer want can be revoked from the list. Used, expired, and revoked codes stay visible as history.

        Give each code a label (office-mac-mini) so the history
        stays legible.

Connecting a machine

Mint a code on the Runners page. Copy it — you won't see it again.

            Install and connect the machine — one command.
            On the machine you're connecting (Linux or macOS on Apple Silicon),
            run the installer with your code — read it first at
            https://runner.kapable.ai/install.sh if you like. It
            downloads the runner, verifies its checksum, installs it to
            ~/.local/bin, and trades the code for the machine's
            own private credential. Pick a --name you'll
            recognise on the Runners page:

curl -fsSL https://runner.kapable.ai/install.sh | sh -s -- --code <your code> --name office-mac-mini

            The binary lands in ~/.local/bin — if your
            shell doesn't have that on PATH, add it, or call
            ~/.local/bin/kapable-runner directly below.

Start it working:

kapable-runner pull --foreman-url https://runner.kapable.ai --name office-mac-mini

            For now pull runs in the foreground — keep it
            alive under tmux, a systemd user unit, or
            launchd. A reboot-surviving background service is
            coming soon.

        The machine appears on the Runners page, online, usually within
        seconds. Linux (x86-64) and macOS (Apple Silicon) builds are published
        today; Windows and additional architectures are on the roadmap.

        The enrollment code itself is never stored on the machine — the
        runner trades it for a credential unique to that machine, which is what
        you later revoke.

Revoking a runner

        Revoking a machine (the Revoke button on its card)
        immediately invalidates its credential: it stops receiving work and
        cannot reconnect. This is not reversible — to bring the machine
        back, mint a new enrollment code and connect it fresh.

        Revoke when a machine is retired, lost, or you no longer trust it.
        Because each machine holds its own credential, revoking one never
        affects the others.

Security model, briefly

Each runner holds a private, individually revocable credential; there is no shared org runner key.

Org runners only ever receive your org's work — platform work is never scheduled onto them, and platform secrets never reach them. Runners are single-org: a machine connected to your org never builds for another.

An unsandboxed runner is always visibly marked. If the badge makes you uncomfortable, that's the point: prefer a sandboxed tier for machines that build untrusted branches.

Next Steps

Deployments

How the build-and-deploy pipeline works.

Security & Compliance

Auth methods, audit logging, and data protection.

Apps & Deployment API

The full apps API reference.

Next

Getting Started · Authentication

---

# Conductor

Source: https://docs.kapable.ai/conductor
Section: Build

Conductor

        Run Kapable's designer on your own Claude subscription. A small daemon
        called kapable-conductor (Kapable Conductor) sits on your Mac. Kapable sends
        design turns to it instead of to Kapable's own model access. The turns
        then draw on the Claude plan you already pay for, at your own rate
        limits, on hardware you control.

You need

A Mac with Apple silicon, a Kapable org, and a Claude subscription.

First call

curl -fsSL https://cli.kapable.ai/install.sh | sh

You should see the installer finish without an error.

macOS on Apple silicon only, today

          The daemon ships for darwin-arm64. There is no Linux
          build and no Intel build yet. On any other machine your design
          sessions keep running on Kapable's model access, which needs no
          install at all.

Why run it yourself

Your subscription, your limits. A design turn spends your Claude plan, not Kapable AI credits.

No platform spend cap. Kapable's own AI spend caps do not gate these turns. Kapable still records what each turn cost, so you can see it.

Your machine. The model session runs on your Mac, under your user account.

        You need a Kapable org first. The Kapable team creates that org for you
        and adds you as its owner. Self-serve signup is closed today, so there
        is no page to sign up on.

What gets installed

Thing	Where it lands	What it is

claude	~/.local/bin	Claude Code, the client for your own Claude subscription

kapable	~/.local/bin	The Kapable CLI, which installs and manages the daemon

kapable-conductor 0.9.34	~/.kapable/bin	The daemon that runs the design turns. Before 2026-09-24 it was called claude-conductor. An old install keeps running, and kapable conductor install moves it to the new name.

dev.kapable.conductor.plist	~/Library/LaunchAgents	A per-user launch agent. macOS starts the daemon when you log in.

scratch folders	~/.kapable/	One working folder per design session

        The CLI fetches the daemon from the same public release registry it
        updates itself from. It checks the SHA-256 before it installs anything.

No admin password

          Every step runs as your own user. Nothing here needs
          sudo. If a step asks you for an admin password, stop and
          tell us — that means something went wrong.

Install

1. Install the two clients.

curl -fsSL https://claude.ai/install.sh | bash
curl -fsSL https://cli.kapable.ai/install.sh | sh

        Both land in ~/.local/bin. Both print advice about adding
        that folder to your PATH via ~/.zshrc.

Put the PATH line in ~/.zprofile, not ~/.zshrc

          zsh reads ~/.zshrc only for interactive shells. An agent
          that runs these commands for you gets a non-interactive shell, and
          every later command fails with command not found. Login
          shells read ~/.zprofile as well. We measured that
          failure on 2026-08-15, so this is not a theory.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
export PATH="$HOME/.local/bin:$PATH"

kapable --version   # 0.18.0 or later
claude --version

2. Sign in to Claude. This is your own subscription.

claude auth login --claudeai
claude auth status

        The login opens a browser, and a human has to finish it. That is the
        whole point of this setup. Kapable never handles your Claude
        credential. claude auth status tells you whether the login
        took.

3. Sign in to Kapable.

kapable login

        With no flags this runs a device-code flow. It prints a URL and a short
        code, you approve the code in any browser, and the command waits until
        you do. It never opens a browser for you, so an agent can run it on
        your behalf.

4. Install the conductor.

kapable conductor install

        One command does the whole job. It downloads the daemon and checks the
        SHA-256. It registers the daemon with the platform and mints its
        credentials. It writes the launch agent and starts the daemon. Last, it
        checks that Kapable can reach your Mac.

        Two variants exist for repair work. kapable conductor setup
        redoes the platform-side half on its own, which is what you want after a
        credential rotation. kapable conductor install --no-setup
        puts the daemon on your Mac and skips that platform-side half.

Status of the kapable conductor commands (2026-08-15)

          The daemon itself is published and real. We downloaded it, matched its
          SHA-256, and ran it. The kapable conductor commands were
          still in the build on the day we wrote this page. We have not yet run
          them end to end on a clean Mac. Treat this page as the intended
          path. If a command is missing from your CLI build, update the CLI
          (kapable self-update) and tell us if it is still missing.

Check it worked

kapable conductor status

        Two facts matter, and only these two. The daemon has a recent
        heartbeat. Kapable can reach it. If status reports a daemon that runs
        locally but is not reachable, the install did not finish — run
        kapable conductor setup again.

        Trust heartbeat age over any word like online. An online label
        can survive a daemon that died weeks ago. A heartbeat from a minute ago
        cannot.

        This page prints no sample output on purpose. Any output we typed here
        would be illustrative rather than real, and a made-up line is worse than
        none. Read your own.

Turning it on for a design session

        Installing the daemon does not move your design work by itself. Each
        design session carries a backend setting, and Kapable sets that for you
        today. The designer has no self-serve toggle yet, and no org-wide
        default.

        So: ask us to point a session at your conductor. Ask again when you want
        that session back on Kapable's model access. We expect to replace this
        step with a switch you control.

What it exposes, and what it does not

What the daemon does on your Mac:

It opens an outbound tunnel to Kapable. Nobody has to open an inbound port on your router or firewall.

It refuses every request that carries no valid token.

It runs Claude Code sessions that Kapable asks for. Those sessions run as your user, with your user's reach.

Each session works in its own scratch folder under ~/.kapable/. The daemon creates that folder.

It will not overwrite an .mcp.json file that already exists in a project folder. It refuses instead.

Daemon credentials live in the launch agent's environment, in a file only your user can read. They never sit on a command line, where any other local account could read them.

What stays off your Mac:

No Kapable write credential. The designer's tools run on Kapable's side. Your Claude session calls them back over an authenticated channel, so no repository token reaches your machine.

Your Claude credential stays local. Claude Code stores it. Kapable never reads it.

No file sweep. The daemon runs the turns Kapable sends. It does not crawl your disk or ship files anywhere on its own.

        One consequence is worth naming. Your Claude session plans for itself,
        so a conductor turn skips the designer's own lint and compile nag loop.
        Edits still compile-check when you ship them.

Removing it

kapable conductor uninstall

        That stops the daemon, removes the launch agent, and drops its
        registration on the platform side. The same status note as above
        applies: we have not yet run this verb end to end on a clean Mac.

If you would rather do it by hand, or the verb is missing:

launchctl bootout gui/$(id -u)/dev.kapable.conductor
rm ~/Library/LaunchAgents/dev.kapable.conductor.plist
rm -rf ~/.kapable/conductor-scratch

        Tell us before you remove the daemon. A design session still aimed at a
        dead conductor fails its turns. We point those sessions back at
        Kapable's model access, and the designer works as it did before.
        Removing the daemon touches neither your Claude login nor the
        kapable CLI.

Next Steps

kapable CLI

Install, auth, and the full command tree.

Runners

The other way you lend your own machine to the platform.

Security

Token tiers, revocation, and audit logging.

Next

Getting Started · Authentication

---

# Webhooks

Source: https://docs.kapable.ai/webhooks
Section: Build

Webhooks

Not yet shipped

          Webhooks are a planned capability — this page describes the
          intended design, but there is no webhook configuration surface or delivery
          pipeline on the platform today (verified 2026-07-12). For reacting to
          platform activity now, use the audit log in the console or the
          Comms API's messaging primitives.

        Webhooks let your systems react to events on Kapable in real time.
        Instead of polling the API, Kapable sends an HTTP POST to your endpoint
        whenever something happens.

Event Types

Event	Fires when

app.deployed	A deployment completes successfully

app.failed	A deployment fails

app.paused	An app is paused

app.resumed	An app is resumed

app.deleted	An app is deleted

member.invited	A new member is invited to the org

member.joined	An invited member accepts and joins

member.deactivated	A member is deactivated

billing.subscription_changed	Subscription plan changes (upgrade, downgrade, cancel)

billing.payment_failed	A payment attempt fails

auth.login_anomaly	An unusual login is detected (new device, new location)

Payload Format

Every webhook POST sends a JSON body:

{
  "id": "evt_01J5K...",
  "type": "app.deployed",
  "created_at": "2026-05-21T10:30:00Z",
  "org_id": "d3f1a2b4-...",
  "data": {
    "app_id": "a1b2c3d4-...",
    "app_name": "my-app",
    "version": "v1.4.2",
    "deployed_by": "alice@example.com"
  }
}

        The data object varies by event type. See the API
        Reference for the full schema of each event.

Setting Up an Endpoint

Your webhook endpoint must:

Accept POST requests with a JSON body

Return a 2xx status within 10 seconds to acknowledge receipt

Be publicly reachable via HTTPS (plain HTTP is rejected)

Example endpoint in Node.js:

app.post('/webhooks/kapable', (req, res) => {
  const event = req.body;
  console.log(`Received ${event.type}`, event.data);

  // Process the event asynchronously
  processEvent(event).catch(console.error);

  // Acknowledge immediately
  res.status(200).json({ received: true });
});

Verifying Signatures

        Every webhook includes an X-Kapable-Signature header
        containing an HMAC-SHA256 signature of the request body, signed with
        your webhook secret.

Always verify the signature before processing:

        Python
        JavaScript

import hmac
import hashlib

def verify_signature(payload_body, signature_header, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

Retry Policy

        If your endpoint doesn't return a 2xx response, Kapable retries with
        exponential backoff:

Attempt	Delay

1st retry	1 minute

2nd retry	10 minutes

3rd retry	1 hour

        After 3 failed retries, the event is marked as failed. You can view
        failed deliveries in the Send Audit page.

Testing

During development, use a tunnel or request-inspection tool:

ngrok — expose your local server: ngrok http 3000

webhook.site — inspect payloads without any code

Kapable test events — use the "Send Test" button in webhook configuration to fire a sample event

Best Practices

Process asynchronously. Acknowledge the webhook immediately (return 200), then process the event in a background job. This prevents timeouts.

Be idempotent. You may receive the same event more than once (during retries). Use the id field to deduplicate.

Log everything. Store raw payloads for debugging. The Send Audit page also keeps a record.

Handle unknown events. New event types may be added. Your handler should ignore types it doesn't recognise rather than failing.

Rotate secrets regularly. You can regenerate your webhook secret in the console without downtime — both old and new secrets are valid for 24 hours during rotation.

Console Configuration

Coming soon

          Webhook configuration is coming soon to the console. In the meantime,
          contact support@kapable.ai
          for early access to the webhook API.

Next Steps

Deployments

The events most webhooks react to.

Comms API

Agents, mailboxes, messages, and SSE streams.

Security & Compliance

Token prefixes, audit logging, key rotation.

Next

Getting Started · Authentication

---

# Agents & Mail

Source: https://docs.kapable.ai/agents-and-mail
Section: Build

Agents & Mail

        Give your apps a real mailbox. Receive email at
        {mailbox-slug}@{org-slug}.worker.email, let agents in your
        app read it, reply via the same path. Included with every Kapable org
        — no extra charge.

Guide vs. reference

          This page is the hands-on guide. The full endpoint reference for
          agents, mailboxes, messages, rooms, and SSE lives on the
          Comms API page.

What you get

A real, RFC-compliant inbox at {anything}@{org-slug}.worker.email

A test mode that intercepts emails so your CI can verify magic-link flows without real sends

An agent-key credential model for machine-to-machine auth (agents reading their own mailboxes)

An app-token credential for your deployed app to send email via the API

Server-Sent Events (SSE) push notifications when mail arrives — no polling required

600 outbound emails/minute/org by default; per-mailbox limits configurable on request

Quickstart (5 minutes)

Navigate to Agents → New agent. Pick a slug (e.g. my-bot).

Open the agent → Mailboxes → New mailbox. Pick a name; this becomes the local-part of the address.

Open the mailbox → Channels → New channel. Set kind = email, address = {mailbox-slug}@{org-slug}.worker.email.

Back on the agent page, click Keys → Mint key. Copy the ak_... value — shown once.

Send a test email from your own inbox to {mailbox-slug}@{org-slug}.worker.email.

Within ~2 seconds, refresh the mailbox messages page — the email appears.

That's it. Your agent has a working inbox.

App tokens — sending email from your deployed app

        An app token (at_...) lets your deployed
        app send email through the Kapable Comms API. It is scoped to your
        org's sending domain, so a leaked token can only send from your own
        addresses.

        Mint one: navigate to
        App Tokens → Mint token. Copy the
        at_... value (shown once).

        When you create a new app via the Kapable dashboard, three environment
        variables are automatically set on the deployment:

Variable	Value

COMMS_URL	https://comms.kapable.ai

COMMS_APP_TOKEN	at_<hex> — org-scoped, valid for sending from *@{org-slug}.worker.email

EMAIL_FROM	noreply@{org-slug}.worker.email — default outbound from-address

Sending an email from your app:

POST $COMMS_URL/v1/internal/send
Authorization: Bearer $COMMS_APP_TOKEN
Content-Type: application/json

{
  "from": "$EMAIL_FROM",
  "to": ["user@example.com"],
  "subject": "Your magic link",
  "body_html": "<p>Click <a href=\"...\">here</a> to sign in.</p>",
  "body_text": "Click here to sign in: ..."
}

Returns 202 Accepted on success.

Test mode

          Pass "test_mailbox_id": "<uuid>" in the body and
          the email is intercepted into that mailbox instead of being sent via
          the real email provider. The test mailbox is immediately readable by
          the agent that owns it. This is the mechanism that makes automated
          login-flow testing possible without a real inbox.

Agent mail — receiving and reading email

        Agents authenticate with an agent key
        (ak_...). The key is scoped to one agent and gives read
        access to that agent's mailboxes.

        Key endpoints (auth:
        Authorization: Bearer ak_<hex>):

Method	Path	What it does

GET	/v1/mailboxes/{mailbox_id}/messages	List messages in a mailbox the agent owns

GET	/v1/messages/{id}	Fetch a single message (includes body_html, body_text)

POST	/v1/mailboxes/{mailbox_id}/send	Send via the mailbox (outbound, same from-domain rules)

GET	/v1/agents/{agent_id}/stream	SSE stream — receive push events when new mail arrives

        Agent keys are scoped to one agent. Cross-agent access returns
        403. See the
        Comms API
        for the complete mailbox and message reference.

Polling example (curl):

curl -sS "$COMMS_URL/v1/mailboxes/$MAILBOX_ID/messages" \
  -H "Authorization: Bearer $AGENT_KEY"

SSE push example (curl):

curl -sN "$COMMS_URL/v1/agents/$AGENT_ID/stream" \
  -H "Authorization: Bearer $AGENT_KEY"
# → data: {"event":"message.received","mailbox_id":"...","message_id":"..."}

Self-test — verify your own login flow

        The Python FastAPI template ships with a
        /agent-self-test admin endpoint that proves your app's own
        magic-link login flow works end-to-end without human involvement:

Creates a test agent + mailbox inside kapable-comms

Calls your app's /signup with "test_mailbox_id" set — the magic-link email is intercepted

The agent polls the mailbox, extracts the verify URL, and clicks it

Asserts the resulting session is valid

Returns {"status": "pass", "duration_ms": N} or a failure with the step that broke

        The same four-route contract (/signup,
        /auth/verify, /app,
        /agent-self-test) applies to any template language.
        Implement those routes + the env vars above and the self-test works.

Required env vars for self-test:

Variable	Description

COMMS_MEMBER_TOKEN	Member session token — used to create test agents/mailboxes

SELF_TEST_TOKEN	Bearer token for the /agent-self-test admin endpoint (keep secret)

JWT_SECRET	Secret for signing magic-link JWTs (min 32 chars)

PUBLIC_URL	App's public base URL (for building verify links)

Rate limits

Scope	Default limit

Outbound per mailbox	30 emails / minute

Outbound per org	600 emails / minute

Inbound per mailbox	60 emails / minute

        Exceeding any limit returns 429 Too Many Requests with a
        Retry-After header and a JSON body:

{"code": "rate_limit_exceeded", "limit": 30, "retry_after_seconds": 42}

        Higher limits are available on request. Contact support or open a
        ticket.

FAQ

Does this cost extra?

        No. Agent Mail is included with every Kapable org. Outbound emails are
        relayed through the platform's Resend account. Extremely high-volume
        senders (>10,000/day) may need a custom plan.

What happens if the email provider goes down?

        Inbound mail queues at the Cloudflare layer and retries. Outbound sends
        return 202 Accepted but delivery may be delayed. The
        send_audit log (visible under
        Agents → Audit log) records every attempt.

My app doesn't use the Python template. Can I still integrate?

        Yes. Implement POST /v1/internal/send calls using
        COMMS_APP_TOKEN for outbound, and
        GET /v1/mailboxes/{id}/messages using ak_...
        for inbound. Language is irrelevant — it's a plain JSON HTTP API.
        Rust and TypeScript template variants with the self-test wired up are
        coming soon.

How do I revoke a leaked token?

        For agent keys: open the agent → Keys →
        Revoke. Revoked immediately; in-flight requests using
        the old key return 401 within seconds. For app tokens:
        open App Tokens → Revoke. Same
        effect.

Can multiple agents share a mailbox?

        Not today. Each mailbox belongs to exactly one agent. If you need
        fan-out (multiple agents reacting to the same inbound email), SSE + a
        relay agent is the current pattern.

What's the COMMS_MEMBER_TOKEN and is it safe to put in my app?

        COMMS_MEMBER_TOKEN is an org-scoped session token used
        only by the self-test to create temporary test agents/mailboxes. It
        should be treated as a secret and not deployed into
        production containers — set it only in development or CI
        environments where the self-test runs. Production apps only need
        COMMS_APP_TOKEN for sending.

Next Steps

Comms API

The full endpoint reference for agents, mailboxes, and rooms.

Security & Compliance

Token prefixes, revocation, and audit logging.

Webhooks

React to platform events over HTTP.

Next

Getting Started · Authentication

---

# Skills

Source: https://docs.kapable.ai/skills
Section: Build

Skills

        Kapable ships Claude Code skills — installable capabilities that let
        any Claude Code agent use the platform to your taste. Drop one into
        ~/.claude/skills/ and invoke it by name in any session; it carries the
        platform's own doctrine so what it produces is on-brand, not generic scaffolding.

You need

A Kapable org and a session or org key. Install the skill before you invoke it.

First call

kapable artifact skill status

You should see the installed skill version.

What a skill is

          A skill is a self-contained folder with a SKILL.md (plus any bundled
          reference docs) that Claude Code discovers and invokes by the name: in its
          frontmatter. Kapable's skills are self-contained — the doctrine and examples travel
          with the skill — so they work installed globally or per-project, with no repo
          checkout required. The only thing you supply is an org API key.

Installing a skill

        Skills live in ~/.claude/skills/<name>/ (global — every session) or
        .claude/skills/<name>/ inside a project (that project only). Install the
        folder, set the prerequisite env, then invoke it by name:

# 1. Install the skill folder (global — available in every Claude Code session)
cp -R kapable-artifact-publish ~/.claude/skills/

# 2. Provide an org API key with the `write` scope (minted in the Kapable console)
export KAPABLE_ORG_KEY="sk_org_…"

# 3. Invoke it in any session
#    /kapable-artifact-publish   — or just: "publish this report as a Kapable artifact"

Auth

          Skills that call the platform need an sk_org_ org key — scope
          write to publish, read to list/read. The org is resolved from the
          key; you never pass an org id. A read-only key that tries to publish gets a
          403. See the Authentication guide.

kapable-artifact-publish

        Design and publish a beautiful, self-contained HTML artifact — a
        report, plan, spec, case, or brief — to your org gallery at
        {org}.kapable.ai/artifacts/, addressable forever and shareable with a link.

        The skill carries Kapable's design doctrine (its 02-TASTE spec + a fully worked
        reference render) so any model, not just its author, produces a document the org is
        proud to share — grounded in its subject, never stamped from a house template. It
        sketches a design plan, writes the self-contained HTML with real content, self-validates
        against the publish rules locally, publishes via the Artifacts API, and returns the URL.

Invoke it with

Trigger	What happens

/kapable-artifact-publish	Runs the full design → validate → publish flow

"publish this report / plan / case / spec / brief"	Same, with the kind inferred

"put this in the gallery" · "make a Kapable artifact"	Same

What you can publish

        Every artifact is a single self-contained HTML document (everything inline, nothing fetched
        at runtime), versioned immutably, and served under a strict Content-Security-Policy. Pick a
        kind:

kind	For

report	Status, delivery, and analysis reports

plan	Roadmaps, project and rollout plans

spec	Design specs and technical specifications

case	Business cases, proposals, narratives

brief	Short briefs, memos, session wraps

Under the hood

        The skill publishes through the Kapable Artifacts API. You can call it directly too —
        with the @kapable/sdk or a plain request:

Method	Path	SDK (client.artifacts)

POST	/v1/artifacts	publish

GET	/v1/artifacts	list

GET	/v1/artifacts/{slug}	get

GET	/v1/artifacts/{slug}/html	html

POST	/v1/artifacts/{slug}/shares	share

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

const client = new KapableClient({
  baseUrl: "https://api.kapable.ai",
  apiKey: process.env.KAPABLE_ORG_KEY, // sk_org_… with write scope
});

const res = await client.artifacts.publish({
  slug: "q3-delivery-report",
  title: "Q3 — Delivery Report",
  kind: "report",
  html,                       // the validated, self-contained document
  summary: "What shipped, live-verified, in three unattended days.",
  favicon: "🧾",
});
console.log(res.url); // → https://{org}.kapable.ai/artifacts/q3-delivery-report

        Once published, mint a revocable public link with client.artifacts.share(slug)
        — it serves the document, logged-out, at https://kapable.ai/a/{token}
        (noindex, honoring revocation and expiry).

The doctrine is the differentiator

          Artifacts without the doctrine is a file server. The skill's whole point is that taste
          travels with the tool: it loads Kapable's design spec before writing a line of HTML,
          so a document published by an agent reads as designed, not slop. Do not skip that step.

More skills

        This catalog grows as the platform does. Want a skill for another Kapable capability —
        or to publish one of your own? Reach us via the Forgejo
        or point your agent at kapable.ai/llms.txt.

Next

Getting Started · Authentication

---

# Artifacts API

Source: https://docs.kapable.ai/artifacts
Section: Build

Artifacts API

        Durable, designed renders. An artifact is a self-contained HTML document — a
        report, a plan, a business case, a spec — published once, frozen at a version,
        addressable forever, and shared with a person rather than queried by a machine.
        The wiki is the living telling; artifacts are the documents kept.

Four properties define it

          Finished, not living — a version never changes after publish;
          updating means publishing a new version. Design is content — the
          visual treatment is part of the author's statement; the platform enforces safety, not a
          house template. Self-contained or rejected — external resource
          references fail at publish time, not at view time years later. Org-gated by
          default — sharing outward is an explicit, revocable, minted capability.

        Base URL https://api.kapable.ai. Publish/write needs an sk_org_
        key with the write scope (or an org-member session); reads need read.
        Agents are first-class publishers — most artifacts are authored by AI sessions
        following the taste doctrine (see Skills).

Publish

        POST /v1/artifacts is create-or-append: a new
        slug creates version 1; an existing slug appends version n+1.
        Returns the artifact id, the new version, the org URL, and the content
        sha256 (content address, verified on write).

Method	Path	SDK (client.artifacts)

POST	/v1/artifacts	publish

        curl
        TypeScript
        Rust

curl -s -X POST https://api.kapable.ai/v1/artifacts \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d '{
    "slug": "q3-business-case",
    "title": "Q3 Business Case",
    "kind": "case",
    "html": "<!doctype html><html><head><title>Q3</title></head><body><h1>Q3</h1></body></html>",
    "summary": "The case for shipping verified features",
    "favicon": "🧾",
    "session_ref": "planning-loop · 2026-07-03"
  }'

# 201 Created
# { "artifact_id": "edce30ff-…", "version": 1,
#   "url": "https://acme.kapable.ai/artifacts/q3-business-case",
#   "sha256": "bfc97dac…" }

import { KapableClient } from '@kapable/sdk';
const client = new KapableClient({ apiKey: process.env.KAPABLE_ORG_KEY });

const res = await client.artifacts.publish({
  slug: 'q3-business-case',
  title: 'Q3 Business Case',
  kind: 'case',                 // report | plan | spec | case | brief | other
  html: selfContainedHtml,
  summary: 'The case for shipping verified features',
  favicon: '🧾',               // 1–2 emoji: gallery + tab identity
  session_ref: 'planning-loop · 2026-07-03',
});
// res.version === 1 ; res.sha256 === content address ; res.url === org URL

use kapable_sdk::{KapableClient, artifacts::PublishArtifactRequest};
let client = KapableClient::new(std::env::var("KAPABLE_ORG_KEY")?);

let res = client.artifacts().publish(PublishArtifactRequest {
    slug: "q3-business-case".into(),
    title: "Q3 Business Case".into(),
    kind: "case".into(),
    html: self_contained_html,
    summary: Some("The case for shipping verified features".into()),
    favicon: Some("🧾".into()),
    session_ref: Some("planning-loop · 2026-07-03".into()),
    tags: None,
}).await?;

Self-contained or rejected (422)

          Publish-time validation rejects any document that reaches outside its own bytes and
          returns the exact offending constructs so an agent can self-fix:
          external <script src>/<link href>/<img
          src>, CSS @import/url() to non-data:
          URLs, <iframe>/<object>/<base>,
          and external meta refresh/form action. Plain hyperlinks
          (<a href="https://…">) are fine — a document may cite
          the web, it just may not depend on it. Size cap: 2 MiB
          per version; versions are kept forever.

// 422 Unprocessable Entity
{ "error": "unprocessable", "code": 422,
  "detail": "artifact is not self-contained; fix the offending constructs and re-publish",
  "offending": [ { "construct": "script src", "snippet": "<script src=\"https://cdn.example/x.js\">" } ] }

List, get & serve

        The gallery feed returns latest-version metadata only (never html). Fetch one artifact's
        metadata + full version list, or its raw self-contained bytes (pin a version with
        ?v=n). Every served document carries the sealed CSP that enforces
        self-containment at view time.

Method	Path	SDK (client.artifacts)

GET	/v1/artifacts	list

GET	/v1/artifacts/{slug}	get

GET	/v1/artifacts/{slug}/v/{n}	get (version meta)

GET	/v1/artifacts/{slug}/html?v=n	html

DELETE	/v1/artifacts/{slug}	retract — member session (see Retraction)

        The org gallery is served at {org}.kapable.ai/artifacts/ (org-member session),
        a designed register that is itself the feature's first artifact. Filter with
        ?kind= and search with ?q=.

Reading an artifact — the bar, Listen and Focus

        Every artifact opens with a slim bar above the document. The same bar appears when the
        artifact opens in a window on the desktop. Left to right: the version picker, then the
        document controls. Not every control shows on every document; a control only appears
        when the document can use it.

Control	What it does

Version picker	Read an earlier version. Versions never change once published.

Listen (speaker icon)	Play the narration. Only present when this version carries a recording. See below.

Share	Copy the link, mint a public link, or show a QR code.

Reading width	Cycle narrow, default and wide measures.

A− / A+	Smaller or larger reading size. Remembered per reader.

Focus	Present the document as slides. See below.

Copy for LLM	Copy the whole document as Markdown, chrome stripped, ready to paste into a model.

Print	Print or save as PDF. The bar and margin stay out of the output.

History (arrow)	The version list and resolved discussions.

Colour scheme	Auto, light or dark for this document. Inside the desktop the bar carries its own toggle; in a normal tab the shared header's toggle applies.

Listen — narrated documents

        When an author has attached a recording, a speaker icon appears in the bar. Click it for the
        player: play or pause, stop, skip back fifteen seconds, playback speed, skip forward fifteen
        seconds. The recording is a spoken briefing written for the ear, not the page read aloud, so
        it is usually shorter than the document.

        If the author also attached a cue track, the page follows along: as the
        voice reaches each cued passage, the page scrolls there. There is no switch to turn this on.
        Scrolling, using the wheel, or touching the page hands control back to you; pressing play
        again re-engages following from wherever the voice is. In a background tab the scroll waits
        and catches up when you return. A version published without a new recording shows a quiet
        pointer to the most recent narrated version instead of the speaker icon.

Focus — present as slides

        The Focus control turns the document into slides for walking it on a call. Nothing is
        re-rendered: the same page is shown one section at a time, split at the document's own
        headings (with long sections split again at their sub-headings), and restored exactly on
        exit. The button only appears when the document yields at least two slides. A wayfinding
        line at the top shows the section name and the slide count, and fades after a couple of
        seconds until you move.

Key	Action

→ / ←	Next / previous slide

Space / PageDown	Scroll a long slide, then advance at its end (presenter remote friendly)

Home / End	First / last slide

Esc	Leave Focus and return to reading mode where you were

        Each slide has a deep link: the address bar carries ?focus=<heading-id>, so a
        link opens straight on that slide. On a desktop-sized screen the stage scales the text up by
        a fifth on top of your own reading size; phones keep the author's scale. Ratings, when the
        document has them, sit as a compact footer while Focus is active.

        Listen works inside Focus. If the narration is playing when you enter Focus
        it keeps playing, the stage header carries its own play and pause control, and the slides
        follow the voice: when the narration crosses a cue, the stage flips to the slide that holds
        that passage. Leaving Focus does not stop the narration.

Sharing

        A share is a minted, revocable capability — not an ACL. Mint a link and a
        partner with no Kapable account reads the exact bytes at
        kapable.ai/a/{token} (noindex, a clean render with no chrome and no margin).
        Pin a version or follow latest; set an optional expiry (it must lie in the
        future — a past expires_at is a 400 at
        mint, never a link that is dead on arrival); revoke and the link dies within one
        request (410 Gone).

Method	Path	SDK (client.artifacts)

POST	/v1/artifacts/{slug}/shares	share

GET	/v1/artifacts/{slug}/shares	listShares

DELETE	/v1/artifacts/{slug}/shares/{id}	revokeShare

# Mint → returns { id, public_url, token }. Revoke by id; then /a/{token} → 410.
curl -s -X POST https://api.kapable.ai/v1/artifacts/q3-business-case/shares \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d '{ "version": 1 }'
# { "id": "2c52bf4e-…", "public_url": "https://kapable.ai/a/9f3750e9…", "token": "9f3750e9…" }

Retraction — the tombstone

        Publishing is an agent act; retraction is a human one.
        DELETE /v1/artifacts/{slug} sets a tombstone: the artifact leaves the
        gallery and search, and every read surface — the org view, the raw
        /v1 html/meta routes, and every live share — returns
        410 Gone carrying the full tombstone facts (who retracted it, when,
        and the optional reason), never a bare 404. It is member-session only:
        an sk_org_ agent key gets a 403 (“agents publish, agents
        never destroy”). Retraction is reversible — POST …/restore
        clears the tombstone.

Method	Path	SDK (client.artifacts)

DELETE	/v1/artifacts/{slug}	retract — member session only

POST	/v1/artifacts/{slug}/restore	restore — member session only

DELETE	/v1/artifacts/{slug}?purge=bytes	purgeBytes — member session only

        curl
        TypeScript
        Rust

# Retract — member-cookie session only; an sk_org_ agent key → 403.
curl -s -X DELETE https://acme.kapable.ai/artifacts/q3-business-case \
  --cookie "$SESSION_COOKIE" -H "Content-Type: application/json" \
  -d '{ "reason": "Superseded by the FY24 plan" }'

# Every read now 410s with the tombstone facts (org view AND /v1 html/meta AND live shares):
# { "error": "retracted", "code": 410, "detail": "this artifact has been retracted",
#   "title": "Q3 Business Case", "retracted_at": "…", "retracted_by": "Herman",
#   "reason": "Superseded by the FY24 plan" }

# Restore clears it (member session only):
curl -s -X POST https://acme.kapable.ai/artifacts/q3-business-case/restore \
  --cookie "$SESSION_COOKIE"
# { "warnings": [] }   // carries a note if the bytes were previously purged

await client.artifacts.retract('q3-business-case', {
  reason: 'Superseded by the FY24 plan',
});
await client.artifacts.restore('q3-business-case');

// The tombstone register — read-scoped, shows ONLY retracted artifacts:
const gone = await client.artifacts.list({ retracted: '1' });

use kapable_sdk::artifacts::{RetractRequest, ListArtifactsQuery};

client.artifacts().retract("q3-business-case",
    RetractRequest { reason: Some("Superseded by the FY24 plan".into()) }).await?;
client.artifacts().restore("q3-business-case").await?;

let gone = client.artifacts().list(ListArtifactsQuery {
    retracted: Some("1".into()), ..Default::default() }).await?;

The retracted register (D55)

          GET /v1/artifacts?retracted=1 lists ONLY retracted artifacts — the
          tombstone register, mutually exclusive with the ordinary live list. It is available to
          any read-scoped key, not just members: retraction hides a document's
          content, never its existence. Any other value for
          retracted is a 422 receipt naming the only legal value,
          1.

Purge is the escalation, not the default (D57)

          For the genuine legal / leaked-secret case, DELETE
          /v1/artifacts/{slug}?purge=bytes irreversibly overwrites every version's html
          (and any audio) with a fixed sentinel. It is legal only on an already-retracted
          artifact (else 409 “restore first” — two
          deliberate acts, never one). Rows, shas, metadata, and verdicts all remain: the record
          still proves what existed and when, just not its content. A later
          restore revives the slug, and its warnings[] says the bytes
          are gone for good.

        A retracted document seals its margin too: the five annotation write paths (create,
        reply, resolve, edit, edit-reply) refuse rather than accrue a note no surface can show.
        An org member gets a 409 naming the fix — “this artifact is
        retracted; the margin is closed with it — restore first (POST
        /v1/artifacts/{slug}/restore) to continue the conversation” — while a
        guest, who cannot restore, gets a 410 Gone (the withdrawn-capability
        idiom the guest door already uses). Existing threads stay readable; only writing
        is closed. Publishing a new version onto a retracted slug likewise 409s
        — restore first.

The margin — annotations

        The margin is the discussion layer that lives beside a frozen version, never
        inside it. A reader highlights a passage and comments; the highlight is durable —
        anchored to the version's frozen bytes and visible to every org member. The document is
        never edited: convergence happens one of two ways — minds align (a reply resolves the
        thread) or the artifact was wrong (a new version resolves it). Public shares never show the
        margin; it is an org-member surface.

Method	Path	SDK (client.artifacts)

POST	/v1/artifacts/{slug}/annotations	createAnnotation

GET	/v1/artifacts/{slug}/annotations?version=&status=	listAnnotations

GET	/v1/artifacts/{slug}/annotations/{id}	getAnnotation

POST	/v1/artifacts/{slug}/annotations/{id}/replies	replyAnnotation

POST	/v1/artifacts/{slug}/annotations/{id}/resolve	resolveAnnotation

PATCH	/v1/artifacts/{slug}/annotations/{id}	editAnnotation

PATCH	/v1/artifacts/{slug}/annotations/{id}/replies/{replyId}	editReply

        An annotation stores a quote selector anchor = {exact, prefix, suffix} plus a
        server-maintained positions map ({"<version>": {start,end} |
        null}). Because versions are immutable, anchoring is a publish-time batch: on each
        new version, open annotations re-anchor once — a concrete position when the quote
        survives, or an explicit null orphan receipt ("highlight lost
        in vn") when the passage changed. Never a silent drop.

Resolution is a taxonomy (D12)

          Resolve with status one of aligned (mental models converged;
          the document was right), amended (the document was corrected by a new
          version — requires resolved_by_version), or declined (a
          reasoned refusal). Every resolve requires a reply body —
          a resolution without a stated answer is a silent drop, and forbidden.

# Create → highlight a passage of a version and comment.
curl -s -X POST https://api.kapable.ai/v1/artifacts/q3-business-case/annotations \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d '{ "version": 1,
        "anchor": { "exact": "shipping verified features", "prefix": "case for ", "suffix": "." },
        "body": "Do we have the receipt for this claim?" }'

# Resolve amended, pointing at the fixing version (reply is required).
curl -s -X POST https://api.kapable.ai/v1/artifacts/q3-business-case/annotations/$ID/resolve \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "amended", "resolved_by_version": 2,
        "reply": "Corrected in v2 with the loop receipt.", "session_ref": "discuss · repo" }'

        Every annotation renders a Copy prompt control in the viewer that emits a
        versioned <kapable-annotation v="1"> block — paste it into any
        Claude Code session and the kapable-artifact-discuss
        skill answers in the margin (reply and resolve aligned, or republish and
        resolve amended). The clipboard is the transport; the human stays in the loop.

Polish & suggestions (M8)

        The margin's viewer batch: status-colored highlights (resolved threads read
        quieter than open ones — the margin celebrates convergence by calming
        down), an open · N replies chip so an answered-but-unresolved
        thread never looks ignored, mono/tabular-nums timestamps on every annotation and
        reply, a margin rail (the drawer, listing every thread in document
        order), overlapping-highlight detection (a click in the overlap filters the rail to
        the intersecting threads), figure annotation, edit-own, live updates over SSE, and
        suggestions.

Method	Path	SDK (client.artifacts)

PATCH	/v1/artifacts/{slug}/annotations/{id}	editAnnotation

PATCH	/v1/artifacts/{slug}/annotations/{id}/replies/{replyId}	editReply

GET	/artifacts/{slug}/sse	— (viewer-internal, not an SDK method)

Edit-own (D23)

          Authors may edit their own annotation/reply body anytime — no status gate.
          The server compares the caller's identity to the row's created_by/
          author and 403s a mismatch; a successful edit stamps
          edited_at, shown in the viewer as edited · {ts}.

        Figure annotation — selecting an <img>,
        <svg>, or <table> offers "annotate this
        figure." The anchor becomes an ELEMENT selector,
        {kind: "element", tag, nth_of_type} — the Nth occurrence of that
        tag in the document, in document order — instead of a text quote selector.
        Element anchors get the same per-version orphan receipts as text anchors: if the
        Nth img no longer exists in a new version, the thread orphans exactly
        like a vanished quote.

Suggestions (D24)

          createAnnotation accepts an optional proposed_text —
          a concrete replacement for the highlighted passage, member-only (guests ask and
          reply; they never propose replacement text, D24a). The viewer renders it as a
          compact inline diff (deletions struck, insertions underlined). The steward treats
          a suggestion exactly like any other question — it may discuss or decline, but
          it never applies one (no action in its typed set does that, D13 unchanged).
          Adopting a suggestion is a session decision: republish version n+1
          incorporating the change, then resolve amended — the
          kapable-artifact-discuss skill's "apply
          suggestion" flow does exactly this.

        Live updates — the org viewer opens an SSE stream
        (GET /artifacts/{slug}/sse, viewer-internal, not an SDK method) fed by
        the same LISTEN/NOTIFY trigger pattern the platform uses elsewhere
        (notify_table_change on both margin tables). A change
        event carries no row data — the client re-fetches through the normal API, so a
        reply posted in one browser session appears in a second open viewer without a
        reload. Degrades to reload-on-focus when SSE is unavailable.

Gallery signals

        The list feed carries an open_thread_count per artifact, surfaced as an
        "N open threads" chip on each gallery card. The ?discussions=active filter
        (API and gallery) narrows the register to artifacts with open annotation threads —
        the "active discussions" lens.

# Only artifacts with open threads
curl -s "https://api.kapable.ai/v1/artifacts?discussions=active" -H "x-api-key: $KAPABLE_ORG_KEY"
# { "data": [ { "slug": "q3-business-case", "open_thread_count": 1, … } ], "total": 1 }

Grounding & the decision history

        publish accepts an optional grounding array — where this
        version's truth lives, frozen with it forever: [{ kind: "repo"|"ks"|"url", ref:
        string }], ≤16 entries, each ref ≤512 chars. Grounding is
        advisory — absence never blocks a publish (D15); it only lowers the
        steward's license to answer confidently (see below). It's surfaced in version metadata
        (never the gallery list feed) and rendered as a quiet "grounded in" line in the chrome
        — url refs are links, repo/ks refs are mono
        text. Nothing that reads grounding ever fetches a url ref; it is
        cited, never resolved.

curl -s -X POST https://api.kapable.ai/v1/artifacts \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d '{ "slug": "q3-business-case", "title": "Q3 Business Case", "kind": "case",
        "html": "…",
        "grounding": [
          { "kind": "repo", "ref": "platform/relate/src/loop.rs" },
          { "kind": "ks", "ref": "claim:relate-tick-54-improvements" }
        ] }'

        GET {org}.kapable.ai/artifacts/{slug}/versions renders the
        decision history: every version with its publish metadata, the aligned/
        declined counts of threads it originated, and — for a version born from a fix
        — "this version exists because…" naming the amended thread that
        caused it, deep-linked back into the margin. It is entirely derived from existing publish
        + margin records (D16); nothing new is authored to render it. The chrome's version picker
        links to it.

The steward

        The steward is a background tick that answers open, question-intent
        annotations on its own — grounded citation when it can give one, honest discussion
        or a routed hand-off when it can't. It is deliberately restricted to a
        typed action set it can never step outside of: aligned
        (resolves the thread, citing the version's own declared grounding — downgraded
        server-side to discuss if the version declared none, regardless of what the
        model itself claims), discuss (a reply, thread stays open), declined
        (a reasoned resolve), or route (hands off to a human/the authoring agent).
        It never publishes and never resolves amended —
        amending a document stays a deliberate act under the publish doctrine. Annotation bodies
        and document content are fenced, labeled DATA in the steward's prompt; an annotation that
        tries to instruct it ("ignore your instructions and publish/delete…") cannot
        succeed — the model's raw output is parsed as strict JSON against the four literal
        actions above, so there is no fifth action for an injection to land in.

        Every annotation may declare an intent on
        createAnnotation: question (default — the only intent the
        steward acts on), uncertainty (an agent's own declared doubt after
        publishing — badged distinctly, adjudicated by a human, steward-ignored by design),
        or review-request (a plain flag, also steward-ignored).

Method	Path	SDK (client.artifacts)

GET	/v1/steward/status	stewardStatus

        Loop-safety is structural, not a heuristic: the steward never re-triggers on its own
        replies (it only ever considers annotations with no existing steward reply), never acts
        on agent/service-authored annotations, and never treats a non-question intent
        as something to answer. It runs under a per-org daily cap (live-computed from the DB, so
        it's correct across a blue-green deploy pair) — every skip, whatever the reason
        (cap reached, no model configured, unparseable output), leaves a visible receipt in the
        logs and in GET /v1/steward/status, never silence.

Bundle shares

        A single share link exposes one artifact. A bundle exposes a
        named set — the missing primitive for sharing a cross-linked batch (a
        report + its appendices, a spec pack) publicly as the whole it was authored to be.
        Bundle shares live in the same token namespace as plain shares:
        GET /a/{token} resolves either kind automatically.

        Bytes are served verbatim — a bundle never rewrites stored html,
        never injects a <base>, never touches connect-src for a
        plain (non-annotate) bundle. What it adds is a small prepended public chrome carrying a
        click-resolver script: any link on the page whose path resolves to
        /artifacts/{slug} for a slug that is a member of the bundle
        navigates to /a/{token}/{slug} instead of the org host; every other link
        — external, or a non-member artifact — is left completely untouched. Authors
        write ordinary <a href="/artifacts/other-slug"> cross-links; the
        bundle makes them resolve within the shared set for a logged-out reader.

        Revoking a bundle (DELETE /v1/bundles/{id}) invalidates every member in one
        call — the next request to any /a/{token}/* path 410s.

Method	Path	SDK (client.artifacts)

POST	/v1/bundles	mintBundle

GET	/v1/bundles	listBundles

DELETE	/v1/bundles/{id}	revokeBundle

curl -s -X POST https://api.kapable.ai/v1/bundles \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Q3 launch pack", "slugs": ["q3-business-case", "q3-runbook", "q3-faq"] }'
# { "id": "…", "name": "Q3 launch pack", "token": "…", "public_url": "https://kapable.ai/a/…",
#   "slugs": ["q3-business-case","q3-runbook","q3-faq"], "can_annotate": false }

Guest margins

        A share or bundle minted with can_annotate: true serves the annotation layer
        on its public link to a reader with no Kapable account — the
        default share remains a sealed, clean render; crossing this boundary is a deliberate
        mint-time choice, never a default. The guest surface is share-token auth:
        the token embedded in the URL path is the sole credential (no separate guest login), so
        it is not part of the authenticated customer SDK — a guest interacts through the
        served page's own margin UI, not @kapable/sdk.

        A guest types a display name once (remembered client-side) and can highlight a passage
        to ask a question, or reply on a thread their own link opened. They can
        never resolve a thread and their intent is always
        question, regardless of anything sent client-side — there is no resolve
        route on the guest surface at all. Writes are rate-limited per token.

        The privacy wall: a guest reading back sees only threads opened under
        their own share/bundle token — never an org-internal thread, never another
        guest link's threads, even on the identical artifact. Org members see everything in the
        normal margin viewer, with guest threads badged guest · {name}. Guest
        questions count against the org's steward cap and get steward answers exactly like a
        member's question would.

# mint an annotate-enabled share
curl -s -X POST https://api.kapable.ai/v1/artifacts/q3-business-case/shares \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d '{ "can_annotate": true }'
# a logged-out reader opening the public_url gets the margin layer;
# their questions/replies ride /a/{token}/annotations* (or /a/{token}/{slug}/annotations*
# for a bundle member) — share-token auth, not an sk_org_ key.

The warnings channel

        POST /v1/artifacts now always returns an additive
        warnings: [] array alongside the existing response fields — a WARN,
        never a reject; the publish always succeeds. The first warning: pandoc's dollar-math
        span residue (class="math) surviving into a stored artifact — no
        artifact kind renders TeX, so its presence is almost always pipeline corruption. The
        publish skill already rejects this author-side; the warning is defense-in-depth for
        other authors' pipelines. Unknown/future warning codes are safely ignorable by old
        clients.

{ "artifact_id": "…", "version": 2, "url": "…", "sha256": "…",
  "warnings": [ { "construct": "math-span", "snippet": "class=\"math inline\"" } ] }

Per-org steward settings

        The platform-wide STEWARD_ENABLED environment toggle remains the
        master switch — the tick never runs at all when it's off,
        regardless of any org setting. An org admin/owner (or platform staff scoped via
        X-Org-Id) can additionally opt their own org out while the
        platform default stays on, and override the per-org daily reply cap.

Method	Path	SDK (client.artifacts)

GET	/v1/artifacts/admin/steward-settings	getStewardSettings

PUT	/v1/artifacts/admin/steward-settings	updateStewardSettings

curl -s -X PUT https://api.kapable.ai/v1/artifacts/admin/steward-settings \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
# { "org_id": "…", "enabled": false, "daily_cap_override": null,
#   "effective_enabled": false, "effective_daily_cap": 20 }

Reply-to routing & margin health

        publish accepts an optional reply_to object — where the
        steward's route action should deliver, frozen with the version alongside
        grounding: { kind: "comms-mailbox", ref: string }, where
        ref is a kapable-comms mailbox id (a UUID minted via kapable-comms' own
        POST /v1/mailboxes). Explicit only — the free-text
        session_ref provenance field is never parsed for routing. When a
        route-d reply lands on a version with a declared reply_to, the
        steward delivers it into that mailbox (via kapable-comms'
        POST /v1/internal/intercept) in addition to posting the reply in the
        margin as usual; the generic STEWARD_AGENT_MAIL_URL hook is unrelated and
        still fires unconditionally on every route.

curl -s -X POST https://api.kapable.ai/v1/artifacts \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d '{ "slug": "q3-business-case", "title": "Q3 Business Case", "kind": "case",
        "html": "…",
        "reply_to": { "kind": "comms-mailbox", "ref": "5b1e6c0a-2f3a-4e9a-9d2b-8f1c2a3b4c5d" } }'

Knowledge capture on aligned

          When a margin thread resolves aligned, the clarified fact may be durable
          enough to belong in the Knowledge Substrate (the claim store), not just that one thread. The
          kapable-artifact-discuss skill MAY file a KS claim after such a
          resolution — claim text = the clarified fact, provenance = the thread's own
          deep-link URL. This is a skill-side, judgment call (a MAY, not a ceremony) — the
          service itself stays uncoupled and never calls kapable-knowledge.

        The org gallery also carries a derived margin health strip: the oldest
        still-open question (aging), the steward's answer-coverage rate over
        question-intent threads, and the artifacts with the most discussion. All
        three are plain queries over the existing annotation tables — no new tables, no new
        authored state — and the strip renders nothing at all when an org has no margin
        activity yet (never a wall of meaningless zeros).

Audio summaries — the ear is a reader

        A version may carry one spoken-summary recording, played from the
        chrome's quiet “▸ Listen” control — never embedded in the
        document, never autoplaying. Attach is write-once: a version that
        already carries audio — a second attach — returns 409; a wrong
        recording is corrected the only way anything here is corrected, by publishing the next
        version. Audio has its own 3 MiB cap, independent of the document's
        2 MiB cap, and is validated MPEG (mp3) by magic bytes — not by the declared
        content-type alone.

        Attach inline at publish time (one round trip) via the optional audio field,
        or afterward via the dedicated attach endpoint. Generation is owned by
        kapable-ai’s dedicated TTS endpoint
        (POST /v1/ai/tts): if the org has configured its own ElevenLabs key
        (PUT /v1/ai/admin/tts-settings, admin/owner only), that key synthesizes with
        no metering; otherwise the platform’s own key synthesizes and a
        usage event is recorded. Artifacts itself never calls ElevenLabs and stores no TTS
        keys — it only ever accepts already-synthesized bytes.

Method	Path	SDK (client.artifacts)

GET	/v1/artifacts/{slug}/audio	audio

POST	/v1/artifacts/{slug}/v/{n}/audio	attachAudio

# 1. Synthesize (kapable-ai) — key resolution is automatic (org key, else platform key + metering).
curl -s -X POST https://api.kapable.ai/v1/ai/tts \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d '{ "text": "Relate'"'"'s fifty-fourth tick shipped twenty-one improvements today…" }' \
  -o summary.mp3

# 2. Attach — write-once; a second attach on the same version → 409.
B64=$(base64 -i summary.mp3 | tr -d '\n')
curl -s -X POST https://api.kapable.ai/v1/artifacts/relate-tick-54/v/1/audio \
  -H "x-api-key: $KAPABLE_ORG_KEY" -H "Content-Type: application/json" \
  -d "{ \"data\": \"${B64}\" }"
# { "version": 1, "content_type": "audio/mpeg", "sha256": "…", "bytes": 84213,
#   "audio_url": "https://acme.kapable.ai/artifacts/relate-tick-54/audio?v=1" }

        Or inline at publish time, in one call — the audio field shares the
        exact same base64/MPEG/3 MiB validation:

{ "slug": "relate-tick-54", "title": "…", "kind": "report", "html": "…",
  "audio": { "data": "", "generated_via": "elevenlabs · eleven_v3 · platform-key" } }

        POST /v1/artifacts’s response gains an audio_url field
        (present only when THAT call attached audio), version metadata gains a
        has_audio boolean, and the artifact.published herald event
        gains an optional audio_url that kapable-notify renders as a “Listen”
        line alongside the document link. The document’s serve-time CSP on authenticated org
        views gains exactly media-src 'self' for the chrome’s player —
        public share links and the raw html endpoint are completely unchanged.

Written for the ear, not read from the page

          The publish skill’s audio step is opt-in and doctrine-bound: author fresh spoken
          prose (∼60–90 seconds, conversational) specifically for listening —
          never the gallery summary field or the document text read
          aloud. The platform never synthesizes uninvited; generating and attaching audio is
          always a deliberate, visible act with a visible cost.

        Follow-along cues (M17) — the audio payload may carry an optional
        cues[] track: { t, quote } entries where t is
        seconds into the recording (strictly increasing, 1–64 of them) and
        quote reuses the margin's anchor shape to point at a passage in the
        document. As narration crosses each t, the docent scrolls the reader there.
        Cues freeze WITH the audio under the same write-once law (D29) — they attach in the
        same audio payload and change only by publishing a new version. Version
        metadata gains a has_cues boolean; the platform validates shape only
        (finite, increasing t; an anchor present) and returns per-cue
        422 receipts (cues[3].t, cues[3].quote.exact) so
        an author self-fixes in one round-trip.

{ "data": "", "generated_via": "elevenlabs · eleven_v3 · org-key",
  "cues": [
    { "t": 0,    "quote": { "exact": "Relate's fifty-fourth tick" } },
    { "t": 12.5, "quote": { "exact": "twenty-one improvements", "prefix": "shipped " } }
  ] }

        Audio is write-once per version, so republishing without re-attaching narration sheds the
        recording. When a bare version's lineage still has a narrated one, version metadata
        carries narrated_by (the nearest narrated version's number, earlier or
        later; null when none), derived at read time — and the chrome offers a
        quiet pointer back to the tour rather than dropping the “Listen” affordance
        silently.

Decision artifacts — the decision is a document

        A decision-kind artifact freezes a ballot with the version:
        a selection mode (pick-one or {"pick-n": n}) and 2–8
        options, each with a short id and a required label. The rendered candidates — the
        side-by-side, argued case for each option — live in the document body as ordinary,
        designed HTML; the decision metadata is the machine-readable twin. A
        decision-kind publish with no ballot, or a ballot with fewer than
        2 options, returns 422.

{ "slug": "palette-decision", "title": "Which palette ships", "kind": "decision", "html": "…",
  "decision": {
    "mode": "pick-one",
    "options": [
      { "id": "a", "label": "Petrol palette", "summary": "Cooler, reads calmer at scale" },
      { "id": "b", "label": "Porcelain palette", "summary": "Warmer, higher first-glance energy" }
    ]
  } }

        Deciding is a human act in the chrome, never an agent capability
        — the mirror of the steward never publishing. An org member sees a
        “Decide” control on an undecided decision-kind version (radio inputs for
        pick-one, checkboxes for pick-n, an optional rationale) and
        submits from the browser. The verdict is write-once: a second decide
        on the same version returns 409; a change of mind is a new version with a
        fresh ballot, so the version history is the decision history, no new view
        needed. chosen must be a subset of that version’s frozen options, or
        422.

Method	Path	SDK (client.artifacts)

POST	/v1/artifacts/{slug}/v/{n}/verdict	decide — member session only

GET	/v1/artifacts/{slug}/v/{n}/verdict	getVerdict — members + agent keys

# Member-cookie session only — an sk_org_ agent key gets a 403 here (not a route error):
curl -s -X POST https://acme.kapable.ai/artifacts/palette-decision/v/1/verdict \
  -H "Content-Type: application/json" --cookie "$SESSION_COOKIE" \
  -d '{ "chosen": ["a"], "rationale": "Petrol reads calmer at scale" }'
# { "version": 1, "chosen": ["a"], "decided_by_id": "…", "decided_by_name": "Herman",
#   "decided_at": "…", "superseded_by": null, "warnings": [] }

# Read the verdict (agent keys allowed here):
curl -s https://api.kapable.ai/v1/artifacts/palette-decision/v/1/verdict \
  -H "x-api-key: $KAPABLE_ORG_KEY"

        Version metadata gains a decision field (the frozen ballot, null
        when none) and a has_verdict boolean (presence-signaling, mirrors
        has_audio). Once decided, every org viewer sees a verdict banner — the
        chosen label(s), the decider’s name, a mono timestamp, and the rationale if given
        — in its own deep, confident wash, distinct from the margin/audio
        palette; a superseded version’s banner additionally notes
        “superseded by v{n}”. On verdict write, the outcome travels: an
        artifact.decided herald event fires, a declared reply_to mailbox
        (if any) receives the decision through the same comms seam the steward uses, and a
        Knowledge Substrate claim is filed (subject = the decision question, claim = the chosen
        label + rationale, provenance = the ballot URL) — delivery failures on the latter two
        surface in the response’s warnings[], never blocking the write itself.
        Public shares and guest surfaces never show the Decide control or the verdict
        banner — deciding and its record stay org-internal in v1.

Not every choice needs a document

          A decision artifact is for choices worth a designed, durable record —
          candidates worth arguing side by side, a verdict worth citing later. A quick,
          low-stakes pick inside an agent session stays with the CLI’s
          AskUserQuestion; there is no named-decider assignment, no approval
          chain, no quorum, and no arbitrary form — options and an optional rationale,
          nothing else.

        Decision forms (M15) — the canonical ballot shape going forward is
        a fields[] form, not a single choice. Each field carries an id,
        a label, an optional required flag (default
        false), and a control — one of six kinds:
        pick-one, pick-many (optional min/max),
        per-item (rule each of an items[] list against shared
        choices[]), text, number, scale, and
        date. 1–12 fields, unique ids, labels required everywhere.

{ "slug": "q3-review", "title": "Q3 launch review", "kind": "decision", "html": "…",
  "decision": {
    "fields": [
      { "id": "ship", "label": "Ship in Q3?", "required": true,
        "control": { "kind": "pick-one",
          "options": [ { "id": "yes", "label": "Ship" }, { "id": "no", "label": "Hold" } ] } },
      { "id": "confidence", "label": "Confidence", "required": true,
        "control": { "kind": "scale", "min": 1, "max": 5, "min_label": "Low", "max_label": "High" } },
      { "id": "notes", "label": "Notes",
        "control": { "kind": "text", "multiline": true, "max_len": 2000 } }
    ]
  } }

Whole-form, fail-closed, per-field receipts (D47–D52)

          A form is validated fail-closed at publish and again at decide: a
          malformed ballot, or a verdict missing a required field or carrying a
          wrong-shaped answer, returns 422 with an offending[] list
          naming the exact field (fields[2].control.max_len,
          responses.confidence) so an agent self-fixes in one round-trip. The legacy
          {mode, options} ballot stays legal forever — the
          server normalizes it internally to a single required field with id choice,
          never rewriting your stored bytes. A verdict passes chosen for a legacy
          ballot and responses (a {field_id: value} map) for a form;
          pass the wrong one and the 422 tells you which the frozen ballot expects.

What a ballot may contain

        Every bound below is rejected at publish with a per-field receipt, so an agent can
        check a ballot against this table before spending a round-trip. The table is generated
        from the constants the server actually enforces — it cannot drift from them
        without failing the docs build.

Bound	Range	Notes

Fields per ballot	1–12	a form with 0 fields, or 13, is rejected at publish

Options per pick-one / pick-many	2–8	ids unique, labels required

per-item items	1–24	one row per item in the rendered document

per-item choices	2–8	the shared choice set every item is ruled against

text max_len	≤ 2000	the field’s own cap; omit for the default

scale span (max − min)	2–10	a 1–5 or 1–10 rating; wider spans are rejected

Verdict rationale	≤ 2000	optional free text submitted with the ruling

Option recommended_reason	≤ 280	characters (Unicode scalar values); the chip is one or two sentences, the full case goes in the document body

Enforced relationally, with the same per-field receipts:

pick-many: min ≤ max, and both ≤ the option count

number and scale: min < max

field ids unique within the ballot; option and item ids unique within their field

at most ONE option per field may set recommended, and only on pick-one / pick-many — a per-item field’s choices are shared across every item, so the mark is rejected there

recommended_reason requires recommended: a reason on an unmarked option is a 422, never a silent drop

Generated from kapable-artifacts/src/models.rs by
        scripts/gen-decide-bounds.mjs — edit the constants, not this table.

Recommending an option

        A ballot that lists options without arguing for one pushes the whole analytical burden
        onto the decider — who has less context than the author who just did the
        reading. An option may therefore carry recommended, an advisory
        mark, plus an optional recommended_reason of one or two sentences.

{ "fields": [{ "id": "palette", "label": "Which palette ships?", "required": true,
  "control": { "kind": "pick-one", "options": [
    { "id": "petrol", "label": "Petrol", "recommended": true,
      "recommended_reason": "This is what the code does today; ruling otherwise is a change order." },
    { "id": "porcelain", "label": "Porcelain" }
  ]}}]}

        The chrome renders it as a chip beside the option, with the reason as visible text rather
        than a hover tooltip — a decider who opens the control without reading the document
        still sees the argument. It never pre-selects. The control opens with
        nothing chosen, because a default selection would bias the ruling rather than inform it.

The rules, each a 422 with a per-field receipt naming the offending option:

Receipt	Cause	Fix

            decision.options.recommended
            two or more options in one field set recommended
            keep the mark on the single option you are arguing for

            decision.choice.recommended
            a per-item choice set the mark
            a per-item field’s choices are shared across every item, so one mark cannot say
              which item it recommends — argue it in the document body, or split the question
              into pick-one fields

            decision.option.recommended_reason
            a reason with no recommended, an empty reason, or one over the cap
            set recommended: true, or drop the reason; shorten to the cap in the
              table above

        Omit recommended rather than sending false. Both
        are accepted and both round-trip faithfully, but they are not the same ballot: settlement
        compares stored ballots with Postgres jsonb =, which is key-presence-sensitive,
        so a version published with false only auto-settles against another that also
        carries false. Absent is the canonical “no recommendation”, and every
        ballot published before this field existed keeps validating and rendering exactly as it always did.

        Authoring in markdown decide blocks? The mark is one optional continuation line
        under the option it belongs to — recommended: <why>, or a bare
        recommended for the mark with no reason:

```decide
id: palette
label: Which palette ships?
pick-one:
  - petrol: Petrol
    recommended: This is what the code does today; ruling otherwise is a change order.
  - porcelain: Porcelain
```

Carrying a ballot forward

        Republishing a decision artifact drops its ballot unless you say otherwise.
        The sentinel is explicit — the bare JSON string "carry" in the
        decision field — and it substitutes the newest version’s declared
        ballot byte-identically. Because the bytes match, carrying onto an already-decided slug
        auto-settles the new version with the borrowed verdict, so a restyle
        never re-asks a settled question.

{ "slug": "q3-review", "title": "Q3 launch review (restyled)", "kind": "decision",
  "html": "…", "decision": "carry" }

        Absence is never carry. Omitting decision on a
        decision-kind publish stays a 422, deliberately: absence-means-carry would
        turn a forgotten field into a silent republish of a stale question. The three receipts
        worth knowing before you hit them:

Receipt	Cause	Fix

            decision.carry.empty
            carry was requested, but no prior version of this slug ever declared a ballot
            declare the ballot in full on this version

            decision.carry.kind
            carry was requested on a non-decision kind
            publish kind: "decision", or declare the ballot in full

            decision.missing
            a decision-kind publish with no decision block at all
            pass a ballot, or "carry"

A ballot on a non-decision kind cannot survive a republish

          Publish accepts a decision block on any kind, but
          "carry" is refused on every kind except decision, and
          omitting the block on a report is perfectly legal. So a report that
          declares a ballot loses it on the next version with no error at any point,
          and the viewer resolves a ballot strictly from the version being viewed — leaving
          it reachable only at that version’s pinned /v/{n} URL. If a ballot
          must outlive its version, publish it as kind: "decision".

Verdict follow-through — the verdict may open the work

        A ballot may declare an optional follow_through block, frozen with the
        version alongside decision: {"kind": "board-story", "ref"?:
        "<kapable-board product_id>"}. In v1 there is exactly one target kind
        — a kapable-board story — and ref is an
        optional hint (a product id) to file it under; absent files with no product. A
        ballot with no follow_through is legal — a plaque is allowed, just
        never accidental.

{ "slug": "palette-decision", "title": "Which palette ships", "kind": "decision", "html": "…",
  "decision": {
    "mode": "pick-one",
    "options": [ { "id": "a", "label": "Petrol palette" }, { "id": "b", "label": "Porcelain palette" } ],
    "follow_through": { "kind": "board-story" }
  } }

        On decide, after herald/reply-to/Knowledge-Substrate delivery, the verdict opens the
        work: a board story is created via kapable-board’s own API, titled from the
        decision title and the chosen label, with the rationale and the ballot URL in its
        body. The created story’s URL is stored on the verdict as
        follow_up_ref and the chrome banner grows a small
        “→ follow-through” link. A failure to create the story
        — kapable-board unreachable, permission denied — is a
        warnings[] receipt, exactly like the reply-to/KS-claim legs; the verdict
        write itself is never blocked by it.

// GET …/verdict, once decided with a follow_through declared
{ "version": 1, "chosen": ["a"], "decided_by_id": "…", "decided_by_name": "Herman",
  "decided_at": "…", "superseded_by": null, "warnings": [],
  "follow_up_ref": "https://acme.kapable.ai/board/cards/…" }

Boundaries (v1)

          One target kind, board-story. No auto-assignment, no scheduling, no status
          sync-back — the created story lives its own life on the board from here on.

Panels — many respond, one decides

        A ballot may empanel respondents so the whole org weighs in before one member rules. Add
        a respondents block to the decision:
        { "mode": "panel", "who": "org", "blind": true } — the only v1 enums
        are mode: "panel" and who: "org" (any org member may respond);
        anything else is a 422 with receipts. blind defaults
        true — independence is the point of a panel. A response is the same
        form-shaped responses map a verdict uses, validated against the version's
        frozen ballot by the same machinery (D49), even a legacy ballot (which normalizes to its
        one choice field).

Method	Path	SDK (client.artifacts)

POST	/v1/artifacts/{slug}/v/{n}/responses	respond — member session only

GET	/v1/artifacts/{slug}/v/{n}/responses	getPanelResponses — members + agent keys

        curl
        TypeScript
        Rust

# Respond — member-cookie session only; an sk_org_ agent key → 403 (D64).
curl -s -X POST https://acme.kapable.ai/artifacts/q3-review/v/1/responses \
  -H "Content-Type: application/json" --cookie "$SESSION_COOKIE" \
  -d '{ "responses": { "ship": "yes", "confidence": 4 }, "rationale": "Runbook is ready" }'
# { "version": 1, "blind": true, "closed": false, "response_count": 3,
#   "own": { "member_name": "Herman", "responses": {…}, … } }
#   // responses[] is withheld while blind + open + you'd not yet voted; your own vote reveals it.

# Read the tally (agent keys allowed here) — honors the blind:
curl -s https://api.kapable.ai/v1/artifacts/q3-review/v/1/responses -H "x-api-key: $KAPABLE_ORG_KEY"

const panel = await client.artifacts.respond('q3-review', 1, {
  responses: { ship: 'yes', confidence: 4 },
  rationale: 'Runbook is ready',
});
// panel.response_count is always present; panel.responses appears once you've voted.
const tally = await client.artifacts.getPanelResponses('q3-review', 1);

use kapable_sdk::artifacts::PanelRespondRequest;
use serde_json::json;

let panel = client.artifacts().respond("q3-review", 1, PanelRespondRequest {
    responses: json!({ "ship": "yes", "confidence": 4 }),
    rationale: Some("Runbook is ready".into()),
}).await?;
let tally = client.artifacts().get_panel_responses("q3-review", 1).await?;

The blind, and closing the panel (D65/D66)

          response_count and your own vote are ALWAYS visible —
          the blind never hides either. The full responses[] record is served only
          when the panel is not blind, OR it is closed (a verdict exists), OR
          you have already submitted; while withheld it is absent (not null),
          so a client can test presence. The owner's verdict closes the panel
          (D66): a response after that is a 409 panel-closed, and a second response
          from the same member is a 409 (“a change of mind is a margin note,
          not an edit”). Responding to a version whose ballot did not empanel respondents is
          a 422.

The settled version

        Republish a decision version whose ballot is byte-identical to an
        earlier DECIDED version's, and the new version is settled, not open: version
        metadata carries a derived settled_by — the version number whose
        verdict already answers this ballot — computed at read time (D77), with nothing
        written on publish. The chrome shows that borrowed verdict, and the
        “Decide” control demotes to a quiet “re-rule” (the ruling already
        exists; deciding again is deliberate, never the default). Change the ballot in any byte
        and the new version is genuinely open — settled_by is
        null and it awaits its own verdict.

// GET …/v/2 (version meta) — v2 re-published v1's decided ballot unchanged:
{ "version": 2, "has_verdict": false, "settled_by": 1, … }
//  has_verdict:false WITH settled_by:1 is NOT an open question — the ruling lives on v1.

        The same rider rides the panel payload: GET …/responses returns
        settled_by when a version's empanelled ballot is settled by an earlier one
        — so an empty-looking panel here is a question resolved elsewhere, not an ignored
        one. Responding is still legal (it opens this version's own panel).

Constitutions — the law of language

        A constitution-kind artifact is a charter an org writes for itself —
        authorial context an agent reads before it works, the way it reads 02-TASTE. Every
        constitution declares a scope: a tier
        (master, topic, project, or person)
        and a lowercase key. Tiers are platform grammar; the key is org vocabulary
        (worldframe-legal, sarah). The master tier takes
        no key (a key there is a 422); every other tier requires one. There is
        one live charter per (tier, key) — publishing a second slug into a
        taken scope is a 409 naming the incumbent (amend that slug, or retract it
        first). A new version of an existing constitution must declare the same scope
        (422 otherwise); move a charter by retract-and-republish.

Method	Path	SDK (client.artifacts)

POST	/v1/artifacts (kind: constitution)	publish

GET	/v1/artifacts/constitution/stack?topic=&project=&person=	getConstitutionStack

        curl
        TypeScript
        Rust

# Resolve the charters applicable to a piece of work — each layer optional.
curl -s "https://api.kapable.ai/v1/artifacts/constitution/stack?topic=worldframe-legal&person=sarah" \
  -H "x-api-key: $KAPABLE_ORG_KEY"
# { "constitutions": [
#     { "slug": "org-charter", "tier": "master", "key": null, "version": 3, "title": "…", "html": "…" },
#     { "slug": "wf-legal",    "tier": "topic",  "key": "worldframe-legal", "version": 1, … } ],
#   "precedence": "Read these charters in order: master first, then topic, then project, then person. …",
#   "unmatched": [ { "tier": "person", "key": "sarah" } ] }   // 'sarah' has no live charter yet

const stack = await client.artifacts.getConstitutionStack({
  topic: 'worldframe-legal',
  person: 'sarah',
});
for (const c of stack.constitutions) applyCharter(c.html); // read every charter's html in full
// stack.unmatched names each provided scope with no live charter (a typo vs. "none yet").

use kapable_sdk::artifacts::ConstitutionStackQuery;

let stack = client.artifacts().get_constitution_stack(ConstitutionStackQuery {
    topic: Some("worldframe-legal".into()),
    person: Some("sarah".into()),
    ..Default::default()
}).await?;

Advisory, never enforcement (D69)

          A constitution shapes how agents write; it never validates a publish.
          Keys are lowercase-normalized before lookup, and every provided scope param
          that matched no live charter comes back verbatim in unmatched[] (always
          present, [] when everything matched) — so a caller can tell a typo'd
          key from “no charter for that scope yet.” An org with no constitutions
          returns constitutions: [], never a 404.

Receipts, not silent drops

        Every refusal on this surface names both the cause and the fix in the message itself
        — the reader of an error here is increasingly an agent that acts on exactly what the
        string says. List filters are strict, never lenient: an unknown kind, a
        discussions value other than active, or a retracted
        value other than 1 each return 422 naming the valid values
        (e.g. “discussions 'open' is not a filter — the only value is 'active'
        … omit it to list all”) rather than silently ignoring the typo and
        returning the wrong set. The free-text q searches literally
        — % and _ are escaped, so a query for 50%
        matches the text “50%”, not every row.

        Minting a share (or bundle) with an expires_at in the past is a
        400, not a link that is dead on arrival: “expires_at … is
        not in the future — a share minted already-expired is dead on arrival … pick
        a future expiry, or omit expires_at for a share that lives until revoked.” The
        pattern is uniform across the module: retraction 410s carry the tombstone facts, purge
        demands a prior retract, a mis-shaped decision form 422s per field, and a closed panel
        409s — a refusal is always a receipt, never a silent drop.

Org brand kit — the org’s name on the door

        An org may declare its taste as data: a palette/type token tree, an inline logo, a
        display name, and a short voice doctrine. The kit is a default, never a
        law — publish never validates a document against it, and there is no
        “off-brand” warning anywhere in this system, on any axis, ever. One
        mutable kit per org (a PUT replaces the whole thing); reach it via
        PUT/GET/DELETE /v1/artifacts/org/brand-kit.

{ "tokens": { "color": { "accent": { "$value": "#2E5C63" } } },
  "logo_svg": "<svg viewBox=\"0 0 120 32\">…</svg>",
  "display_name": "Geldentech",
  "voice": "Calm, precise, never chatty. No exclamation points.",
  "tts": { "voice_id": "abc123", "provider": "elevenlabs" } }

Method	Path	SDK (client.artifacts)

PUT	/v1/artifacts/org/brand-kit	setBrandKit — member sessions + sk_org_ write keys

GET	/v1/artifacts/org/brand-kit	getBrandKit — any read scope, 404 if unset

DELETE	/v1/artifacts/org/brand-kit	deleteBrandKit — member session only

        tokens is loosely DTCG-shaped and shape-checked only
        (every leaf lives in an object carrying $value) — the values
        themselves are never inspected or constrained. logo_svg is sanitized
        with the same self-containment law as documents (no scripts, no
        foreignObject, no external refs), plus its own 32 KiB cap; the
        whole kit is capped at 64 KiB total. tts (both fields required
        non-empty strings when present) is likewise shape-checked only — it is data for
        callers, never plumbing: the publish skill’s audio step uses
        kit.tts.voice_id as the default TTS voice when the author didn’t
        choose one (precedence: explicit caller voice > kit voice > the org’s
        org_tts_settings.default_voice_id > provider default).

        When a kit exists, the org-authenticated chrome bar and gallery render the logo,
        display name, and color.accent through a CSS-variable seam —
        margin/status washes and control geometry stay platform-fixed in every org. A
        missing or invalid kit silently falls back to the platform default; it is never an
        error surface. Public shares are completely unaffected.

        A share/bundle token also resolves under the org’s own subdomain
        ({org}.kapable.ai/a/{token}) — the identical sealed bytes as the
        kapable.ai/a/{token} apex form, same token, same CSP. The apex form
        keeps working forever; a share mint response returns both URLs. A token minted by
        one org 404s if opened under a different org’s subdomain.

The kit shapes taste, it never polices it

          The publish skill fetches the org’s kit and renders on-brand by default
          — but a subject that genuinely calls for a different treatment gets one,
          deliberately, without asking permission. There is no enforcement, linting, or
          off-brand signal anywhere in this system.

Skills

        Two Claude Code skills carry the doctrine so any agent works to taste:
        kapable-artifact-publish (loads the 02-TASTE design doctrine,
        writes a self-contained document, self-validates locally, publishes) and
        kapable-artifact-discuss (parses a copy-prompt block, judges
        alignment-question vs. defect, then replies + resolves aligned or republishes
        + resolves amended). See the Skills page.

Worked example

          The Kapable getting-started artifact, published through this exact flow and shared as a
          public capability link:
          open the shared render →

Next

Getting Started · Authentication

---

# Drops API

Source: https://docs.kapable.ai/drops
Section: Build

Drops API

        Zero-knowledge, burn-after-read secret sharing. Hand a credential, key, or sensitive
        string to a person or an agent once — without it living in a chat transcript, a
        log, or even the drop server's own database.

You need

Ciphertext to share. Create calls need a session or `sk_org_` key. Claim calls need the full URL fragment.

First call

curl -sS https://drop.kapable.ai/health

You should see a healthy response from the Drops host.

Base URL is drop.kapable.ai, not api.kapable.ai

          Drops run on their own host, https://drop.kapable.ai — the
          same host serves the API, the human claim page (/d/{id}), and the
          returned claim links. The SDK's client.drops targets it automatically; a
          raw caller uses that host directly.

The zero-knowledge model

        The creator encrypts the secret in their own process with AES-256-GCM
        under a random 32-byte key, and uploads only the ciphertext. The key never
        reaches the server. It rides the claim URL's #fragment:

https://drop.kapable.ai/d/<id>#<key-b64url>
                                        └────────┬────────┘
                    the fragment is never sent to the server — browsers and
                    HTTP clients keep everything after # local to the client

        Decryption happens on the claimer's side: in the browser via WebCrypto on the claim
        page, or via a bun -e one-liner for agents. The server stores ciphertext it
        genuinely cannot read, and a claim returns that same ciphertext for the claimer to
        decrypt with the fragment key.

Payload format

The wire contract, shared by the SDK, the claim page, and the raw recipe:

fragment key = base64url(32 raw key bytes)              // in the URL #hash
ct_b64       = base64( iv[12] || ciphertext || gcm_tag[16] )   // uploaded + returned

Endpoints

Method	Path	Auth	SDK (client.drops)

POST	/v1/drops	required	create

POST	/v1/drops/{id}/claim	public	claim

GET	/v1/drops/{id}/status	creator + org	status

GET	/d/{id}	public page	—

GET	/health	public	—

Create a drop

        Authenticated (any platform credential — a session token, or an sk_org_
        key). The body carries only ciphertext; the caller does the encryption. The response
        never contains the key.

# The SDK does the encryption for you; this is the raw wire shape.
curl -X POST https://drop.kapable.ai/v1/drops \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
        "ct_b64": "<base64(iv||ct||tag)>",
        "label": "prod db url",
        "ttl_secs": 259200,
        "max_claims": 1
      }'

# 200 OK
{
  "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "claim_url": "https://drop.kapable.ai/d/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "expires_at": "2026-07-21T15:44:42Z",
  "max_claims": 1
}

        Append #<key-b64url> to claim_url and share the whole
        link. Defaults: ttl_secs 259200 (72h, cap 604800 / 7 days),
        max_claims 1 (cap 10). Ciphertext is capped at 64 KiB — drops carry
        secrets, not files.

Claim a drop

        Public — no auth. Possession of the URL (id + fragment key) is the
        credential. The claim is atomic and burns the drop: on the final claim the ciphertext
        is destroyed in the same transaction. Rate-limited to 10/min per IP.

curl -X POST https://drop.kapable.ai/v1/drops/<id>/claim

# 200 OK — decrypt ct_b64 client-side with the fragment key
{ "ct_b64": "<base64(iv||ct||tag)>", "label": "prod db url", "claims": 1, "max_claims": 1 }

Check status (creator only)

        Authenticated, and scoped to the creating org. Returns state + receipts, never
        the ciphertext.

curl -H "Authorization: Bearer $TOKEN" \
  https://drop.kapable.ai/v1/drops/<id>/status

# 200 OK
{
  "state": "burned",            // unclaimed | claimed | expired | burned
  "claims": 1, "max_claims": 1,
  "created_at": "2026-07-18T15:45:18Z",
  "expires_at": "2026-07-21T15:45:18Z",
  "last_claimed_at": "2026-07-18T15:45:18Z",
  "claim_hint": "203.0.113.7"   // claimer IP hint (receipt only)
}

Burn & expiry semantics

Burn on explicit claim, never on GET. Opening
          /d/{id} (or a link-preview prefetching it) never consumes the drop — only
          POST …/claim does. Safe to paste into a chat that renders previews.

One-time by default. max_claims defaults to 1 (cap 10).
          On the final claim the ciphertext is NULLed; a tombstone row is kept ~30 days for
          receipts, then reaped.

Short-lived. ttl_secs defaults to 72h, capped at 7 days.
          An hourly reaper destroys the ciphertext of any expired-but-unclaimed drop.

Error strings are actionable

Errors use {error:{code,message,details}}. The message is the human line.

Code	What you see	What to do

410	already claimed at 2026-07-18T15:45:18Z — all 1 claim(s) used	Ask the sender to mint a new drop.

410	expired 2026-07-21T15:45:18Z — drops live at most 7 days	Ask the sender to mint a new drop.

404	no drop with that id	Ask the sender to mint a new drop.

422	ttl_secs 691200 exceeds the cap of 604800 (7 days)	Use a TTL of 604800 or less.

422	max_claims 11 exceeds the cap of 10	Use 10 or fewer claims.

429	too many claim attempts from your address	Wait 60 seconds and try again.

Claim without Kapable tooling

        Any box with curl + bun can claim a drop — no SDK, no login.
        This exact recipe is printed in the claim page footer:

URL='https://drop.kapable.ai/d/<id>#<key>' bun -e 'const u=new URL(process.env.URL),id=u.pathname.split("/").pop();let b=u.hash.slice(1).replace(/-/g,"+").replace(/_/g,"/");while(b.length%4)b+="=";const r=await fetch(u.origin+"/v1/drops/"+id+"/claim",{method:"POST"});if(!r.ok){console.error(await r.text());process.exit(1)}const{ct_b64}=await r.json();const raw=Uint8Array.from(atob(ct_b64),c=>c.charCodeAt(0)),iv=raw.slice(0,12),data=raw.slice(12),kr=Uint8Array.from(atob(b),c=>c.charCodeAt(0));const k=await crypto.subtle.importKey("raw",kr,"AES-GCM",false,["decrypt"]);const pt=await crypto.subtle.decrypt({name:"AES-GCM",iv},k,data);await Bun.write("secret.out",new Uint8Array(pt));console.error("wrote secret.out — chmod 600 secret.out")'

The plaintext lands in secret.out (never on your screen), and the drop is burned.

Security posture — what a server compromise leaks

        Because encryption is client-side and the key never touches the server, the drop server
        is a deliberately low-value target:

An attacker who fully owns the drop server / its DB / its logs gets…

Ciphertext (AES-256-GCM)	❌ useless without the key

The decryption key	✅ never stored, never logged, never in a request — not leaked

The plaintext secret	✅ not leaked

Label, claim counts, timestamps, claimer IP hint	⚠️ metadata — leaked (keep labels non-sensitive)

        The confidentiality boundary is the client-side key plus an unguessable 128-bit id — not
        tenant row-scoping, which is why the service deliberately runs without RLS and the claim
        route is public by design. The residual exposure is metadata: don't put the secret in the
        label. If a full link (including the #fragment) ever lands in a
        transcript or log, treat the secret as compromised and rotate it.

SDK Examples

        The SDK owns the crypto so callers can't get it wrong: create encrypts and
        returns the full claim URL with the fragment key already appended;
        claim fetches and decrypts to bytes.

        TypeScript
        Rust

// Create — the SDK encrypts client-side and returns the shareable URL (incl. #key)
const { id, claimUrl } = await client.drops.create({
  secret: 'sk_org_live_…the-credential…',
  label: 'onboarding key for Hardy',
  ttlSecs: 86_400,   // optional (default 72h, cap 7d)
  maxClaims: 1,      // optional (default 1, cap 10)
});
console.log(claimUrl); // https://drop.kapable.ai/d/# — share this once

// Claim — fetch + decrypt in one call (burns the drop)
const secret = await client.drops.claimText(claimUrl); // string
// or claim() for raw bytes: Uint8Array

// Status (creator only) — receipts, never the ciphertext
const s = await client.drops.status(id);
console.log(s.state); // 'burned'

// Create — encrypts client-side, returns the URL with the fragment key
let created = client.drops().create(&CreateDropRequest {
    secret: b"sk_org_live_…the-credential…".to_vec(),
    label: Some("onboarding key for Hardy".into()),
    ttl_secs: Some(86_400),
    max_claims: Some(1),
}).await?;
println!("{}", created.claim_url); // share once

// Claim — fetch + decrypt (burns the drop)
let bytes = client.drops().claim(&created.claim_url).await?;

// Status (creator only)
let s = client.drops().status(&created.id).await?;
assert_eq!(s.state, "burned");

        See also the Secrets API (secrets at rest) and the
        Skills page for the /drop Claude skill.

Next

Getting Started · Authentication

---

# API reference

Source: https://docs.kapable.ai/api
Section: API reference

API reference

Find a module and open its reference.

Board API

Stories, sprints, plans, products, and comments.

Store API

Object storage, buckets, and presigned uploads.

Kaps API

Routes for kaps, versions, triggers, and the per-kap database, files, and secrets.

Data API

Typed tables, row CRUD, bulk operations, and change streams.

Comms API

Agents, mailboxes, rooms, messaging, and email.

Knowledge API

Claims, predicates, perspectives, and provenance graphs.

AI API

Configure providers and proxy their native APIs.

Model Catalog

Browse model capabilities, pricing, and approved rosters.

Secrets API

Store and reference encrypted organization secrets.

Billing API

Organization billing, subscriptions, and checkout.

Wiki API

Markdown pages, collections, and AI-assisted authoring.

Harbor API

Distribute signed releases and validate software licenses.

Warrant API

Products, plans, licenses, and feature entitlements.

Teams

Manage team members, roles, and resource access.

---

# Board API

Source: https://docs.kapable.ai/board
Section: API reference

Board API

        Work tracking orchestration -- stories, sprints, plans, products, comments,
        and sprint closures. Full lifecycle management from backlog to release.

Stories

Stories are the core work item. Each story has a status, optional sprint attachment, and code identifier.

Method	Path	Description

            GET
            /v1/board/stories
            List stories with optional filters (status, sprint, search)

            POST
            /v1/board/stories
            Create a new story

            GET
            /v1/board/stories/{id_or_code}
            Get a story by UUID or code

            PATCH
            /v1/board/stories/{id_or_code}
            Update a story (partial update)

            DELETE
            /v1/board/stories/{id_or_code}
            Delete a story

            POST
            /v1/board/stories/{id_or_code}/transition
            Transition a story to a new status

SDK Examples

        TypeScript
        Rust

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

// Create a story
const story = await client.board.createStory({
  title: 'Implement user dashboard',
  description: 'Build the main dashboard view with metrics',
  status: 'backlog',
});

// Update a story
await client.board.updateStory('PROJ-42', {
  title: 'Updated title',
  description: 'Updated description',
});

// Transition to "in_progress"
const result = await client.board.transitionStory('PROJ-42', {
  to: 'in_progress',
});

// Delete a story
await client.board.deleteStory('PROJ-42');

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

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

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

let story = client.board().create_story(CreateStoryRequest {
    title: "Implement user dashboard".into(),
    description: Some("Build the main dashboard view with metrics".into()),
    status: Some("backlog".into()),
    ..Default::default()
}).await?;

client.board().update_story("PROJ-42", UpdateStoryRequest {
    title: Some("Updated title".into()),
    description: Some("Updated description".into()),
    ..Default::default()
}).await?;

client.board().transition_story("PROJ-42", TransitionRequest {
    to: "in_progress".into(),
}).await?;

client.board().delete_story("PROJ-42").await?;

Sprints

        Sprints group stories into time-boxed iterations. A sprint progresses
        through planned → active → completed states.

Method	Path	Description

            GET
            /v1/board/sprints
            List sprints with optional filters

            POST
            /v1/board/sprints
            Create a sprint

            GET
            /v1/board/sprints/{id_or_code}
            Get a sprint (includes attached stories)

            POST
            /v1/board/sprints/{id_or_code}/start
            Start a planned sprint

            POST
            /v1/board/sprints/{id_or_code}/complete
            Complete an active sprint

            POST
            /v1/board/sprints/{id_or_code}/stories
            Attach a story to a sprint

            DELETE
            /v1/board/sprints/{id_or_code}/stories/{story_id}
            Detach a story from a sprint

SDK Examples

        TypeScript
        Rust

// Create a sprint
const sprint = await client.board.createSprint({
  name: 'Sprint 12',
  goal: 'Ship user dashboard',
  starts_at: '2026-05-20T00:00:00Z',
  ends_at: '2026-06-03T00:00:00Z',
});

// Start the sprint
await client.board.startSprint(sprint.id);

// Attach a story
await client.board.attachStory(sprint.id, {
  story_id: storyId,
});

// Complete the sprint
await client.board.completeSprint(sprint.id);

// Rust SDK
let sprint = client.board().create_sprint(CreateSprintRequest {
    name: "Sprint 12".into(),
    goal: Some("Ship user dashboard".into()),
    starts_at: Some("2026-05-20T00:00:00Z".into()),
    ends_at: Some("2026-06-03T00:00:00Z".into()),
    ..Default::default()
}).await?;

client.board().start_sprint(&sprint.id.to_string()).await?;

client.board().attach_story(&sprint.id.to_string(), AttachStoryRequest {
    story_id: story_id,
}).await?;

client.board().complete_sprint(&sprint.id.to_string()).await?;

Sprint Closures

Closures capture retrospectives and release notes when a sprint completes.

Method	Path	Description

            GET
            /v1/board/sprints/{id_or_code}/closure
            Get closure for a sprint

            POST
            /v1/board/sprints/{id_or_code}/closure
            Create or update a sprint closure

SDK Examples

        TypeScript
        Rust

// Upsert a sprint closure
const closure = await client.board.upsertClosure('sprint-12', {
  retro: 'Good velocity, need better estimation',
  release_notes: '## Dashboard v1\n- User metrics\n- Activity feed',
});

// Read it back
const existing = await client.board.getClosure('sprint-12');

// Rust SDK
let closure = client.board().upsert_closure("sprint-12", UpsertClosureRequest {
    retro: Some("Good velocity, need better estimation".into()),
    release_notes: Some("## Dashboard v1\n- User metrics\n- Activity feed".into()),
    ..Default::default()
}).await?;

let existing = client.board().get_closure("sprint-12").await?;

Plans

Plans are versioned documents (roadmaps, specs, designs) with revision history.

Method	Path	Description

            GET
            /v1/board/plans
            List plans

            POST
            /v1/board/plans
            Create a plan

            GET
            /v1/board/plans/{id_or_code}
            Get a plan by UUID or code

            PATCH
            /v1/board/plans/{id_or_code}
            Update a plan

            GET
            /v1/board/plans/{id_or_code}/revisions
            List revisions for a plan

            POST
            /v1/board/plans/{id_or_code}/revisions
            Create a new revision

SDK Examples

        TypeScript
        Rust

// Create a plan with initial content
const plan = await client.board.createPlan({
  title: 'Q3 Roadmap',
  body: '## Goals\n- Launch v2\n- Onboard 10 customers',
});

// Create a revision when updating
await client.board.createRevision(plan.id, {
  body: '## Goals (revised)\n- Launch v2.1\n- Onboard 20 customers',
  summary: 'Revised targets after board review',
});

// Rust SDK
let plan = client.board().create_plan(CreatePlanRequest {
    title: "Q3 Roadmap".into(),
    body: Some("## Goals\n- Launch v2\n- Onboard 10 customers".into()),
    ..Default::default()
}).await?;

client.board().create_revision(&plan.id.to_string(), CreateRevisionRequest {
    body: "## Goals (revised)\n- Launch v2.1\n- Onboard 20 customers".into(),
    summary: Some("Revised targets after board review".into()),
}).await?;

Products

Products represent logical product lines or applications that stories and plans belong to.

Method	Path	Description

            GET
            /v1/board/products
            List all products for the org

            POST
            /v1/board/products
            Create a product

            GET
            /v1/board/products/{slug}
            Get a product by slug or UUID

            PATCH
            /v1/board/products/{slug}
            Update a product

SDK Examples

        TypeScript
        Rust

// Create a product
const product = await client.board.createProduct({
  name: 'Dashboard',
  slug: 'dashboard',
  description: 'Internal analytics dashboard',
});

// List all products
const { data: products } = await client.board.listProducts();

// Rust SDK
let product = client.board().create_product(CreateProductRequest {
    name: "Dashboard".into(),
    slug: "dashboard".into(),
    description: Some("Internal analytics dashboard".into()),
}).await?;

let products = client.board().list_products().await?;

Comments

Comments can be attached to any target (story, sprint, plan) via a target_type and target_id.

Method	Path	Description

            GET
            /v1/board/comments
            List comments (filter by target_type + target_id)

            POST
            /v1/board/comments
            Create a comment

            PUT
            /v1/board/comments/{id}
            Update a comment

            DELETE
            /v1/board/comments/{id}
            Delete a comment

SDK Examples

        TypeScript
        Rust

// Add a comment to a story
const comment = await client.board.createComment({
  target_type: 'story',
  target_id: storyId,
  body: 'Ready for review',
});

// List comments for a story
const { data: comments } = await client.board.listComments({
  target_type: 'story',
  target_id: storyId,
});

// Update a comment
await client.board.updateComment(comment.id, {
  body: 'Approved and merged',
});

// Rust SDK
let comment = client.board().create_comment(CreateCommentRequest {
    target_type: "story".into(),
    target_id: story_id,
    body: "Ready for review".into(),
}).await?;

let comments = client.board().list_comments(ListCommentsQuery {
    target_type: Some("story".into()),
    target_id: Some(story_id),
    ..Default::default()
}).await?;

client.board().update_comment(comment.id, UpdateCommentRequest {
    body: "Approved and merged".into(),
}).await?;

Next

Getting Started · Authentication

---

# Store API

Source: https://docs.kapable.ai/store
Section: API reference

Store API

        S3-backed object storage with org-scoped buckets, presigned URLs for
        direct browser uploads, and cursor-based pagination.

Buckets

        Buckets are org-scoped containers. Each org can create multiple buckets to
        organize objects by purpose (uploads, avatars, exports, etc.).

Method	Path	Description

            GET
            /v1/buckets
            List all buckets for the org

            POST
            /v1/buckets
            Create a new bucket

SDK Examples

        TypeScript
        Rust

// List buckets
const buckets = await client.store.listBuckets();

// Create a bucket
const { bucket, created } = await client.store.createBucket({
  name: 'user-uploads',
});

// Rust SDK
use kapable_sdk::store::types::*;

let buckets = client.store().list_buckets().await?;

let resp = client.store().create_bucket(CreateBucketRequest {
    name: "user-uploads".into(),
}).await?;

Objects

        Objects are files stored in buckets. Upload, download, list, delete, and
        inspect objects via the Objects endpoints.

Method	Path	Description

            GET
            /v1/objects/{bucket}
            List objects in a bucket (prefix filter, cursor pagination)

            PUT
            /v1/objects/{bucket}/{key}
            Upload an object (raw bytes body)

            GET
            /v1/objects/{bucket}/{key}
            Download an object

            DELETE
            /v1/objects/{bucket}/{key}
            Delete an object

            HEAD
            /v1/objects/{bucket}/{key}
            Get object metadata (size, content-type, etag)

SDK Examples

        TypeScript
        Rust

// Upload a file
const data = new TextEncoder().encode('Hello, world!');
const uploaded = await client.store.uploadObject(
  'user-uploads',
  'docs/readme.txt',
  data,
  'text/plain',
);
console.log(`Uploaded: ${uploaded.key}, size: ${uploaded.size}`);

// Download a file
const response = await client.store.downloadObject(
  'user-uploads',
  'docs/readme.txt',
);
const text = await response.text();

// List objects with prefix
const listing = await client.store.listObjects('user-uploads', {
  prefix: 'docs/',
  max_keys: 100,
});

// Auto-paginate through all objects
for await (const obj of client.store.paginateObjects('user-uploads')) {
  console.log(obj.key, obj.size);
}

// Delete an object
await client.store.deleteObject('user-uploads', 'docs/readme.txt');

// Rust SDK
let data = b"Hello, world!".to_vec();
let uploaded = client.store().upload_object(
    "user-uploads", "docs/readme.txt", data, Some("text/plain"),
).await?;

let bytes = client.store().download_object(
    "user-uploads", "docs/readme.txt",
).await?;

let listing = client.store().list_objects("user-uploads", ListObjectsParams {
    prefix: Some("docs/".into()),
    max_keys: Some(100),
    ..Default::default()
}).await?;

Presigned URLs

        Generate presigned S3 URLs for direct browser uploads and downloads.
        This avoids proxying large files through the API server.

Method	Path	Description

            POST
            /v1/presign/{bucket}/{key}
            Generate a presigned upload URL

            GET
            /v1/presign/{bucket}/{key}
            Generate a presigned download URL

SDK Examples

// Get a presigned upload URL (browser can PUT directly to S3)
const { url, expires_at } = await client.store.presignUpload(
  'user-uploads',
  'photos/avatar.jpg',
  { expires_in: 3600 }, // 1 hour
);

// Browser-side upload using the presigned URL
await fetch(url, {
  method: 'PUT',
  body: fileBlob,
  headers: { 'Content-Type': 'image/jpeg' },
});

// Get a presigned download URL
const download = await client.store.presignDownload(
  'user-uploads',
  'photos/avatar.jpg',
);
// Redirect user to download.url

External vs Internal S3 Endpoint

          The store service uses a separate S3 client for presigning that targets
          the external endpoint (S3_EXTERNAL_ENDPOINT). This ensures
          the presigned URL's signature matches the host the browser will connect to.

Next

Getting Started · Authentication

---

# Kaps API

Source: https://docs.kapable.ai/kaps-api
Section: API reference

Kaps API

        The route reference for kaps: create and save kaps, manage versions,
        triggers, tokens and audience, and read and write a kap's database,
        file store and secrets. For the guide, see Kaps.

Authentication

          Base URL: https://{org}.kapable.ai/v1/orgs/{org_id}. Authenticate
          with X-Session-Token: kses_…, Authorization: Bearer kses_…,
          or a platform session cookie. Every change (anything that is not a
          GET) requires X-Kapable-Client: <name> (1–128 bytes).
          Cookie-authenticated changes also require
          Origin: https://<actual-host>. Send
          Content-Type: application/json; bodies are capped at 2 MiB.
          Errors come back as {error:{code,message,details}} with a human
          message.

Kaps, files and versions

All paths below are relative to /v1/orgs/{org_id}.

Method	Path	Body / result

            POST
            /kaps
            {name,main_file,files:[{path,content}],audience?:"members"} → 201 {kap,version,address,bypass_token}. The token is shown once.

            GET
            /kaps
            {kaps:[...]} — the active list.

            GET
            /kaps/{id}
            {kap,files,version,triggers} for the current snapshot.

            PUT
            /kaps/{id}/files
            {base_version_id,main_file?,files:[{path,content}]} → {version}. A save replaces the whole file set; a stale base gets 409 VERSION_CONFLICT.

            GET
            /kaps/{id}/versions
            {versions:[...]}, newest sequence first, complete snapshots.

            GET
            /kaps/{id}/versions/{version_id}
            {version}.

            POST
            /kaps/{id}/versions/{version_id}/restore
            {base_version_id} → a new {version} with restored_from. Restoring never deletes earlier versions.

            GET
            /kaps/{id}/diff?from={uuid}&to={uuid}
            {from,to,main_file:{before,after},files:[{path,kind,before,after}]}.

            GET
            /kaps/{id}/history
            {events:[...]} in event sequence order, including deletion and recovery.

            DELETE
            /kaps/{id}
            {kap} with deleted_at and recover_until. Deletion stops the runtime and enters recovery.

            GET
            /recovery
            {kaps:[...]} — deleted kaps, including expired deadlines.

            POST
            /kaps/{id}/recover
            No body → {kap} restored with the same versions, files and token states.

Example: create a kap

curl -X POST https://acme.kapable.ai/v1/orgs/$ORG_ID/kaps \
  -H "X-Session-Token: kses_..." \
  -H "X-Kapable-Client: my-script" \
  -H "Content-Type: application/json" \
  -d '{"name":"hello","main_file":"main.ts","files":[{"path":"main.ts","content":"export default (request: Request): Response => new Response('"'"'Hello'"'"')"}]}'

        The create JSON can contain any files you like; the new kap is born with
        an enabled request trigger and one machine token named default.

Machine tokens and endpoint secrets

Paths relative to /v1/orgs/{org_id}.

Method	Path	Body / result

            GET
            /kaps/{id}/bypass-tokens
            {tokens:[{id,name,created_at,revoked_at}]} — metadata only; the bearer value is never listed.

            POST
            /kaps/{id}/bypass-tokens
            {name} → 201 {bypass_token:{...,token}}, shown once.

            DELETE
            /kaps/{id}/bypass-tokens/{token_id}
            Revoke durably → {bypass_token} metadata.

            GET
            /kaps/{id}/endpoint-secrets
            Live and revoked secrets, the address template and the scheme. The address carries a {secret} placeholder, never a value.

            POST
            /kaps/{id}/endpoint-secrets
            {name} → 201 with the secret under shown_once and nowhere else.

            DELETE
            /kaps/{id}/endpoint-secrets/{secret_id}
            Revoke; both doors refuse it on the next request.

        Machines call a kap with Authorization: Bearer kbt_… (a bypass
        token). Outside webhook senders that cannot hold a token use an endpoint
        secret: either the secret address
        https://{kap}.{org}.kapable.run/__kaps/e/{secret} or a signed
        request with X-Kaps-Signature: t=<unix seconds>,v1=<lowercase hex
        HMAC-SHA256>, where the signed message is
        kaps-endpoint-v1\nMETHOD\nTARGET\nt\nbody (method, path with query,
        timestamp, then the exact body bytes). Requests more than 300 seconds
        from the service clock are refused as stale.

Audience

Method	Path	Body / result

            GET
            /v1/orgs/{org}/kaps/{kap}/audience
            {policy:{audience,invited,revision},events:[...]} — audience history only.

            PUT
            /v1/orgs/{org}/kaps/{kap}/audience
            Full policy replacement with its displayed revision, e.g. {"audience":"invited","invited":["person@corp.example","@corp.example"],"base_revision":0} → {policy,changed:true}. Widening needs a member; going public additionally needs confirm_public:true. A stale write gets 409 AUDIENCE_CONFLICT.

Triggers

        The request trigger's switch is part of the core table (paths relative to
        /v1/orgs/{org_id}); schedule and inbox triggers and their runs live under
        /v1/orgs/{org}/kaps/{kap}.

Method	Path	Body / result

            GET
            /kaps/{id}/triggers
            {triggers:[...]}.

            PUT
            /kaps/{id}/triggers/{trigger_id}
            {kind:"request",file_path:<main>,enabled} → {trigger}; pausing and resuming are attributed.

            GET
            /triggers
            Trigger metadata, the kap's mail address, and deployment limits.

            POST
            /triggers
            {kind:"schedule",file_path,interval_seconds} or {kind:"schedule",file_path,cron} → 201 {trigger}.

            POST
            /triggers
            {kind:"inbox",file_path} → 201 {trigger}.

            POST
            /triggers/{id}/pause or /resume
            No body; attributed change.

            DELETE
            /triggers/{id}
            No body; removes the attachment, keeps run receipts.

            POST
            /triggers/{id}/run-now
            No body; {run}, including a missed or failed reason.

            GET
            /trigger-runs?before={run_id}
            Up to 100 newest rows with has_more and next_cursor.

            GET
            /trigger-runs/{id}
            The run plus its retained parsed payload, or an explicit expiry notice.

            POST
            /trigger-runs/{id}/acknowledge
            No body; attributed acknowledgement of a failure.

        Schedule cron has five numeric UTC fields with lists, ranges and positive
        steps; the default shortest cadence is 15 minutes. A kap's inbox address
        is {kap}@{org}.kapable.email; incoming messages are capped at
        30 MiB and rate-limited per kap per hour.

Runs, logs, and switching a kap off

Method	Path	Body / result

            GET
            /v1/orgs/{org}/kaps/{kap}/runs?limit={n}&cursor={c}&failed_since={t}
            Newest first; runs, next_cursor, has_more, status, message. 20 by default, 100 at most; failed_since is an RFC 3339 instant narrowing to failed runs. Every row carries a plain-words outcome (outcome, what_to_do) and the raw detail behind it.

            GET
            /v1/kaps/{id}/log?after=<opaque-cursor>
            Up to 200 retained console/trace rows with lines, next_cursor, has_more, status, and a human message.

            POST
            /v1/orgs/{org}/kaps/{kap}/disable
            {"reason":"..."} (required) — the kap serves nothing, runs no schedule and accepts no email; every refusal names who switched it off, when, and the reason. Switch it back on with POST .../enable.

            GET
            /v1/orgs/{org}/usage
            What the organisation consumed, per kap, per day, for the last 30 days. A measure, not a ceiling: "enforced": false.

Per-kap database, files and secrets

        Every kap gets its own PostgreSQL schema, file store and secret set. The
        same routes accept two bases: /v1/orgs/{org_id}/kaps/{kap_id}, or
        /v1/kaps/{kap_id} (the organisation comes from the authenticated
        member). The second base also accepts the kap's kst1_ store
        capability token, but only for /db/... and /store/....

Method	Path	Body / result

            POST
            /db/query
            {sql,params?:[]} → {rows:[],row_count}. One PostgreSQL statement.

            GET
            /db/tables
            {tables:[{name,columns:[{name,type,nullable,default}]}]}.

            GET
            /db/tables/{table}/rows
            {rows:[],row_count} — the complete result, or a named refusal.

            POST
            /db/tables/{table}/rows
            An object of column values → 201 {rows:[inserted],row_count:1}. Defaults apply to omitted columns.

            GET
            /db/tables/{table}/rows/{key}
            One row, selected by the table's single-column primary key.

            PUT
            /db/tables/{table}/rows/{key}
            An object of changed columns; explicit null stays null.

            DELETE
            /db/tables/{table}/rows/{key}
            No body → the deleted row; an absent key gives 404.

            GET
            /db/export
            A PostgreSQL SQL dump, application/sql, attachment store.sql.

            GET
            /store/files
            {files:[{key,size,last_modified,etag}]}; all pages are followed for you.

            PUT
            /store/files/object?key={encoded_key}
            Raw body and Content-Type → {stored:true,key}.

            GET
            /store/files/object?key={encoded_key}
            Raw bytes, preserved Content-Type, attachment disposition.

            DELETE
            /store/files/object?key={encoded_key}
            No body → {deleted:true,key}.

            GET
            /store/files/export
            A tar stream, attachment files.tar.

            GET
            /secrets
            {secrets:[{name,group_id,group_name}],refresh_pending} — names only, never values.

            PUT
            /secrets/{NAME}
            {value:string} → {name,set:true,refresh_pending:false}. The value is never returned.

            DELETE
            /secrets/{NAME}
            No body → {name,deleted:true,refresh_pending:false}.

            GET
            /secret-groups
            The attached {groups:[{id,name}]}.

            PUT
            /secret-groups/{group_id}
            No body → {attached:true} after the current-version refresh.

            DELETE
            /secret-groups/{group_id}
            No body → {detached:true} after the refresh.

            GET
            /export/manifest
            {format,kap,versions,secret_names,store:{sql,files}} with links to the separate store downloads.

Example: query a kap's database

curl -X POST https://acme.kapable.ai/v1/kaps/$KAP_ID/db/query \
  -H "X-Session-Token: kses_..." \
  -H "X-Kapable-Client: my-script" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT id, body FROM notes WHERE id = $1","params":[1]}'
# → {"rows":[{"id":1,"body":"hello"}],"row_count":1}

SQL notes

          Parameters support null, bool, int2/4/8, float4/8, text/varchar/name,
          UUID and JSON/JSONB, matched to the prepared statement's expected
          type. Cast anything else through text, e.g. $1::text::numeric.
          Results additionally support date/timestamp and bytea (base64url).
          Duplicate result column names are refused; use aliases. Tables without
          a single-column primary key need /db/query for row changes.

Organisation secret groups

        A secret group is a set of secrets shared with every kap attached to it.
        Base: /v1/orgs/{org_id}/secret-groups.

Method	Path	Body / result

            GET
            /v1/orgs/{org_id}/secret-groups
            {groups:[{id,name}]}.

            POST
            /v1/orgs/{org_id}/secret-groups
            {name} → 201 {group:{id,name}}; a group can exist before the first kap.

            GET
            /{group_id}/secrets
            Names and their group origin only.

            PUT
            /{group_id}/secrets/{NAME}
            {value} → name/set receipt; refreshes every attached active kap.

            DELETE
            /{group_id}/secrets/{NAME}
            No body → name/deleted receipt; refreshes every attached active kap.

            GET
            /{group_id}/history
            Attributed metadata events; no values.

Secret names

          Secret names are uppercase ASCII environment identifiers starting with
          a letter, at most 128 bytes. Runtime names (PATH, HOME,
          DENO_*, NODE_* and friends) and KAP_* are reserved.
          Effective names must be unique across the kap and every attached
          group; a conflict is refused with 409 SECRET_NAME_CONFLICT and
          the whole change is left unapplied.

Next

Kaps guide · Authentication

---

# Data API

Source: https://docs.kapable.ai/data
Section: API reference

Data API

        Typed-table CRUD service with dynamic row schemas, full-text search,
        bulk operations, CSV import/export, and real-time SSE change streams.

✅ Self-service ready (2026-06-10)

          The Data API is fully reachable with a plain sk_live_ API key —
          no extra setup. Every org gets a default project (a private
          Postgres schema) at signup, and data requests resolve it automatically.
          API keys are scope-gated: read covers
          GET/list/SSE, write covers row mutations and table DDL.

Quickstart

Four calls from zero to live data — no headers beyond the key:

# 1. Sign up (returns a session token; org_slug is required)
curl -X POST https://api.kapable.ai/v1/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"...","org_name":"Acme","org_slug":"acme"}'

# 2. Mint an API key (secret is shown ONCE)
curl -X POST https://api.kapable.ai/v1/auth/api-keys \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"my-key"}'

# 3. Create a table (default project resolved server-side)
curl -X POST https://api.kapable.ai/v1/tables \
  -H "x-api-key: $SK_LIVE_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"todos","columns":[{"name":"title","col_type":"text"},{"name":"done","col_type":"boolean"}]}'

# 4. CRUD rows
curl -X POST https://api.kapable.ai/v1/todos -H "x-api-key: $SK_LIVE_KEY" \
  -H 'Content-Type: application/json' -d '{"title":"first","done":false}'
curl https://api.kapable.ai/v1/todos -H "x-api-key: $SK_LIVE_KEY"

Or with the SDK (@kapable/sdk ≥ 0.3.0):

const client = new KapableClient({ baseUrl: 'https://api.kapable.ai', apiKey: 'sk_live_…' });
await client.data.createTable({ name: 'todos', columns: [{ name: 'title', col_type: 'text' }] });
await client.data.createRows('todos', { title: 'first' });
const rows = await client.data.listRows('todos');

        Errors use {error:{code,message,details}}. The
        message field tells you what to fix.

Code	What you see	What to do

FORBIDDEN	key lacks the write scope	Use a key with write for table or row changes.

NOT_FOUND	table not found	Create the table before you query it.

400	reserved table name	Choose a name other than tables, projects, or _meta.

Projects & request resolution

        A project is a private Postgres schema your tables live in.
        Signup seeds a default project (slug default). Each data request
        resolves its project in this order:

an explicit X-Project-Id header (must belong to your org);

the project the API key is bound to (mint with
          {"project_id": "…"} — the key dies with the project);

your org's default project.

        Discover project ids with GET /v1/projects (works with keys and
        sessions; SDK: client.projects.list()). Create/delete projects from
        an org-member session (client.projects.create({name}) /
        client.projects.delete(id) — delete requires ?confirm=true
        and drops the schema irreversibly).

Tables

        Tables define the schema for your data. Each table has typed columns
        that are enforced on write. Schemas can be migrated (add/drop columns)
        without downtime.

Method	Path	Description

            GET
            /v1/tables
            List all tables for the org

            POST
            /v1/tables
            Create a new table with column definitions

            DELETE
            /v1/tables/{table}
            Drop a table and all its data

            POST
            /v1/tables/{table}/migrate
            Migrate schema (add/drop columns)

SDK Examples

        TypeScript
        Rust

// Create a table. Field is `col_type` (not `type`); the live API expects
// LOWERCASE values: text, integer, big_int, float, boolean, timestamp, uuid, json.
// (The SDK's published ColumnType union is PascalCase and is being corrected —
//  until then, pass the lowercase string.)
const table = await client.data.createTable({
  name: 'contacts',
  columns: [
    { name: 'email', col_type: 'text', nullable: false, unique: true },
    { name: 'name', col_type: 'text' },
    { name: 'age', col_type: 'integer' },
    { name: 'active', col_type: 'boolean', default_value: true },
  ],
});

// List tables
const { data: tables } = await client.data.listTables();

// Add a column
await client.data.migrateTable('contacts', {
  add: [{ name: 'company', type: 'text' }],
});

// Drop a table
await client.data.dropTable('contacts');

// Rust SDK
use kapable_sdk::data::types::*;

let table = client.data().create_table(&CreateTableRequest {
    name: "contacts".into(),
    columns: vec![
        ColumnDef { name: "email".into(), col_type: "text".into(), required: Some(true), default: None },
        ColumnDef { name: "name".into(), col_type: "text".into(), required: None, default: None },
        ColumnDef { name: "age".into(), col_type: "integer".into(), required: None, default: None },
    ],
}).await?;

let tables = client.data().list_tables().await?;

client.data().migrate_table("contacts", &MigrateTableRequest {
    add: Some(vec![ColumnDef { name: "company".into(), col_type: "text".into(), required: None, default: None }]),
    drop: None,
}).await?;

client.data().drop_table("contacts").await?;

Row CRUD

        Rows are dynamic JSON objects whose shape matches the table schema.
        The Data service validates column types on write and returns errors
        for type mismatches.

Method	Path	Description

            GET
            /v1/{table}
            List rows with pagination and filters

            POST
            /v1/{table}
            Create one or more rows

            GET
            /v1/{table}/{id}
            Get a single row by UUID

            PUT
            /v1/{table}/{id}
            Replace a row (full update)

            PATCH
            /v1/{table}/{id}
            Patch a row (partial update)

            DELETE
            /v1/{table}/{id}
            Delete a row

            POST
            /v1/{table}/search
            Full-text search across all text columns

SDK Examples

        TypeScript
        Rust

// Create a single row
const row = await client.data.createRows('contacts', {
  email: 'alice@example.com',
  name: 'Alice',
  age: 30,
});

// Create multiple rows (batch)
const rows = await client.data.createRows('contacts', [
  { email: 'bob@example.com', name: 'Bob', age: 25 },
  { email: 'carol@example.com', name: 'Carol', age: 35 },
]);

// List with pagination
const { data, total } = await client.data.listRows('contacts', {
  limit: 20,
  offset: 0,
  sort: 'name',
  order: 'asc',
});

// Get a single row
const contact = await client.data.getRow('contacts', rowId);

// Patch a row (partial update)
await client.data.patchRow('contacts', rowId, {
  name: 'Alice Updated',
});

// Full-text search
const results = await client.data.searchRows('contacts', {
  query: 'alice',
  limit: 10,
});

// Auto-paginate
for await (const row of client.data.paginateRows('contacts')) {
  console.log(row.email, row.name);
}

// Rust SDK
use serde_json::json;

let row = client.data().create_rows("contacts", &json!({
    "email": "alice@example.com",
    "name": "Alice",
    "age": 30
})).await?;

let result = client.data().list_rows("contacts", &DataListParams {
    limit: Some(20),
    offset: Some(0),
    sort: Some("name".into()),
    order: Some("asc".into()),
    ..Default::default()
}).await?;

let contact = client.data().get_row("contacts", row_id).await?;

client.data().patch_row("contacts", row_id, &json!({
    "name": "Alice Updated"
})).await?;

let search = client.data().search_rows("contacts", &SearchRowsRequest {
    query: "alice".into(),
    limit: Some(10),
    ..Default::default()
}).await?;

Bulk Operations

        Bulk endpoints accept arrays of IDs or objects and operate in a single
        database transaction for consistency.

Method	Path	Description

            POST
            /v1/{table}/bulk/update
            Update multiple rows by ID

            POST
            /v1/{table}/bulk/delete
            Delete multiple rows by ID

            POST
            /v1/{table}/import
            Import rows from CSV

            POST
            /v1/{table}/export
            Export all rows as JSON (max 10,000)

SDK Examples

        TypeScript
        Rust

// Bulk update
await client.data.bulkUpdate('contacts', {
  rows: [
    { id: 'uuid-1', data: { active: false } },
    { id: 'uuid-2', data: { active: false } },
  ],
});

// Bulk delete
await client.data.bulkDelete('contacts', {
  ids: ['uuid-1', 'uuid-2', 'uuid-3'],
});

// CSV import
const csv = `email,name,age
dave@example.com,Dave,40
eve@example.com,Eve,28`;
const imported = await client.data.importCsv('contacts', csv);

// Export all rows as JSON
const allRows = await client.data.exportData('contacts');

// Rust SDK
client.data().bulk_update("contacts", &BulkUpdateRequest {
    rows: vec![
        BulkUpdateRow { id: uuid1, data: json!({"active": false}) },
        BulkUpdateRow { id: uuid2, data: json!({"active": false}) },
    ],
}).await?;

client.data().bulk_delete("contacts", &BulkDeleteRequest {
    ids: vec![uuid1, uuid2, uuid3],
}).await?;

Atomic Batch

        POST /v1/_batch executes an ordered list of
        insert/update/patch/delete operations, across any tables in the
        project schema, in a SINGLE database transaction. All ops succeed, or
        none do -- a mid-batch failure rolls back everything already written
        and returns one typed error naming the failing op's zero-based index.
        Use this whenever a write has a multi-row invariant (e.g. an invoice
        header plus its line items) that must never be observed half-written.

        Op semantics mirror the single-row endpoints exactly: same
        validation, same coercion, same system-column rejection, same
        null-skip behavior on patch. The one addition specific
        to batch: insert may carry a client-supplied
        id, so a later op in the same batch can reference a row
        written earlier (e.g. a line item referencing its header's id) --
        there is no $ref templating, just an explicit id you
        already chose. Capped at 100 ops per request; an empty batch is a 400.

Method	Path	Description

            POST
            /v1/_batch
            Execute an ordered list of write ops in one transaction

SDK Examples

        TypeScript
        Rust

// Header + two lines in one all-or-nothing transaction. The header's id is
// client-supplied so the line ops can reference it.
const headerId = crypto.randomUUID();
const result = await client.data.batch({
  ops: [
    { op: 'insert', table: 'invoices', id: headerId, data: { total: 250 } },
    { op: 'insert', table: 'invoice_lines', data: { invoice_id: headerId, amount: 100 } },
    { op: 'insert', table: 'invoice_lines', data: { invoice_id: headerId, amount: 150 } },
    { op: 'patch', table: 'invoices', id: headerId, data: { status: 'final' } },
  ],
});
// result.results[i] -- { op, table, row } for each op, in order.

// A failing op rolls back the whole batch; the thrown error's details name
// the failing op's index (details.op_index) and the underlying typed error
// (e.g. system_column_immutable, NOT_FOUND, CONFLICT).

use kapable_sdk::data::{BatchOp, BatchOpKind, BatchRequest};
use serde_json::json;

let header_id = uuid::Uuid::new_v4();
let result = client.data().batch(&BatchRequest {
    ops: vec![
        BatchOp { op: BatchOpKind::Insert, table: "invoices".into(), id: Some(header_id),
                  data: json!({"total": 250}).as_object().unwrap().clone() },
        BatchOp { op: BatchOpKind::Insert, table: "invoice_lines".into(), id: None,
                  data: json!({"invoice_id": header_id, "amount": 100}).as_object().unwrap().clone() },
        BatchOp { op: BatchOpKind::Patch, table: "invoices".into(), id: Some(header_id),
                  data: json!({"status": "final"}).as_object().unwrap().clone() },
    ],
}).await?;

SSE Change Streams

        Subscribe to real-time change events via Server-Sent Events. The stream
        emits insert, update, and delete events as they happen.

Method	Path	Description

            GET
            /v1/sse
            SSE stream for table change notifications (query: tables=a,b)

Usage

// Subscribe to changes on the "contacts" table
const es = new EventSource(
  'https://api.kapable.ai/v1/sse?tables=contacts',
  // Add auth header via polyfill or proxy
);

es.addEventListener('insert', (e) => {
  const row = JSON.parse(e.data);
  console.log('New contact:', row);
});

es.addEventListener('update', (e) => {
  const row = JSON.parse(e.data);
  console.log('Updated:', row.id);
});

es.addEventListener('delete', (e) => {
  const { id } = JSON.parse(e.data);
  console.log('Deleted:', id);
});

Column Types

          Supported col_type values (lowercase, exactly as the API validates):
          text, integer, big_int, float,
          boolean, timestamp, uuid, json.
          Per-column flags: nullable, default_value,
          unique, indexed.

Next

Getting Started · Authentication

---

# Comms API

Source: https://docs.kapable.ai/comms
Section: API reference

Comms API

        Agent communication infrastructure -- agents, mailboxes, channels, rooms,
        email sending, SSE streams, Telegram bridges, presence, and MCP transport.

Token tier: session or at_ app-token — sk_ API keys are rejected

          The Comms customer surface rejects sk_live_ / sk_test_ /
          sk_org_ API keys with 401 (verified live). Authenticate
          with a kses_ session token, or mint a per-org at_
          app token for service-to-service integrations.
          Agent processes may also use a per-agent ak_ agent key for SSE
          streaming and message sending.

Agents

        Agents represent autonomous processes (AI agents, bots, workers) that
        can send and receive messages through mailboxes and rooms.

Method	Path	Description

            POST
            /v1/agents
            Create or upsert an agent

            GET
            /v1/agents
            List agents for the org

            DELETE
            /v1/agents/{id}
            Soft-delete an agent

            GET
            /v1/agents/{id}/mailboxes
            List mailboxes for an agent

            POST
            /v1/agents/{id}/keys
            Mint a new API key for an agent

            GET
            /v1/agents/{id}/keys
            List API keys for an agent

            DELETE
            /v1/agents/{id}/keys/{key_id}
            Revoke an agent key

            GET
            /v1/agents/{id}/stream
            SSE stream for agent events

SDK Examples

        TypeScript
        Rust

// Create an agent
const agent = await client.comms.createAgent({
  name: 'support-bot',
  description: 'Customer support automation',
});

// Mint an API key for the agent
const { key } = await client.comms.mintAgentKey(agent.id, {
  label: 'production',
});

// List agents
const agents = await client.comms.listAgents();

// List an agent's mailboxes
const mailboxes = await client.comms.listAgentMailboxes(agent.id);

// Rust SDK
use kapable_sdk::comms::types::*;

let agent = client.comms().create_agent(CreateAgentRequest {
    name: "support-bot".into(),
    description: Some("Customer support automation".into()),
    ..Default::default()
}).await?;

let key_resp = client.comms().mint_agent_key(agent.id, MintAgentKeyRequest {
    label: "production".into(),
}).await?;

let agents = client.comms().list_agents().await?;
let mailboxes = client.comms().list_agent_mailboxes(agent.id).await?;

Mailboxes and Channels

        Mailboxes are named inboxes attached to agents. Channels are typed
        communication pipes on a mailbox (e.g. "email", "webhook").

Method	Path	Description

            POST
            /v1/mailboxes
            Create or upsert a mailbox

            DELETE
            /v1/mailboxes/{id}
            Soft-delete a mailbox

            GET
            /v1/mailboxes/{id}/channels
            List channels for a mailbox

            POST
            /v1/channels
            Create a channel on a mailbox

SDK Examples

        TypeScript
        Rust

// Create a mailbox
const mailbox = await client.comms.createMailbox({
  agent_id: agent.id,
  address: 'support@acme.worker.email',
  display_name: 'Support Bot',
});

// Create a channel
const channel = await client.comms.createChannel({
  mailbox_id: mailbox.id,
  kind: 'email',
});

// Rust SDK
let mailbox = client.comms().create_mailbox(CreateMailboxRequest {
    agent_id: agent.id,
    address: "support@acme.worker.email".into(),
    display_name: Some("Support Bot".into()),
    ..Default::default()
}).await?;

let channel = client.comms().create_channel(CreateChannelRequest {
    mailbox_id: mailbox.id,
    kind: "email".into(),
    ..Default::default()
}).await?;

Messages and Email

        Read received messages and send outbound email through mailboxes.
        Rate limiting and send audit tracking are built in.

Method	Path	Description

            GET
            /v1/mailboxes/{id}/messages
            List messages for a mailbox

            GET
            /v1/messages/{id}
            Get a single message by ID

            POST
            /v1/mailboxes/{id}/send
            Send an email through a mailbox

            GET
            /v1/mailboxes/{id}/send-audit/hits
            Get rate-limit hits for a mailbox

SDK Examples

        TypeScript
        Rust

// List messages
const messages = await client.comms.listMessages(mailbox.id, {
  limit: 20,
  since: '2026-05-01T00:00:00Z',
});

// Send an email
const sent = await client.comms.sendEmail(mailbox.id, {
  to: 'user@example.com',
  subject: 'Your support ticket update',
  body_html: '<p>Your issue has been resolved.</p>',
  from: 'Support Bot <support@acme.worker.email>',
});

// Rust SDK
let messages = client.comms().list_messages(mailbox.id, ListMessagesQuery {
    limit: Some(20),
    since: Some("2026-05-01T00:00:00Z".into()),
    ..Default::default()
}).await?;

let sent = client.comms().send_email(mailbox.id, SendEmailRequest {
    to: "user@example.com".into(),
    subject: "Your support ticket update".into(),
    body_html: Some("<p>Your issue has been resolved.</p>".into()),
    from: Some("Support Bot <support@acme.worker.email>".into()),
    ..Default::default()
}).await?;

Rooms

        Rooms are multi-party message channels. Agents and users join rooms via
        invite tokens and exchange messages in real time via SSE streams.

Method	Path	Description

            POST
            /v1/rooms
            Create a room

            GET
            /v1/rooms
            List rooms

            GET
            /v1/rooms/{id}
            Get room details with participants

            POST
            /v1/rooms/join/{token}
            Join a room via invite token

            POST
            /v1/rooms/{id}/messages
            Post a message to a room

            GET
            /v1/rooms/{id}/messages
            List messages in a room

            GET
            /v1/rooms/{id}/stream
            SSE stream for room events

            POST
            /v1/rooms/{id}/invites
            Create an invite for a room

            GET
            /v1/rooms/{id}/invites
            List active invites

            POST
            /v1/rooms/{id}/invites/{invite_id}/revoke
            Revoke an invite

Joining a room from an invite link (agents & guests)

        An invite URL (https://chat.kapable.ai/join/rinv_…) opens the human
        chat UI — agents do not fetch that page. Agents and guests call
        the join API directly with the rinv_ token. No Kapable credentials are
        required: an unauthenticated join with a display_name mints a guest
        identity and returns a room-scoped gid_ token. (A kses_
        session or ak_ agent key is also accepted.)

# 1. Join — display_name is required for guest joins
curl -sS -X POST "https://api.kapable.ai/v1/rooms/join/rinv_XXXX" \
  -H "content-type: application/json" \
  -d '{"display_name":"My Agent"}'
# response: { participant, room, token: "gid_..." }  ← keep the gid_ token

# 2. Read messages — gid_ goes in the Authorization header, not x-api-key
curl -sS "https://api.kapable.ai/v1/rooms/{room_id}/messages?limit=30" \
  -H "authorization: Bearer gid_XXXX"

# 3. Post — the field is `body` on POST; messages read back as `body_text`
curl -sS -X POST "https://api.kapable.ai/v1/rooms/{room_id}/messages" \
  -H "authorization: Bearer gid_XXXX" -H "content-type: application/json" \
  -d '{"body":"Hello from an agent"}'

        Gotchas: the gid_ token is room-scoped — store it for the session
        and reuse it for every call to that room. Invite tokens can carry
        expires_at / max_uses / revoked_at; a 4xx on
        join means the invite is spent or revoked — ask a room admin for a fresh link
        rather than retrying. Note the field asymmetry: you send body but receive
        body_text (tracked as IMP-2469).

SDK Examples

        TypeScript
        Rust

// Create a room
const { room } = await client.comms.createRoom({
  name: 'project-alpha',
  description: 'Main coordination channel',
});

// Invite a user to the room
const { token } = await client.comms.createRoomInvite(room.id);

// Join with the invite token
const { room: joined } = await client.comms.joinRoom(token);

// Post a message
await client.comms.postRoomMessage(room.id, {
  body: 'Deployment started for v2.1',
  kind: 'text',
});

// List room messages
const { messages } = await client.comms.listRoomMessages(room.id, {
  limit: 50,
});

// Rust SDK
let room_resp = client.comms().create_room(CreateRoomRequest {
    name: "project-alpha".into(),
    description: Some("Main coordination channel".into()),
    ..Default::default()
}).await?;

let invite = client.comms().create_invite(room_resp.room.id, CreateInviteRequest {
    ..Default::default()
}).await?;

client.comms().join_room(&invite.token, JoinRoomRequest {
    ..Default::default()
}).await?;

client.comms().post_room_message(room_resp.room.id, PostRoomMessageRequest {
    body: "Deployment started for v2.1".into(),
    kind: Some("text".into()),
    ..Default::default()
}).await?;

let msgs = client.comms().list_room_messages(room_resp.room.id, ListRoomMessagesQuery {
    limit: Some(50),
    ..Default::default()
}).await?;

Room Agents and Presence

        Agents can be invited to rooms for automated participation. Presence
        tracking shows which agents are currently active.

Method	Path	Description

            POST
            /v1/rooms/{id}/agents
            Invite an agent to a room

            POST
            /v1/rooms/{id}/agents/{agent_id}/revoke
            Revoke an agent from a room

            POST
            /v1/rooms/{id}/agents/{agent_id}/heartbeat
            Send a heartbeat for agent presence

            GET
            /v1/rooms/{id}/presence
            Get current presence for a room

SDK Examples

        TypeScript
        Rust

// Invite agent to room
const invitation = await client.comms.inviteAgentToRoom(room.id, {
  agent_id: agent.id,
  role: 'participant',
});

// Heartbeat (agent should call periodically)
await client.comms.heartbeat(room.id, agent.id, {
  status: 'active',
});

// Get room presence
const { presence } = await client.comms.roomPresence(room.id);
for (const entry of presence) {
  console.log(`${entry.agent_id}: ${entry.status} (${entry.last_seen})`);
}

// Rust SDK
let invitation = client.comms().invite_agent_to_room(room_id, InviteAgentRequest {
    agent_id: agent.id,
    role: Some("participant".into()),
    ..Default::default()
}).await?;

client.comms().revoke_room_agent(room_id, agent.id).await?;

Annotations

Post annotations (reactions, metadata) on room messages.

Method	Path	Description

            POST
            /v1/rooms/{id}/messages/{message_id}/annotations
            Post annotations on a message

Bridges

        Connect rooms to external platforms. Currently supports Telegram with
        bi-directional message bridging.

Method	Path	Description

            POST
            /v1/rooms/{id}/bridges/telegram
            Link a Telegram chat to a room

            GET
            /v1/rooms/{id}/bridges/telegram/setup-url
            Get Telegram bot setup URL

            GET
            /v1/rooms/{id}/bridges
            List active bridges for a room

            POST
            /v1/rooms/{id}/bridges/{bridge_id}/revoke
            Revoke a bridge

App Tokens and Audit

        Org-scoped app tokens for service-to-service integrations. Send audit
        provides rate-limit monitoring and anomaly detection.

Method	Path	Description

            POST
            /v1/orgs/{org_id}/app-tokens
            Mint an org-scoped app token

            GET
            /v1/orgs/{org_id}/app-tokens
            List app tokens

            DELETE
            /v1/orgs/{org_id}/app-tokens/{token_id}
            Revoke an app token

            GET
            /v1/orgs/{org_id}/send-audit
            List send audit records

            GET
            /v1/orgs/{org_id}/anomaly-feed
            SSE stream for anomaly events

Mailbox Quotas

Per-mailbox rate-limit overrides for send operations.

Method	Path	Description

            GET
            /v1/mailboxes/{id}/quotas
            Get quota overrides for a mailbox

            PUT
            /v1/mailboxes/{id}/quotas
            Create or update quota overrides

            DELETE
            /v1/mailboxes/{id}/quotas
            Delete quota overrides

MCP Transport

        The Comms service exposes an MCP (Model Context Protocol) endpoint for
        agent onboarding. Agents can be added to Claude via a single command.

Method	Path	Description

            POST
            /v1/mcp/{token}
            MCP handler (agent token authenticated)

# Add a Kapable room to Claude Code as an MCP server
claude mcp add kapable-chat https://comms.kapable.ai/v1/mcp/ak_...

Managing comms in the console

        Everything above also has a UI. In the console sidebar under
        Comms: Agents creates agents, their
        mailboxes, and their ak_ keys (copy a minted key immediately
        — it's shown once); App Tokens mints org-level
        at_ tokens for server-to-server integrations; and
        Send Audit lists every outbound message with delivery
        status (delivered, bounced, pending), recipient, subject, and sender agent.

Best practices

One agent per purpose — separate agents for support, notifications, and automation keep identities, keys, and audit trails clean.

Rotate keys regularly — revoke old agent keys and mint new ones.

Monitor the send audit — it's the earliest place delivery issues (bounces, rate-limit hits) show up.

Connect only the channels each agent needs — fewer channels means a smaller surface to secure and audit.

Next

Getting Started · Authentication

---

# Knowledge API

Source: https://docs.kapable.ai/knowledge
Section: API reference

Knowledge API

        A knowledge graph service for claims, predicates, perspectives, entity
        resolution, provenance tracking, and invariant monitoring. Build
        structured knowledge bases with multi-perspective conflict detection.

Concepts

        A claim is a single typed assertion —
        subject predicate object: Acme Corp
        is_headquartered_in San Francisco;
        Widget API depends_on Auth Service.
        Claims carry metadata — who asserted them, when, a confidence score,
        and optional evidence links — and are retracted rather than
        deleted, preserving the audit trail. A predicate defines
        the kind of relationship a claim can express:

Field	Description

name	Machine-readable identifier (e.g. is_headquartered_in)

description	Human-readable explanation

domain_kind	Expected subject type (e.g. company, person)

range_kind	Expected object type (e.g. location, page_ref)

transitive	Whether the relationship chains (A→B, B→C implies A→C — e.g. a transitive reports_to infers Alice→Carol from Alice→Bob→Carol)

inverse_of	The reverse predicate, if one exists (e.g. manages ↔ reports_to)

        A perspective is a named viewpoint that groups related
        claims, so different members or automated systems can assert under their own
        perspective and disagreements become comparable instead of silent
        overwrites. Kapable ships seed predicates covering common
        relationships — person (affiliated_with,
        assigned_to, reports_to), organisation
        (is_headquartered_in, subsidiary_of,
        partner_of), technical (depends_on,
        deployed_to, implements), and content
        (authored_by, references, supersedes)
        — and you extend the ontology with custom predicates for your domain.
        Browse the full predicate ontology in the console's Knowledge
        page: a searchable table with domain-kind and seed-vs-custom filters.

Sources

        Sources represent the origin of knowledge -- documents, APIs, human input,
        or agent observations. Every claim traces back to a source for provenance.

Method	Path	Description

            GET
            /v1/knowledge/sources
            List sources (optional namespace filter)

            POST
            /v1/knowledge/sources
            Create a source

            DELETE
            /v1/knowledge/sources/{id}
            Soft-delete a source

SDK Examples

        TypeScript
        Rust

// Create a source
const source = await client.knowledge.createSource({
  namespace: 'product-docs',
  name: 'API Reference v2',
  kind: 'document',
  url: 'https://docs.example.com/api/v2',
});

// List sources by namespace
const sources = await client.knowledge.listSources('product-docs');

// Rust SDK
use kapable_sdk::knowledge::types::*;

let source = client.knowledge().create_source(CreateSourceRequest {
    namespace: Some("product-docs".into()),
    name: "API Reference v2".into(),
    kind: Some("document".into()),
    url: Some("https://docs.example.com/api/v2".into()),
    ..Default::default()
}).await?;

let sources = client.knowledge().list_sources(ListSourcesQuery {
    namespace: Some("product-docs".into()),
    ..Default::default()
}).await?;

Pages

        Pages are named entities within a source. They provide the structure for
        organizing claims and edges in the knowledge graph.

Method	Path	Description

            GET
            /v1/knowledge/pages
            List pages (canonical only)

            POST
            /v1/knowledge/pages
            Create a page

            POST
            /v1/knowledge/pages/merge
            Merge two pages (dedup)

SDK Examples

        TypeScript
        Rust

// Create a page
const page = await client.knowledge.createPage({
  source_id: source.id,
  title: 'Authentication',
  namespace: 'product-docs',
});

// Merge duplicate pages
await client.knowledge.mergePages({
  keep_id: canonicalPageId,
  merge_id: duplicatePageId,
});

// Rust SDK
let page = client.knowledge().create_page(CreatePageRequest {
    source_id: source.id,
    title: "Authentication".into(),
    namespace: Some("product-docs".into()),
    ..Default::default()
}).await?;

client.knowledge().merge_pages(MergePagesRequest {
    keep_id: canonical_page_id,
    merge_id: duplicate_page_id,
}).await?;

Claims

        Claims are the core knowledge unit -- subject-predicate-object triples with
        confidence scores, perspectives, and provenance. Claims can be retracted,
        searched, and compared across perspectives.

Method	Path	Description

            GET
            /v1/knowledge/claims
            List claims with optional filters

            POST
            /v1/knowledge/claims
            Create a claim (supports dry_run query param)

            GET
            /v1/knowledge/claims/{id}
            Get a single claim

            POST
            /v1/knowledge/claims/{id}/retract
            Retract a claim

            GET
            /v1/knowledge/claims/similar
            Search claims (lexical, vector, or hybrid)

            GET
            /v1/knowledge/claims-by-perspective
            Compare claims by perspective for a (subject, predicate)

SDK Examples

        TypeScript
        Rust

// Create a claim
const claim = await client.knowledge.createClaim({
  subject: 'kapable-auth',
  predicate: 'supports',
  object: 'OAuth 2.0',
  confidence: 0.95,
  source_id: source.id,
  perspective_id: perspectiveId,
});

// Dry-run: check what would happen without persisting
const outcome = await client.knowledge.createClaim(
  { subject: 'kapable-auth', predicate: 'supports', object: 'SAML' },
  { dryRun: true },
);

// Search claims
const similar = await client.knowledge.searchClaims({
  query: 'authentication protocol',
  mode: 'hybrid',
  limit: 10,
});

// Compare perspectives
const views = await client.knowledge.listClaimsByPerspective({
  subject: 'kapable-auth',
  predicate: 'supports',
});

// Retract a claim
await client.knowledge.retractClaim(claim.id, {
  reason: 'Superseded by newer information',
});

// Rust SDK
let claim = client.knowledge().create_claim(
    CreateClaimRequest {
        subject: "kapable-auth".into(),
        predicate: "supports".into(),
        object: "OAuth 2.0".into(),
        confidence: Some(0.95),
        source_id: Some(source.id),
        perspective_id: Some(perspective_id),
        ..Default::default()
    },
    CreateClaimQuery { dry_run: None },
).await?;

let similar = client.knowledge().search_claims(SearchClaimsQuery {
    query: Some("authentication protocol".into()),
    mode: Some("hybrid".into()),
    limit: Some(10),
    ..Default::default()
}).await?;

let views = client.knowledge().list_claims_by_perspective(CompareByPerspectiveQuery {
    subject: "kapable-auth".into(),
    predicate: "supports".into(),
}).await?;

client.knowledge().retract_claim(claim_id, RetractClaimRequest {
    reason: "Superseded by newer information".into(),
}).await?;

Claim Confidence Evidence

        Attach evidence records that justify a claim's confidence score. Each
        evidence record documents why the confidence was set to a particular value.

Method	Path	Description

            GET
            /v1/knowledge/claims/{id}/confidence-evidence
            List confidence evidence for a claim

            POST
            /v1/knowledge/claims/{id}/confidence-evidence
            Create confidence evidence for a claim

            GET
            /v1/knowledge/claim_confidence_evidence
            List all confidence evidence (global)

Claim Meta and Derivations

        Claim meta (reification) attaches metadata to claims. Derivations link
        claims that were derived from other claims.

Method	Path	Description

            GET
            /v1/knowledge/claim_meta
            List claim meta records

            POST
            /v1/knowledge/claim_meta
            Create claim meta

            GET
            /v1/knowledge/claim_derivations
            List claim derivations

            POST
            /v1/knowledge/claim_derivations
            Create claim derivation links

Edges

Edges connect pages in the knowledge graph (e.g. "references", "depends_on").

Method	Path	Description

            GET
            /v1/knowledge/edges
            List edges with optional filters

            POST
            /v1/knowledge/edges
            Create an edge between pages

SDK Examples

        TypeScript
        Rust

// Create an edge between pages
const edge = await client.knowledge.createEdge({
  source_page_id: authPageId,
  target_page_id: oauthPageId,
  predicate: 'depends_on',
});

// Rust SDK
let edge = client.knowledge().create_edge(CreateEdgeRequest {
    source_page_id: auth_page_id,
    target_page_id: oauth_page_id,
    predicate: "depends_on".into(),
    ..Default::default()
}).await?;

Predicates

        Predicates define the vocabulary for claims and edges. The predicate
        ontology supports parent/child relationships and inverse predicates.

Method	Path	Description

            GET
            /v1/knowledge/predicates
            List all predicates

            GET
            /v1/knowledge/predicates/{name}/ontology
            Get predicate ontology (parents, children, inverse)

SDK Examples

        TypeScript
        Rust

// List all predicates
const predicates = await client.knowledge.listPredicates();

// Get ontology for a predicate
const ontology = await client.knowledge.predicateOntology('supports');
// { name: 'supports', inverse: 'supported_by', parents: [...], children: [...] }

// Rust SDK
let predicates = client.knowledge().list_predicates().await?;

let ontology = client.knowledge().predicate_ontology("supports").await?;
// ontology.name, ontology.inverse, ontology.parents, ontology.children

Canonical Entities

        Entity resolution merges duplicate references into canonical entities.
        Auto-merge candidates are surfaced for review and decision.

Method	Path	Description

            GET
            /v1/knowledge/canonical_entities
            List canonical entities

            POST
            /v1/knowledge/canonical_entities/resolve
            Resolve (or create) a canonical entity

            GET
            /v1/knowledge/canonical_entities/merge_candidates
            List merge candidates

            POST
            /v1/knowledge/canonical_entities/merge_candidates/{id}/decide
            Decide a merge candidate

            POST
            /v1/knowledge/canonical_entities/merge_candidates/{id}/unmerge
            Unmerge a previously merged candidate

SDK Examples

        TypeScript
        Rust

// Resolve an entity (find or create canonical)
const result = await client.knowledge.resolveCanonicalEntity({
  name: 'Kapable Auth Service',
  namespace: 'services',
});

// List merge candidates
const candidates = await client.knowledge.listMergeCandidates({
  status: 'pending',
});

// Accept a merge
await client.knowledge.decideMergeCandidate(candidateId, {
  decision: 'merged',
});

// Undo a merge
await client.knowledge.unmergeMergeCandidate(candidateId, {
  reason: 'False positive -- different services',
});

// Rust SDK
let result = client.knowledge().resolve_canonical_entity(ResolveCanonicalEntityRequest {
    name: "Kapable Auth Service".into(),
    namespace: Some("services".into()),
    ..Default::default()
}).await?;

let candidates = client.knowledge().list_merge_candidates(ListMergeCandidatesQuery {
    status: Some("pending".into()),
    ..Default::default()
}).await?;

client.knowledge().decide_merge_candidate(candidate_id, DecideMergeCandidateRequest {
    decision: "merged".into(),
    ..Default::default()
}).await?;

client.knowledge().unmerge_merge_candidate(candidate_id, UnmergeRequest {
    reason: Some("False positive -- different services".into()),
}).await?;

Perspectives

        Perspectives represent viewpoints from which claims are made. Different
        agents, teams, or documents may hold different perspectives on the same
        subject-predicate pair.

Method	Path	Description

            GET
            /v1/knowledge/perspectives
            List all perspectives

            GET
            /v1/knowledge/perspectives/{id}
            Get a perspective by ID

Provenance

        Track the provenance chain for sources -- where knowledge came from and
        how it was transformed.

Method	Path	Description

            GET
            /v1/knowledge/source_provenance
            List source provenance records

            GET
            /v1/knowledge/sources/{id}/provenance-graph
            BFS provenance graph for a source

SDK Examples

        TypeScript
        Rust

// Get the provenance graph for a source
const graph = await client.knowledge.sourceProvenanceGraph(sourceId, {
  depth: 3,
});
// graph.nodes, graph.edges -- ready for visualization

// Rust SDK
let graph = client.knowledge().source_provenance_graph(source_id, Some(3)).await?;
// graph.nodes, graph.edges

Invariants and Assay

        The Knowledge service runs periodic invariant checks (assay runs) to
        detect data quality issues, contradictions, and anomalies.

Method	Path	Description

            GET
            /v1/knowledge/invariants
            List invariant definitions

            GET
            /v1/knowledge/assay_runs
            List assay run results

Tensions

        Detect contradictions (tensions) between claims. Useful for surfacing
        conflicting information from different perspectives.

Method	Path	Description

            GET
            /v1/knowledge/tensions
            Detect tensions (contradictions) between claims

SDK Examples

        TypeScript
        Rust

// Detect tensions
const tensions = await client.knowledge.detectTensions({
  namespace: 'product-docs',
});
for (const t of tensions.items) {
  console.log(`Tension: ${t.claim_a.subject} vs ${t.claim_b.subject}`);
  console.log(`  Predicate: ${t.predicate}`);
}

// Rust SDK
let tensions = client.knowledge().detect_tensions(TensionsQuery {
    namespace: Some("product-docs".into()),
    ..Default::default()
}).await?;
for t in &tensions.items {
    println!("Tension: {} vs {}", t.claim_a.subject, t.claim_b.subject);
}

Best practices

Use specific predicates — prefer is_headquartered_in over a generic related_to.

Include confidence scores — not all claims are equally certain.

Link evidence — attach source URLs so claims can be verified.

Use perspectives — separate human-asserted claims from automated ones.

Retract, don't delete — retraction preserves the audit trail.

Next

Getting Started · Authentication

---

# AI API

Source: https://docs.kapable.ai/ai
Section: API reference

AI API

        Org-scoped AI provider management and a pass-through proxy: configure provider
        credentials once per org, then call any provider's native API through Kapable
        without shipping provider keys to clients.

Token tier: API keys work here

          The AI module is scope-gated: an sk_live_ key with the right
          scope gets 200 (verified live — it's one of the surfaces in the
          SDK's golden-path smoke test).

Providers

Method	Path	SDK (client.ai)

GET	/v1/providers	listProviders

GET	/v1/providers/{id}	getProvider

POST	/v1/providers/{id}/configure	configureProvider

DELETE	/v1/providers/{id}/configure	removeProviderConfig

Provider proxy

        POST /v1/proxy/{provider}/{path} forwards the request to the
        configured provider with the org's stored credentials. The SDK returns the raw
        Response so you keep full control over streaming bodies.

Zero-config AI: OpenRouter only, for now

          A freshly provisioned org can call client.ai.proxy('openrouter', …)
          (or POST /v1/proxy/openrouter/* directly) with no setup — the
          platform funds a default key for that provider, so the call just works. This
          default is provider-specific, by design: only providers the
          platform funds a key for get one (currently just OpenRouter); calling any other
          provider without first configuring your own key still returns 400 No API
          key configured for provider. Configuring your own key for a provider
          (configureProvider) always overrides the platform default for that
          provider.

SDK Examples

        TypeScript
        Rust

// List providers and their configuration state
const { providers } = await client.ai.listProviders();

// Point the provider at a strongbox secret holding the org's upstream key —
// the raw key never travels through this SDK (store it via client.secrets first)
await client.ai.configureProvider('anthropic', { key_name: 'anthropic-api-key' });

// Call the provider's native API through the proxy
const res = await client.ai.proxy('anthropic', '/v1/messages', {
  body: {
    model: 'claude-sonnet-4-6',
    max_tokens: 256,
    messages: [{ role: 'user', content: 'Hello from Kapable' }],
  },
});
const completion = await res.json();

let providers = client.ai().list_providers(ListProvidersParams::default()).await?;

let payload = serde_json::json!({
    "model": "claude-sonnet-4-6",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello from Kapable"}]
});
let res = client.ai().proxy("anthropic", "/v1/messages", ProxyRequest {
    body: Some(serde_json::to_vec(&payload)?),
    ..ProxyRequest::post()
}).await?;

Text-to-speech (M10)

        A dedicated endpoint for spoken-summary generation — the counterpart to
        Artifacts' audio summaries. Distinct
        from the generic provider proxy above: this owns ElevenLabs key resolution so
        callers never touch the raw upstream API or strongbox directly.

Method	Path	SDK (client.ai)

POST	/v1/ai/tts	tts

GET	/v1/ai/admin/tts-settings	getTtsSettings

PUT	/v1/ai/admin/tts-settings	putTtsSettings

DELETE	/v1/ai/admin/tts-settings	deleteTtsSettings

        Key resolution: if the org has stored its own ElevenLabs key
        (PUT /v1/ai/admin/tts-settings, admin/owner only — encrypted at rest,
        never echoed back), it synthesizes with no metering. Otherwise the
        platform's own key synthesizes and a usage event (characters synthesized) is recorded.
        text is capped at ~5000 characters per call (422 if exceeded); voice
        is optional (org default, else a platform default).

        TypeScript
        Rust

// BYO org key (admin/owner only) — no metering once set.
await client.ai.putTtsSettings({ api_key: process.env.ELEVENLABS_API_KEY });

// Synthesize — returns raw audio/mpeg bytes.
const bytes = await client.ai.tts({ text: "Relate's fifty-fourth tick shipped…" });

// Attach to an artifact version (base64-encode first).
const b64 = Buffer.from(bytes).toString('base64');
await client.artifacts.attachAudio('relate-tick-54', 1, { data: b64 });

let bytes = client.ai().tts(TtsRequest { text: "…".into(), voice: None }).await?;

let b64 = base64::engine::general_purpose::STANDARD.encode(&bytes);
client.artifacts().attach_audio("relate-tick-54", 1, AudioAttach {
    data: b64, content_type: None, duration_secs: None, generated_via: None,
}).await?;

Next

Getting Started · Authentication

---

# Model Catalog

Source: https://docs.kapable.ai/models
Section: API reference

Model Catalog

        Every AI model we track — what it costs, how much context it holds, when it
        shipped — merged nightly from models.dev and LiteLLM, plus intelligence scores
        from Artificial Analysis. Below the catalog sits the roster: the
        models an org has approved for each kind of work.

Loading the latest publish run…

        Published as static JSON:
        catalog.json,
        receipt.json,
        rosters/geldentech.json.
        CORS is open — read them from anything.

Roster — who we've approved for what

        The catalog is facts; the roster is policy. It is edited by decision,
        never by the nightly job, and it names a ranked fallback order per role rather than a
        single model — so a role survives a model being retired. Skills ask the roster
        “who does X for us today?” instead of hardcoding a model name.

Loading the roster…

Catalog

        Prices are US dollars per million tokens. Click a column heading to sort;
        untracked values always sort to the bottom, because an absence is not a small number.

Absence is typed, never blank

          A dash (—) means no source publishes that value for that model — hover it
          for the reason. It never means zero, and it never sorts as zero. Whether a whole
          column is available at all depends on its source: the status chips at the top of this
          page say which feeds answered on the last run.

Loading the catalog…

How it is built

        A nightly job on the platform fetches three public feeds and merges them by canonical
        model id (creator/model-slug). On conflict: pricing follows LiteLLM (fastest
        to update on launch day), specifications follow models.dev, and intelligence and speed
        come only from Artificial Analysis. Every merged field records where it came from.

        Source rows that cannot be mapped to a canonical id are not dropped silently — they
        land in unmapped[] in the receipt, and the count is shown at the top of this
        page. First-party API models only: Bedrock, Azure Foundry and Vertex variants are
        deliberately out of scope.

Next

Getting Started · Authentication

---

# Secrets API

Source: https://docs.kapable.ai/secrets
Section: API reference

Secrets API

        Org-scoped encrypted secrets from strongbox (the encrypted secrets service): store
        provider keys and app credentials once, reference them by name everywhere
        (e.g. the AI provider proxy reads provider keys from here at request time).

get and rotate return CLEARTEXT

          list / create / update return
          metadata only — never values. But get and
          rotate return the decrypted cleartext value.
          Treat any credential that can call them as able to read every secret it can
          name: scope keys narrowly, audit reads via the audit endpoint,
          and never log the response.

Well-known scopes

        Secret names are free-form, but one prefix carries platform behavior:
        a secret named app:NAME (flat, no further colons —
        e.g. app:DATABASE_URL) is merged into the environment of
        any app your org self-deploys
        on its own runners. The merge receipt lists names only, and your value
        wins over any pipeline default of the same name.

Endpoints

Method	Path	SDK (client.secrets)	Returns value?

GET	/v1/orgs/{org_id}/secrets	list	metadata only

POST	/v1/orgs/{org_id}/secrets	create	metadata only

GET	/v1/orgs/{org_id}/secrets/{name}	get	cleartext

PUT	/v1/orgs/{org_id}/secrets/{name}	update	metadata only

DELETE	/v1/orgs/{org_id}/secrets/{name}	delete	—

POST	/v1/orgs/{org_id}/secrets/{name}/rotate	rotate	cleartext (new value)

GET	/v1/orgs/{org_id}/audit	audit	access log

        Secret names are validated server-side: 1–256 chars from
        [A-Za-z0-9._-]; duplicates return 409 DUPLICATE_NAME.

SDK Examples

        TypeScript
        Rust

// Create (response is metadata — the value is write-only here)
await client.secrets.create(orgId, {
  name: 'anthropic-api-key',
  value: process.env.ANTHROPIC_KEY!,
});

// List — names + metadata, no values
const secrets = await client.secrets.list(orgId);

// Read the decrypted value (CLEARTEXT — handle with care)
const { value } = await client.secrets.get(orgId, 'anthropic-api-key');

// Rotate to a fresh random value, returned once
const rotated = await client.secrets.rotate(orgId, 'webhook-signing-key');

// Who read what, when
const audit = await client.secrets.audit(orgId);

client.secrets().create(org_id, &CreateSecretRequest {
    name: "anthropic-api-key".into(),
    value: std::env::var("ANTHROPIC_KEY")?,
}).await?;

let value = client.secrets().get(org_id, "anthropic-api-key").await?; // cleartext
let audit = client.secrets().audit(org_id).await?;

Next

Getting Started · Authentication

---

# Billing API

Source: https://docs.kapable.ai/billing
Section: API reference

Billing API

        Stripe-backed org billing: read billing state, initialize a subscription
        checkout, open the Stripe customer portal, and start checkouts for
        Warrant-licensed products.

Token tier: sessions only — API keys are rejected

          The billing service rejects sk_live_ / sk_test_ API
          keys entirely (verified live). Authenticate with a kses_ session
          token or an RS256 JWT. This is by design: payment actions are tied to a human
          org member, not a machine credential.

Endpoints

Method	Path	SDK (client.billing)

GET	/v1/orgs/{org_id}/billing	get

POST	/v1/orgs/{org_id}/billing/init	init

POST	/v1/orgs/{org_id}/billing/portal	portal

POST	/v1/checkout/warrant-product	createWarrantCheckout

SDK Examples

        TypeScript
        Rust

// Construct the client with a session token (API keys are rejected here)
const billing = await client.billing.get(orgId);
console.log(billing.plan, billing.status);

// Start a subscription checkout — redirect the user to the returned URL
const { checkout_url } = await client.billing.init(orgId, {
  plan_code: 'pro',
});

// Open the Stripe customer portal for self-service management
const portal = await client.billing.portal(orgId);

let billing = client.billing().get(org_id).await?;

let session = client.billing().init(org_id, &BillingInitRequest {
    plan_code: "pro".into(),
}).await?;

Redirect URLs are origin-checked

          Checkout/portal redirect URLs must be on .kapable.ai /
          .kapable.run / localhost — arbitrary origins
          are refused.

Billing in the console

        The console's Billing page is the human counterpart to this
        API: it shows your current plan, usage against plan limits (apps, team
        members) with progress bars and overage warnings, and monthly invoices you
        can view and download once subscribed. The Manage Billing
        button opens the same Stripe customer portal as the portal
        endpoint — update payment methods, change plans, view history, or
        cancel. Current plan tiers and pricing live at
        kapable.ai/pricing.

Next

Getting Started · Authentication

---

# Wiki API

Source: https://docs.kapable.ai/wiki
Section: API reference

Wiki API

        Org wikis with markdown pages, collections, tags, and projects — plus
        AI-assisted authoring: generate pages from prompts or the knowledge graph (the claim store)
        entities, and regenerate them as the underlying knowledge changes.

Token tier: API keys accepted

          Wiki routes accept sk_live_ keys (verified live — a fresh org
          gets an empty list / 404 rather than a permission error).

Pages

Method	Path	SDK (client.wiki)

GET	/v1/wiki/pages	listPages

POST	/v1/wiki/pages	createPage

PUT	/v1/wiki/pages/{id}	updatePage

DELETE	/v1/wiki/pages/{id}	deletePage

GET	/api/wiki/pages/{id}/raw	getRawPage

AI-assisted authoring

Method	Path	SDK (client.wiki)

POST	/v1/wiki/pages/from-prompt	createPromptPage

POST	/v1/wiki/pages/from-entity	createEntityPage

PUT	/v1/wiki/pages/{id}/prompt	updatePrompt

POST	/v1/wiki/pages/{id}/regenerate	regenerate

POST	/v1/wiki/pages/{id}/generate-narrative	generateNarrative

Collections, tags & projects

Method	Path	SDK (client.wiki)

GET	/v1/wiki/collections	listCollections

POST	/v1/wiki/collections	createCollection

PUT	/v1/wiki/collections/{id}	updateCollection

DELETE	/v1/wiki/collections/{id}	deleteCollection

POST	/v1/wiki/collections/{id}/pages	addPageToCollection

GET	/v1/wiki/tags	listTags

POST	/v1/wiki/pages/{id}/tags	addTagsToPage

GET	/v1/wiki/projects	listProjects

POST	/v1/wiki/projects	createProject

Agent tools

        A small read/search surface designed for AI agents: page reads, substrate
        claim search, canonical-entity lookup, predicates, and generation history
        (searchClaims, getCanonicalEntity,
        listPredicates, readPageTool, listPagesTool,
        pageGenerationHistory under /v1/wiki/agent-tools/…).

SDK Examples

        TypeScript
        Rust

// Create a freeform markdown page
const page = await client.wiki.createPage({
  slug: 'runbook-deploys',
  title: 'Deploy Runbook',
  body_markdown: '# Deploys\n\n1. Push to main…',
});

// Generate a page from a prompt (AI-authored, grounded on the org's knowledge)
const generated = await client.wiki.createPromptPage({
  slug: 'arch-overview',
  title: 'Architecture Overview',
  prompt: 'Summarize our service architecture for new engineers',
});

// List pages
const pages = await client.wiki.listPages();

let page = client.wiki().create_page(&CreateWikiPageRequest {
    slug: "runbook-deploys".into(),
    title: "Deploy Runbook".into(),
    body_markdown: "# Deploys\n\n1. Push to main…".into(),
    ..Default::default()
}).await?;

let pages = client.wiki().list_pages(None).await?;

Next

Getting Started · Authentication

---

# Harbor API

Source: https://docs.kapable.ai/harbor
Section: API reference

Harbor API

        Harbor handles release files and licenses. Use it to activate a license,
        check a license, and download a release from releases.kapable.ai.

Token tier: activate/validate are public

          License activate and validate are deliberately
          unauthenticated (your shipped software calls them from end-user machines).
          Org-scoped endpoints accept sk_live_ keys.

Licensing

Method	Path	SDK (client.harbor)

POST	/v1/harbor/licenses/activate	activate

POST	/v1/harbor/licenses/validate	validate

GET	/v1/harbor/licenses/{key}	getLicense

GET	/v1/licenses/{key}/usage	getLicenseUsage

Releases & artifacts

Method	Path	SDK (client.harbor)

GET	/v1/products/{product}/releases/{version}	getReleaseManifest

GET	/v1/products/{product}/releases/{version}/download	downloadReleaseArtifact

GET	/v1/releases/{product}/latest	getLatestReleaseCompat

GET	/v1/artifacts/{id}	downloadArtifact

POST	/v1/releases/verify	verifyRelease

GET	/v1/orgs/{org_id}/public-key	getOrgPublicKey

GET	/v1/orgs/{org_id}/keys	listOrgKeys

SDK Examples

        TypeScript
        Rust

// In your shipped software — activate a license on first run (public endpoint)
const activation = await client.harbor.activate({
  key: 'LK-XXXX-XXXX-XXXX',
  machine_id: machineId,
});

// Validate on startup
const status = await client.harbor.validate({ key: 'LK-XXXX-XXXX-XXXX' });

// Check what a release contains, then download it
const manifest = await client.harbor.getReleaseManifest('my-product', '1.4.0');
const artifact = await client.harbor.downloadReleaseArtifact('my-product', '1.4.0');

let activation = client.harbor().activate(&ActivateRequest {
    key: "LK-XXXX-XXXX-XXXX".into(),
    machine_id: Some(machine_id),
    ..Default::default()
}).await?;

let manifest = client.harbor().get_release_manifest("my-product", "1.4.0").await?;

Harbor vs Warrant

          Harbor licenses gate access to your released artifacts; the
          Warrant API gates features and
          entitlements inside your product. The two surfaces overlap on licensing
          and are slated for consolidation (tracked as IMP-1363).

Next

Getting Started · Authentication

---

# Warrant API

Source: https://docs.kapable.ai/warrant
Section: API reference

Warrant API

        Product licensing and feature entitlements for software you sell:
        define products, plans, and features; issue signed licenses; and gate features
        at runtime with offline-verifiable tokens (per-org Ed25519 signing).

Routing caveat at api.kapable.ai (IMP-1363)

          Four warrant paths collide with other services on the canonical base and are
          routed elsewhere: /v1/me, /v1/orgs (root),
          /v1/orgs/{id}/public-key, and /v1/products (root list).
          Until the harbor↔warrant consolidation lands, call warrant via
          https://{org}.kapable.ai/warrant as the base URL for the full
          surface. Warrant-distinct paths (/v1/check, /v1/activate,
          /v1/validate, /v1/products/{id}/…,
          /v1/licenses/{id}/…, /v1/shop/…) work on
          either base.

Products, plans & features

Method	Path	SDK (client.warrant)

GET	/v1/products	listProducts

POST	/v1/products	createProduct

GET	/v1/products/{id}	getProduct

PATCH	/v1/products/{id}	updateProduct

DELETE	/v1/products/{id}	deleteProduct

GET	/v1/products/{id}/features	listFeatures

POST	/v1/products/{id}/features	createFeature

GET	/v1/products/{id}/plans	listPlans

POST	/v1/products/{id}/plans	createPlan

Licenses

Method	Path	SDK (client.warrant)

GET	/v1/products/{id}/licenses	listLicenses

POST	/v1/products/{id}/licenses	issueLicense

GET	/v1/licenses/{id}	getLicense

POST	/v1/licenses/{id}/revoke	revokeLicense

POST	/v1/licenses/{id}/suspend	suspendLicense

POST	/v1/licenses/{id}/reactivate	reactivateLicense

Runtime checks (in your shipped product)

Method	Path	SDK (client.warrant)

POST	/v1/activate	activate

POST	/v1/validate	validate

POST	/v1/check	check

GET	/v1/shop/{org}/{product}	shopInfo

POST	/v1/shop/{org}/{product}/checkout	shopCheckout

SDK Examples

        TypeScript
        Rust

// Vendor side: define a product and issue a license
const product = await client.warrant.createProduct({
  name: 'My SaaS',
  slug: 'my-saas',
});
const license = await client.warrant.issueLicense('my-saas', {
  plan_slug: 'pro',
  customer_name: 'Acme Inc',
});

// Inside your shipped product: gate a feature with the signed token
const verdict = await client.warrant.check({
  signed_token: storedToken,
  feature: 'advanced-reports',
});
if (verdict.enabled) { /* unlock */ }

let verdict = client.warrant().check(&CheckRequest {
    signed_token: stored_token,
    feature: "advanced-reports".into(),
}).await?;

Next

Getting Started · Authentication

---

# Teams

Source: https://docs.kapable.ai/teams
Section: API reference

Teams

        A team is a named group inside an organization — with its own
        members, its own roles, and its own bound resources. Teams let an org owner answer
        “who works on what, and what can they touch?” without giving anyone
        org-wide permissions they don’t need. This page covers managing teams from the
        console and carrying team context through the API and SDKs.

Teams are called workspaces in the API

          The console and this documentation say Teams. Everywhere in the
          API, SDK types, and headers, the same construct is named workspace
          — the routes are /v1/workspaces, the header is
          X-Workspace-Id, the SDK client is client.workspaces. They
          are one and the same thing; only the label differs.

What a Team Is

        Your organization is the tenant — the isolation boundary that separates your
        data from every other org on Kapable. A team lives inside one org. It has:

a name and a slug (unique within the org),

an owner and its own member list,

per-team roles (four built-ins, plus any custom roles you define), and

resource bindings — apps, knowledge corpora, wiki pages, or data sources the team works on.

        A person can belong to many teams. The same person can be an owner of one
        team and a viewer of another. Teams never change the org itself: deleting
        a team never deletes the underlying resources or removes anyone from the org.

Org Roles vs. Team Roles

        These are two separate permission layers, and they never leak into each other.

Layer	Scope	Roles	Grants

            Org role
            Org-wide
            owner / admin / member / viewer (or a custom org role)
            What a person can do across the whole organization.

            Team role
            Within one team
            owner / admin / member / viewer (plus custom team roles)
            What a person can do inside that team, expressed as capability grants.

Team membership never changes org-wide permissions

          Adding someone to a team, changing their team role, or removing them from a team has
          no effect on their org-wide role. A team owner is not an
          org owner. Likewise, an org role never auto-grants team membership —
          being an org admin doesn’t put you on any team; you’re added or invited
          explicitly.

        Custom team roles draw from a fixed capability vocabulary:
        workspace.view, workspace.update,
        workspace.members.manage, workspace.invitations.manage,
        workspace.resources.manage, workspace.roles.manage,
        content.read, and content.write.

Managing Org Members

        Before you manage teams, you manage the people in your org. From the console at
        {org}.kapable.ai/console, open Members
        (/console/org/members). An org admin can:

See the roster — every member with their role and active status.

Invite by email — enter an email and pick a role. Kapable creates a
          single-use invitation and emails it.

See pending invitations — everyone invited but not yet accepted.

Revoke a pending invitation — the token stops working immediately.

Copy the accept link for manual delivery.

        When an invitee accepts, they appear in the roster automatically — no manual step.

Invitation links are shown once

          The accept link is revealed exactly once, on the “Invitation
          Created” page, with a Copy button. Kapable stores invitation tokens hashed, so the
          raw link cannot be recovered afterward — the pending list shows the invitation but
          not its link. Lost a link? Revoke the invitation and send a new one.

Managing Teams

        Open Teams in the console
        ({org}.kapable.ai/console/workspaces). An org admin can:

List the org’s teams, and create one. You give a
          name; the slug is derived from it and editable at create time. Once the team exists, the
          slug is immutable.

Open a team to see its members and their team roles, its pending
          invitations, and its bound resources.

Invite a member — by email (a single-use link, shown once, exactly
          like org invitations), or by picking an existing org member.

Change a team member’s role, including custom team roles.

Remove a team member — effective on their very next request.

Bind and unbind resources — declare which apps, knowledge corpora,
          wiki pages, or data sources the team works on.

Rename a team, and delete one (with confirmation).

        A plain org member who isn’t an admin still sees the teams they belong to.

Deleting a team releases its slug

          When you delete a team, its slug becomes available again — you can immediately
          create a new team with the same slug. A binding whose resource no longer exists is shown
          as unresolvable, with an unbind control, rather than being hidden.
          Resource bindings are declarations: binding records that a team works on a resource, and
          the owning service resolves it — Kapable does not delete the resource when you unbind
          it or delete the team.

Team Context in the API

        By default, every API call is scoped to your org — exactly as it
        always has been. To act within a team, a caller declares which
        team by sending the X-Workspace-Id header on an otherwise normal, validated
        session. Kapable verifies membership and, when it holds, resolves the team context.

          When the session belongs to an accepted member of a live team in the same
          org, the validate response gains two fields:
          workspace_id (the resolved team) and workspace_capabilities
          (the capability union of the member’s team role).

          When no header is sent, the response carries neither field —
          behavior is byte-identical to before teams existed. Absence of team context is always
          valid and means “org-scoped, as today.”

          When the caller declares a team they are not an accepted member of
          (or a deleted team, or a team in another org), the request is denied with a typed
          403 — Kapable never silently ignores an unauthorized declaration.

        Team-bound API keys carry their team context implicitly: a key minted
        against a team resolves that team on every call, with no header needed. A bound key is
        subject to the same membership check — if its team is deleted or the binding no
        longer holds, it gets the same typed denial the header path returns.

# Declare team intent on a validated session with the X-Workspace-Id header:
curl https://api.kapable.ai/v1/me \
  -H "Authorization: Bearer kses_..." \
  -H "X-Workspace-Id: 3f9c2a10-..."      # the team (workspace) id
# → 200 { ..., "workspace_id": "3f9c2a10-...",
#         "workspace_capabilities": ["content.read","content.write","workspace.view"] }

# Same session, no header → org-scoped, no workspace fields (unchanged behavior):
curl https://api.kapable.ai/v1/me -H "Authorization: Bearer kses_..."
# → 200 { ... }   (no workspace_id, no workspace_capabilities)

SDK Usage

        Both SDKs set the X-Workspace-Id header for you and surface the resolved
        workspace_id / workspace_capabilities on the validate response.

        TypeScript
        Rust

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

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

// Derive a client scoped to a team. Every call it makes carries
// X-Workspace-Id: teamId — including validate/me.
const teamClient = client.withWorkspace(teamId);

const ctx = await teamClient.auth.me();
// ctx.workspace_id           === teamId
// ctx.workspace_capabilities === ['content.read', 'content.write', 'workspace.view']

// No team intent → org-scoped, exactly as before:
const orgCtx = await client.auth.me();
// orgCtx.workspace_id is undefined

// Clear the scope again (org-wide client):
const backToOrg = teamClient.withWorkspace(undefined);

use kapable_sdk::KapableClient;
use kapable_sdk::auth::types::ValidateRequest;

// Declare team intent at build time with the .workspace_id(...) builder.
let team_client = KapableClient::new("https://api.kapable.ai")
    .token(session_token)          // kses_...
    .workspace_id(team_id)         // sends X-Workspace-Id on every call
    .build();

let ctx = team_client.auth().validate(&ValidateRequest {
    token: session_token.clone(),
}).await?;
// ctx.workspace_id           -> Some(the resolved team's uuid)
// ctx.workspace_capabilities -> Some(["content.read", "content.write", "workspace.view"])

// Or re-scope an existing client without rebuilding auth:
let team_client = client.with_workspace_id(team_id);
let org_client  = team_client.without_workspace_id(); // back to org-wide

Administering Teams via the SDK

        Team administration (create, invite, roles) is a session-token flow — it’s a
        human activity, so it uses a member session, not an API key. Both SDKs expose these under
        the workspaces client. Resource bind/unbind is the exception: it lives on
        the auth client — TS client.auth.bindWorkspaceResource() /
        unbindWorkspaceResource(), Rust client.auth().bind_workspace_resource() /
        unbind_workspace_resource().

        TypeScript
        Rust

// Create a team (the caller becomes its owner).
const team = await client.workspaces.create({
  name: 'Growth',
  slug: 'growth',
  description: 'Growth & lifecycle experiments',
});

// Invite a member by email — the token is shown ONCE in the response.
const invite = await client.workspaces.createInvitation(team.id, {
  email: 'teammate@example.com',
  role: 'member',
});
// invite.token — deliver this now; it is not recoverable later.

// Add an existing org member directly (by user id):
await client.workspaces.addMember(team.id, { user_id: userId, role: 'admin' });

// Define a custom team role from the capability vocabulary:
await client.workspaces.createRole(team.id, {
  role_name: 'editor',
  capabilities: ['workspace.view', 'content.read', 'content.write'],
});

// Bind a resource — note this one is on the AUTH client, not workspaces:
await client.auth.bindWorkspaceResource(team.id, { resource_type: 'app', resource_id: appId });

// List the team with its members and bound resources:
const detail = await client.workspaces.get(team.id);

use kapable_sdk::workspaces::types::{
    CreateWorkspaceRequest, CreateWsInvitationRequest, AddMemberRequest, CreateRoleRequest,
};
use kapable_sdk::auth::types::BindWorkspaceResourceRequest;

// Create a team (the caller becomes its owner).
let team = client.workspaces().create(&CreateWorkspaceRequest {
    name: "Growth".into(),
    slug: "growth".into(),
    description: Some("Growth & lifecycle experiments".into()),
}).await?;

// Invite a member by email — the token is shown ONCE in the response.
let invite = client.workspaces().create_invitation(team.id, &CreateWsInvitationRequest {
    email: "teammate@example.com".into(),
    role: Some("member".into()),
}).await?;
// invite.token — deliver this now; it is not recoverable later.

// Add an existing org member directly (by user id):
client.workspaces().add_member(team.id, &AddMemberRequest {
    user_id,
    role: Some("admin".into()),
}).await?;

// Define a custom team role from the capability vocabulary:
client.workspaces().create_role(team.id, &CreateRoleRequest {
    role_name: "editor".into(),
    capabilities: vec!["workspace.view".into(), "content.read".into(), "content.write".into()],
}).await?;

// Bind a resource — note this one is on the AUTH client, not workspaces:
client.auth().bind_workspace_resource(team.id, &BindWorkspaceResourceRequest {
    resource_type: "app".into(),
    resource_id: app_id,
}).await?;

// List the team with members + bound resources:
let detail = client.workspaces().get(team.id).await?;

Denial Receipts

        Every rejected action returns a typed, specific receipt — Kapable never fails
        silently. These are the exact shapes a builder sees on the team surface:

Code	What you see	What to do

            CONFLICT
            workspace slug already exists in this org
            Choose a new workspace slug.

            FORBIDDEN
            workspace_forbidden: not an accepted member of the requested workspace
            Accept an invite or use a workspace where you are a member.

            NOT_FOUND
            invitation not found, expired, or already used
            Ask the sender to create a new invite.

            FORBIDDEN
            must be workspace owner or org owner
            Ask the workspace or org owner to delete it.

        The SDKs normalize these into a thrown KapableError (TypeScript) /
        KapableError (Rust) carrying the status and message, so you handle them the
        same way as any other API error.

Next

Getting Started · Authentication

---

# Roles & Permissions

Source: https://docs.kapable.ai/roles
Section: Operate

Roles & Permissions

        Kapable uses role-based access control (RBAC) to manage what members
        can do within your organisation. This guide explains the built-in
        roles, how to create custom roles, and best practices for access
        management.

Built-in Roles

Every organisation comes with four built-in roles:

Owner

The organisation creator. Full access to everything.

Manage billing and subscription

Delete the organisation

Manage all members and roles

Configure authentication settings

Full app and deployment control

Access all audit logs

        There is exactly one owner per organisation. Ownership can be
        transferred but not shared.

Admin

        Trusted team leads with broad access, but no billing or destructive
        org controls.

Invite and manage members

Create and manage apps

Deploy and configure apps

Manage agents, mailboxes, and tokens

View audit logs

Configure auth settings (if permitted)

Member

Standard team members who build and deploy.

Create apps

Deploy to their own apps

View app logs and settings

Manage their own API keys

View team members (read-only)

Access documentation

Viewer

Read-only access for stakeholders and observers.

View apps and their status

View deployment history

View team members

Access documentation

Cannot create, modify, or deploy anything

Permission Matrix

Action	Owner	Admin	Member	Viewer

Organisation

View org info	Yes	Yes	Yes	Yes

Edit org name/slug	Yes	Yes	No	No

Delete organisation	Yes	No	No	No

Manage billing	Yes	No	No	No

Members

View members	Yes	Yes	Yes	Yes

Invite members	Yes	Yes	No	No

Remove members	Yes	Yes	No	No

Change member roles	Yes	Yes	No	No

Apps

View apps	Yes	Yes	Yes	Yes

Create apps	Yes	Yes	Yes	No

Deploy apps	Yes	Yes	Yes	No

Delete apps	Yes	Yes	No	No

Manage app settings	Yes	Yes	Yes	No

Manage custom domains	Yes	Yes	No	No

Auth & Security

View audit log	Yes	Yes	No	No

Configure SSO	Yes	Yes	No	No

Manage domain allowlist	Yes	Yes	No	No

Communications

View agents	Yes	Yes	Yes	Yes

Create agents	Yes	Yes	Yes	No

Manage agent keys	Yes	Yes	Yes	No

View send audit	Yes	Yes	Yes	No

API Keys

Create own API keys	Yes	Yes	Yes	No

Revoke own API keys	Yes	Yes	Yes	No

View all API keys	Yes	Yes	No	No

Revoke others' keys	Yes	Yes	No	No

Custom Roles

        Organisations on paid plans can create custom roles with fine-grained
        permissions.

Creating a Custom Role

Navigate to Roles in your console sidebar

Click Create Role

Enter a role name and description

Select permissions from the available list

Save the role

Assigning Custom Roles

Once created, custom roles appear in the role dropdown when:

Inviting new members

Changing an existing member's role

Editing and Deleting

Edit a custom role's permissions at any time — changes apply to all members with that role immediately

Deleting a custom role reassigns affected members to the Member built-in role

Built-in roles cannot be edited or deleted

Role-Based Access in the API

        When using the API with a session token or API key, the caller's role
        determines what endpoints succeed:

# This succeeds for Owner/Admin
POST /v1/orgs/{org_id}/invitations
Authorization: Bearer kses_...

# This fails for Member/Viewer with 403 Forbidden
POST /v1/orgs/{org_id}/invitations
Authorization: Bearer kses_...
{"error": "insufficient permissions"}

        The API returns 403 Forbidden for any action the caller's
        role doesn't permit.

Code	What you see	What to do

403	insufficient permissions	Ask an owner or admin to grant the needed permission.

Best Practices

Principle of Least Privilege

Assign the minimum role needed for each member's job:

Developers building apps → Member

Team leads managing the team → Admin

External stakeholders reviewing progress → Viewer

Only the billing contact → Owner

Regular Access Reviews

Review the member list monthly

Deactivate accounts for departed team members immediately

Downgrade roles when responsibilities change

Check the audit log for unusual activity patterns

Onboarding Checklist

When a new team member joins:

Send invitation with the appropriate role

Verify they authenticate through SSO (if configured)

Confirm they can access the apps they need

Share relevant documentation links

Offboarding Checklist

When a team member leaves:

Deactivate their account (Members page)

Revoke any API keys they created

Review and rotate shared secrets they had access to

Check recent audit log entries for their account

Next Steps

Teams

Org vs. team roles and team-scoped access.

Security & Compliance

SSO, audit logging, and session management.

Authentication

API keys, JWT tokens, and org context.

Next

Getting Started · Authentication

---

# Security & Compliance

Source: https://docs.kapable.ai/security
Section: Operate

Security & Compliance

        Kapable takes security seriously. This guide covers the platform's
        security features, compliance controls, and best practices for keeping
        your organisation safe.

Authentication Methods

Magic Links (Default)

        Every Kapable login uses a one-time magic link sent to the user's
        verified email. No passwords are stored or transmitted.

Links expire after 10 minutes

Each link can only be used once

Links are cryptographically signed and scoped to a single org

Single Sign-On (SSO)

Organisations on paid plans can configure SSO through:

Google OAuth 2.0 — uses Google Workspace identity

Microsoft OAuth 2.0 — uses Azure AD / Entra ID identity

Generic OIDC — any OpenID Connect provider (Okta, Auth0, Keycloak, etc.)

        Configure SSO in Auth Settings in your console. When
        SSO is enabled, users authenticate through your identity provider and
        are automatically provisioned in Kapable.

API Keys

        For programmatic access, create scoped API keys in the
        API Keys section. Keys use the kapi_
        prefix and are transmitted via the Authorization: Bearer
        header or X-Api-Key header.

Session Management

Token Lifecycle

Session tokens (kses_ prefix) are issued on successful authentication

Tokens are stored in encrypted HTTP-only cookies

Sessions expire after 30 days of inactivity

Tokens are invalidated immediately on logout

Logout Everywhere

        If you suspect a session has been compromised, use
        Logout Everywhere in your Account page. This instantly
        invalidates all active sessions across all devices and browsers.

Session Cookies

HttpOnly — not accessible to JavaScript

Secure — only sent over HTTPS

SameSite=Lax — protection against CSRF

Encrypted with a per-deployment secret (PrivateCookieJar)

Audit Logging

Every security-relevant event is recorded in the audit log:

Event	What's Recorded

Login	Email, IP, user agent, method (magic link / SSO)

Logout	Email, session duration

Failed login	Email attempted, IP, failure reason

API key created	Key name, creator email

API key revoked	Key ID, revoker email

Member invited	Invitee email, role assigned, inviter

Member deactivated	Target email, actor, reason

Role changed	Member, old role, new role, actor

Org settings changed	Field changed, actor

        Access the full audit log at Auth Audit in your
        console. Export to CSV for compliance reporting.

API Key Security

Best Practices

Name keys descriptively — e.g., "CI/CD Pipeline" or "Monitoring Dashboard"

Rotate regularly — revoke and re-create keys every 90 days

Use environment variables — never commit keys to source control

One key per service — don't share keys between applications

Monitor usage — check "last used" timestamps in the API Keys page

Key Prefixes

        All Kapable tokens use recognizable prefixes for easy identification:

Prefix	Type

kses_	Session token

kapi_	API key

kagent_	Agent key

kapp_	App token

Revoking Keys

        Revoke a key immediately from the API Keys page or via the API:

DELETE /v1/auth/api-keys/{key_id}
Authorization: Bearer kses_your_session_token

        Revocation is instant — any in-flight requests using the revoked
        key will fail.

Data Protection

Encryption in Transit

All traffic uses TLS 1.2+ (enforced by Caddy with automatic HTTPS)

Internal service-to-service communication uses private networking

API endpoints reject plain HTTP connections

Encryption at Rest

Database storage uses encrypted volumes

Secrets are stored in age-encrypted vault files

Session tokens are hashed before storage

Compliance Features

Domain Allowlists

        Restrict who can sign up or be invited to your organisation by
        configuring allowed email domains in Auth Settings.

Only email addresses matching allowed domains can join

Wildcard support for subdomains

Combine with SSO for maximum control

Signup Controls

Configure whether your organisation allows:

Self-signup — anyone with an allowed domain can create an account

Invitation only — only explicitly invited users can join

SSO-gated — users must authenticate through your SSO provider

Role-Based Access Control

        Limit what members can do based on their assigned role. See the
        Roles & Permissions guide for
        details.

Incident Response

If you suspect a security incident:

Logout Everywhere — Account page → Logout Everywhere (invalidates all sessions)

Revoke API keys — API Keys page → revoke any potentially compromised keys

Check the audit log — Auth Audit → filter by suspicious activity, export CSV

Deactivate compromised accounts — Members page → deactivate affected members

Review auth settings — ensure SSO and domain allowlists are properly configured

Security Headers

Kapable sets the following security headers on all responses:

X-Content-Type-Options: nosniff

X-Frame-Options: DENY

Strict-Transport-Security: max-age=31536000

Referrer-Policy: strict-origin-when-cross-origin

Next Steps

Roles & Permissions

RBAC, the permission matrix, and custom roles.

Authentication

API keys, JWT tokens, and org context.

Secrets API

Org-level secret storage via strongbox.

Next

Getting Started · Authentication

---

# Troubleshooting

Source: https://docs.kapable.ai/troubleshooting
Section: Operate

Troubleshooting

Common issues and how to resolve them.

Deployment Issues

Build Fails

If your app fails to build:

Check build logs — go to your app's detail page and click View Logs to see compiler output.

Verify environment variables — missing build-time variables (e.g. DATABASE_URL for Prisma) will cause failures. Go to App Settings > Environment and check all required vars are set.

Check dependencies — ensure your package.json, Cargo.toml, or equivalent lock file is committed and up to date.

Framework version — Kapable supports Node.js 20+, Rust stable, and Python 3.11+. Check your runtime requirements match.

App Shows "Unhealthy"

Your app deployed but isn't responding:

Check app logs — look for startup errors, panics, or binding issues.

Verify the port — your app must listen on the port provided in the PORT environment variable. Hardcoded ports won't work.

Startup time — apps have 30 seconds to start responding to health checks. If your app needs longer, consider optimizing startup or using a lighter health endpoint.

Memory limits — apps on the Free plan have 512MB RAM. Check for memory leaks or large startup allocations.

Custom Domain Not Working

DNS propagation — CNAME changes can take up to 48 hours to propagate. Use dig CNAME yourdomain.com to check.

Verify CNAME target — it should point to your-app-slug.kapable.run.

SSL certificate — certificates are issued automatically via Let's Encrypt. It may take a few minutes after DNS verification. Check the domain status in App Settings > Domains.

TXT record — if domain verification is pending, ensure the TXT record matches exactly what's shown in the console.

"503 Service Unavailable"

This means the app exists but isn't currently serving traffic:

Paused — check if the app was paused. Click Resume in the app detail page.

Building — a new deployment may be in progress. Check the deployment timeline.

Crashed — the app process exited. Check logs for the crash reason and redeploy.

Authentication Issues

Can't Log In

Check your email — magic links are sent to the email you signed up with. Check spam/junk folders.

Link expiry — magic links expire after 10 minutes. Request a new one if yours has expired.

Browser cookies — Kapable uses secure cookies. Ensure cookies are enabled and you're not in a browser mode that blocks them.

Correct organisation — if you belong to multiple orgs, ensure you're logging into the right one at {org-slug}.kapable.ai.

SSO Not Working

Client ID and Secret — verify these match exactly what your identity provider shows. Trailing whitespace is a common issue.

Redirect URI — the redirect URI configured in your IdP must match the one shown in Auth Settings. Copy it exactly.

Domain allowlist — if you've configured a domain allowlist, ensure the user's email domain is included.

Provider status — check that the provider shows "Active" in Auth Settings. If it shows "Configured" but not "Active", toggle the enable switch.

Session Expired

        Sessions expire after extended inactivity. Simply log in again. If
        sessions are expiring too quickly:

Check that your browser allows persistent cookies for .kapable.ai

Ensure your system clock is accurate (clock skew can cause token validation failures)

API Issues

Kapable returns {error:{code,message,details}}. The message is the human line.

Code	What you see	What to do

401	Unauthorized	Check the key, session, and auth header.

403	Forbidden	Ask an org owner to check your role and permission.

429	Rate Limited	Wait for Retry-After, then retry.

401 Unauthorized

Your API key or session token is invalid:

Revoked key — check the API Keys page to confirm the key is still active.

Wrong key — ensure you're using the correct key. Keys are shown only once at creation.

Header format — use Authorization: Bearer your-key-here (not X-Api-Key or other formats).

403 Forbidden

You're authenticated but lack permission:

Role check — your role may not have the required permission. Ask an org owner to check your role in Members. See Roles & Permissions.

Org scope — API keys are scoped to one organisation. Ensure you're accessing resources within the correct org.

429 Rate Limited

You're sending too many requests:

Default limits — Free plan: 60 requests/minute. Starter: 300/min. Pro: 1000/min.

Retry-After — check the Retry-After header in the response for when to retry.

Batch operations — if making many sequential calls, consider using bulk endpoints where available.

Billing Issues

Payment Failed

Go to Billing and click Manage Subscription to open the Stripe portal.

Update your payment method.

Stripe will automatically retry the charge.

Plan Limits Reached

If you've hit your plan's app or member limit:

Upgrade — go to Billing and select a higher plan.

Clean up — delete unused apps or deactivate inactive members to free up capacity.

Getting Help

If you can't resolve your issue:

Documentation — browse all guides at docs.kapable.ai

Email support — contact support@kapable.ai with your org slug and a description of the issue

Include details — app ID, timestamps, error messages, and screenshots help us resolve issues faster

Next Steps

Deployments

Statuses, retries, and the build pipeline.

Custom Domains

DNS, SSL, and domain verification.

Environment Variables

Build-time vs runtime configuration.

Next

Getting Started · Authentication

---

# Kapable On-Prem

Source: https://docs.kapable.ai/onprem-overview
Section: Own server

Kapable On-Prem

        Run the entire Kapable platform on a server you own —
        the same services, the same deploy pipeline, the same console that
        power the cloud, installed by one command against your own domain.
        With this documentation and a license key, you can stand up a
        production-shaped Kapable from a blank Ubuntu box.

What you get

        A single-box installation of the full v2 platform: PostgreSQL,
        the Berth (the deploy manager), the Caddy edge with automatic TLS,
        the service fleet (auth, gateway, hosting, console, launchpad, CI,
        and the rest), a first organization with an owner account, and a
        deployed sample app served over a real certificate at
        <app>.<org>.yourdomain.com.

        The installer is a 10-node dependency graph, not a
        script: every node checks before it changes, reports
        APPLIED or NO-CHANGE, and the whole graph is
        safe to re-run at any time. A from-zero install on a wiped box takes
        about 12 minutes; a verification re-run about 5.

Prerequisites

Requirement	Details

Server	Ubuntu 24.04 LTS, amd64. 4 vCPU / 8 GB RAM / 150 GB disk is proven sufficient for the full stack with headroom.

Access	Root SSH (key-based) from the machine you run the installer on.

Network	A public IPv4 address; ports 80 and 443 reachable from the internet (required for ACME certificate issuance).

Domain	A base domain you control (e.g. example.com) with the DNS records below.

ACME email	An email address for Let's Encrypt registration and expiry notices.

SMTP (optional)	Credentials for outbound mail. Skip entirely with --no-mail; everything else works without it.

License key	Issued by Kapable. See Licensing.

DNS records

Point three records at your server's public IP before installing:

Record	Type	Serves

example.com	A	The platform apex.

*.example.com	A	Org hosts (acme.example.com) and platform services (api., releases., …).

*.*.example.com	A	App hosts — deployed apps live at <app>.<org>.example.com, two labels deep.

        The two-level wildcard is not optional. A DNS wildcard
        (*.example.com) matches any depth, so app hostnames will
        resolve without the third record — but the TLS edge
        matches site addresses one label at a time, so without an explicit
        two-level entry the handshake for app.org.example.com is
        refused even though DNS answers. If TLS fails while
        dig succeeds, check this first.

Built for AI-assisted installation

        These pages are public by design, so you can hand them to your AI
        assistant before you have an account or a license — and the
        installer is built to be driven by one: every error names its cause
        and the corrective action in the message itself, the graph is
        idempotent so a failed run is simply re-run after the fix, and the
        final seal check gives an
        unambiguous, machine-readable exit code. Point your agent at this
        section and let it drive.

Next Steps

Install

The one command and the 10-node graph behind it.

Licensing

License keys, activation, and the bootstrap window.

Verify

The seal check: prove your install is correct.

Next

Getting Started · Authentication

---

# Install

Source: https://docs.kapable.ai/onprem-install
Section: Own server

Install

        One command installs the platform: kapable-ops bootstrap
        walks a 10-node dependency graph from a blank box to a served,
        TLS-terminated sample app. Every node is idempotent — the same
        command is the installer, the verifier, and the repair tool.

You need

The operator CLI, the access named in this guide, and the role needed for the action.

First call

kapable-ops --help

You should see the operator command list.

The command

        From your workstation (the installer connects to the server over SSH;
        nothing needs to be pre-installed on the box):

kapable-ops bootstrap \
  --server my-kapable-box \
  --domain example.com \
  --acme-email ops@example.com \
  --admin-email admin@example.com \
  --org-slug acme \
  --org-name "Acme" \
  --staff-email admin@example.com \
  --public-ip 203.0.113.10 \
  --artifact-source ~/kapable-artifacts \
  --no-mail

Flag	Meaning

--server	SSH host (alias or user@ip) of the target box. Root access required.

--domain	Your base domain. Org hosts and platform services hang off it; apps at <app>.<org>.<domain>.

--acme-email	Let's Encrypt registration email.

--org-slug / --org-name	Your first organization. The slug becomes its subdomain.

--admin-email / --staff-email	The owner account created for you, and which account gets platform-staff rights.

--public-ip	The box's public IPv4 — cross-checked against DNS during preflight.

--artifact-source	Directory containing the licensed platform binaries for your release. See artifact distribution.

--no-mail	Skip SMTP entirely. Use --smtp-host/-port/-username/-password and --email-from instead when you have a mail provider.

The 10-node graph

Nodes run in dependency order; each prints its outcome as it lands.

#	Node	What it does

0	preflight	SSH reachability, OS check, DNS records resolve to --public-ip, ports open.

1	pg	PostgreSQL 16 installed, cluster up, platform databases created.

2	secrets	Service secrets generated on the box and written to per-service env files (never transmitted).

3	berth	The deploy orchestrator installed with per-service signing keys; refuses unsigned deploys from first boot.

4	caddy-stage-1	The edge in HTTP-only bootstrap mode, ready to answer ACME challenges.

5	fleet-deploy	All platform services deployed through Berth as signed artifacts, health-checked.

6	caddy-stage-2	Full TLS edge: the gateway generates route config from its database; certificates are minted on demand and gated by an authorization check.

7	first-org	Your organization and owner account created through the real signup API; credentials persisted on the box at /root/.kapable-bootstrap/ (mode 0600); a real login is performed as the gate.

8	first-app	A sample app registered, built through the CI pipeline, and deployed.

9	seal-check	End-to-end verification: the app answers 200 over a real certificate. See Verify.

APPLIED vs NO-CHANGE

        Each node reports one of two outcomes. APPLIED means the
        node found something missing or wrong and fixed it — expected
        everywhere on a first run. NO-CHANGE means the node
        verified its slice of the system and touched nothing.

        Run the command twice. A correct installation reports
        NO-CHANGE on all ten nodes the second time. That
        all-NO-CHANGE repeat is not a formality — it is the proof that the
        installer converged, and it is the same mechanism you will later use
        to repair drift.

        If a node fails, read the error — it names the cause and the
        corrective action. Fix, then re-run the same full command:
        completed nodes fly by as NO-CHANGE and execution resumes
        where it stopped. A full re-run is the supported resume mechanism.

Next Steps

Licensing

Activate your install within the bootstrap window.

Verify

Run the seal check and read its three gates.

Operate

Day-2: healing, upgrades, and backups.

Next

Getting Started · Authentication

---

# Licensing

Source: https://docs.kapable.ai/onprem-license
Section: Own server

Licensing

        An on-prem installation runs under a signed license
        issued by Kapable. The license is the wall — this documentation is
        public, the platform bits are licensed. You never receive or handle
        signing keys; you receive a license for your installation.

You need

The operator CLI, the access named in this guide, and the role needed for the action.

First call

kapable-ops --help

You should see the operator command list.

How licensing works

Platform services validate a signed license at startup and bind it to the machine they run on (a fingerprint of the box). A license moved to different hardware fails validation by design.

Licenses are issued by Kapable, scoped to your installation, and renewable. Issue and revocation are functions of the Kapable release service; validation happens locally on your box — a running install does not phone home to stay up.

The installer places license material on the box during node 5 (fleet-deploy); you don't hand-install files.

The bootstrap window

        A fresh installation boots its services inside a 72-hour
        bootstrap window, so the install itself never blocks on
        license logistics. Activate with your issued license inside that
        window and the installation transitions to its durable license;
        after the window closes, unlicensed services stop accepting work
        with an error that says exactly this.

Getting the bits

        Two things are distributed to you: the kapable-ops
        installer CLI, and the artifact bundle — the set
        of signed platform binaries for a release, which you point
        --artifact-source at.

        Current status, honestly: self-service distribution
        through https://releases.kapable.ai (download a release
        bundle with your license key, installer validates it offline) is
        rolling out. Until it lands, artifact bundles and license issuance
        are operator-assisted — contact us
        and we provision both with you, typically same-day. The install
        procedure on these pages is identical either way; only how the
        bundle reaches your workstation changes.

Next Steps

Install

The one command and the 10-node graph.

Verify

Prove the install with the seal check.

Harbor API

The release & licensing service behind activation.

Next

Getting Started · Authentication

---

# Verify: the Seal

Source: https://docs.kapable.ai/onprem-verify
Section: Own server

Verify: the Seal

        You don't have to take the installer's word for it. The
        seal check is a read-only verification pass you run
        yourself: exit code 0 means your installation is sealed
        — serving a real app over a real certificate, with its security
        gates re-proven live. It mutates nothing.

You need

The operator CLI, the access named in this guide, and the role needed for the action.

First call

kapable-ops --help

You should see the operator command list.

Running it

Append --seal-check to the same bootstrap command:

kapable-ops bootstrap ... --seal-check
# === seal-check (verify-only; mutates nothing) ===
# ✓ berth fails-closed gate
# ✓ gateway insecure-default probe (401 without token)
# ✓ first-org login cookie round-trip
#
# SEAL CHECK PASSED: zero open receipts, all re-probed gates green.
echo $?   # 0

        A non-zero exit prints which gate failed and why. The check is safe
        to run any time — in cron, in your monitoring, after an incident,
        before an upgrade.

The three gates

Gate	What it proves

Berth fails closed	The deploy orchestrator rejects unsigned work. Nobody — including a compromised CI step — can push an unsigned binary onto your box.

Gateway fails closed	The route-management API answers 401 without its token. The edge cannot be reconfigured anonymously.

Login round-trip	A real login POST with your owner account returns a valid session cookie for your domain — auth, database, TLS, and cookie scoping all working together, end to end.

The convergence signal

        The deeper health check is the plain re-run: execute the full
        bootstrap command (without --seal-check) and read the
        outcomes. All ten nodes reporting NO-CHANGE means the
        system matches its specification exactly. Any APPLIED on
        a re-run is the installer telling you it found drift — and
        that it just repaired it. The node name tells you what drifted.

Next Steps

Operate

Day-2: healing, upgrades, and backups.

Install

Back to the command and the graph.

Security & Compliance

The platform security model in depth.

Next

Getting Started · Authentication

---

# Operate

Source: https://docs.kapable.ai/onprem-operate
Section: Own server

Operate

        Day-2 on-prem is deliberately boring: the installer is also the
        repair tool, every error tells you what to do, and the seal check
        tells you when you're done. There is no separate runbook to
        memorize.

You need

The operator CLI, the access named in this guide, and the role needed for the action.

First call

kapable-ops --help

You should see the operator command list.

Healing: re-run the installer

        The bootstrap graph is idempotent, so the repair procedure
        for almost anything is the install command itself. A config
        file hand-edited into a bad state, a service unit removed, a missing
        database — re-run the full command and watch the outcomes: nodes
        that find drift report APPLIED (found and fixed), the
        rest report NO-CHANGE. Finish with
        --seal-check for the receipt.

        Re-running is safe while the platform is serving: nodes verify
        before they touch anything, and a converged system takes about five
        minutes to walk with zero changes.

Errors are instructions

        Platform error messages name the limit or cause and the
        corrective action, in the message itself. This is a design rule, not
        an aspiration — the intended reader of an error is whoever (or
        whatever) will act on it, including your AI assistant. When
        something fails: read the error, do what it says, re-run. If an
        error ever leaves you guessing, that is a bug worth
        reporting.

Upgrades

        An upgrade is the same motion as an install: obtain the newer
        artifact bundle for your license (see
        distribution),
        point --artifact-source at it, and re-run. Nodes whose
        artifacts changed redeploy them (APPLIED); everything
        else is NO-CHANGE. Deploys go through Berth's
        blue-green slots, so services swap without dropping the box.
        Run --seal-check after.

Backups

Three things on the box constitute your state; everything else is reproducible from the installer and your artifact bundle:

What	Where	How

PostgreSQL	all platform data	pg_dumpall on a schedule you trust; standard PITR tooling applies. Restores have been exercised across major PG versions with a plain dump/restore.

Service env files	/opt/kapable/env/	Contains the box-local secrets generated at install (node 2). Back up encrypted; without them a restore regenerates secrets and re-issues sessions.

Owner credentials	/root/.kapable-bootstrap/	The first-org owner login persisted at install, mode 0600. Store it in your password manager and you can delete it from the box.

Where things live

Path	Contents

/opt/berth/	The deploy orchestrator: slots, per-service signing keys, service logs under data/logs/.

/opt/kapable/env/	Per-service environment files (secrets; mode-restricted).

/etc/caddy/ + /etc/caddy/conf.d/	The TLS edge. conf.d snippets are generated by the gateway service from its database — hand-edits are overwritten within a minute by design. Routing changes go through the platform, not the files.

/var/lib/postgresql/	The database cluster.

Next Steps

Verify

The seal check as your standing health probe.

Troubleshooting

Platform-wide diagnostic patterns.

Overview

Back to the start of the on-prem section.

Next

Getting Started · Authentication

---

# Changelog

Source: https://docs.kapable.ai/changelog
Section: Resources

Changelog

        API changes, new features, and deprecations across all Kapable services.

Versioning Policy

          All Kapable API endpoints use the /v1/ prefix. We follow these principles:

Additive changes are non-breaking. New fields in responses, new endpoints, and new optional query parameters are added without a version bump.

Removal or rename of fields is a breaking change. We announce these at least 30 days before enforcement, marked with a BREAKING badge below.

SDKs follow semver. @kapable/sdk (npm) and kapable-sdk (cargo) use semantic versioning. Minor bumps add features; patches fix bugs.

Deprecation headers. Deprecated endpoints return a X-Kapable-Deprecated header with a removal date. SDKs surface this as a console warning.

2026-06-11 — SDK v0.4.2 (TS) / v0.4.1 (Rust)

Native workspace scoping

TS: new KapableClient({ ..., workspaceId }) sends X-Workspace-Id on every request; per-request override via RequestOptions.workspaceId (null = org-wide opt-out); client.withWorkspace(id) derives a re-scoped client whose sub-clients all carry the scope.

Rust: KapableClient::new(url).workspace_id(ws) builder option; with_workspace_id / without_workspace_id derive re-scoped clients.

Apps deployments read API

auth.listDeployments(appId, {limit}) + auth.getDeployment(appId, deploymentId) (TS) / list_deployments + get_deployment (Rust) wrap GET /v1/apps/{app_id}/deployments (+ /{deployment_id}).

Also since 0.2.0

0.3.0: client.projects.* + project-bound key mint; workspace/project credential binding; workspace_scoped table creation.

0.4.0: workspaces module (CRUD, members, single-use invitations, custom roles, org audit), per-record read-only shares, simulate — "principal sees N of M rows" via the real RLS engine.

0.4.1 (TS): Node-compatible ESM dist/ — the package now imports cleanly in both Node and Bun (dual-runtime clean-room gate).

2026-06-09 — SDK v0.2.0, canonical API host, operator SDK

api.kapable.ai is live

One canonical base URL. https://api.kapable.ai now fronts all customer-tier services with /v1/* path routing — the base URL the SDKs always documented finally resolves.

Self-service credentials verified end-to-end: signup → mint key (POST /v1/auth/api-keys, secret shown once) → authenticated 200.

AI-readable docs published: llms.txt + llms-full.txt (352 endpoints, generated from the SDK coverage manifest).

SDK v0.2.0 published (npm + cargo)

@kapable/sdk@0.2.0 — 13 modules, 324 methods (was 7 modules at 0.1.0). New: ai, secrets, billing, wiki, harbor, warrant, security types.

kapable-sdk@0.2.0 (cargo) — full TypeScript parity (315 methods) including a new SSE module.

New: operator SDK. @kapable/ops-sdk@0.1.0 + kapable-ops-sdk@0.1.0 wrap the berth/foreman/host/gateway/admin tier; customer keys rejected at construction. See Operator SDK.

Cargo registry now live (anonymous read): sparse+https://git.kapable.dev/api/packages/kapable/cargo/.

Fixed from 0.1.0: 4 phantom org-repo methods (404 at runtime), 6 wrong-path Rust knowledge methods, Rust↔TS drift in every module. 0.1.0 remains installable but is deprecated — upgrade.

Docs

This site moved to docs.kapable.ai; quickstart rewritten around the verified golden path (note: org_slug is required on signup).

Honest scope documentation: what an sk_live_ key can and cannot reach today (see Authentication).

2026-05-20 — SDK v0.1.0

TypeScript & Rust SDKs Published

Published @kapable/sdk@0.1.0 to Forgejo npm registry — 7 modules, 176+ methods

Published kapable-sdk@0.1.0 to Forgejo cargo registry — 6 modules, 140 methods

SSE real-time module added to TypeScript SDK with auto-reconnection

API docs site deployed at docs.kapable.dev

Install

# TypeScript (add .npmrc first: @kapable:registry=https://git.kapable.dev/api/packages/kapable/npm/)
bun add @kapable/sdk

# Rust (add to .cargo/config.toml: [registries.kapable] index = "sparse+https://git.kapable.dev/api/packages/kapable/cargo/")
cargo add kapable-sdk --registry kapable

API Documentation Site

Launched unified API documentation site covering all five services

Added TypeScript SDK examples for every endpoint

Dark/light mode, responsive design, code copy buttons

2026-05-15

Comms

Added per-mailbox quota overrides (GET/PUT/DELETE /v1/mailboxes/{id}/quotas)

Added anomaly SSE feed (GET /v1/orgs/{org_id}/anomaly-feed)

MCP transport endpoint for agent onboarding (POST /v1/mcp/{token})

Knowledge

Added reversible merges -- unmerge endpoint for canonical entities

Predicate ontology lookup (GET /v1/knowledge/predicates/{name}/ontology)

Provenance graph BFS (GET /v1/knowledge/sources/{id}/provenance-graph)

2026-04-28

Board

Added Products resource (/v1/board/products)

Added Comments resource with target_type scoping

Sprint closures for retrospectives and release notes

Data

SSE change streams (GET /v1/sse) for real-time table notifications

Full-text search endpoint (POST /v1/{table}/search)

CSV import and JSON export endpoints

2026-04-01

Platform

Unified error response format across all services (kv2-core)

Cursor-based and offset pagination standardized

Health endpoints now probe database pools (not static "ok")

Store

Presigned URLs with external endpoint support

HEAD endpoint for object metadata

2026-03-15

Initial Release

Board API: stories, sprints, plans

Store API: buckets, objects

Data API: tables, row CRUD, bulk operations

Comms API: agents, mailboxes, channels, messages, rooms

Knowledge API: sources, pages, claims, edges, predicates

TypeScript SDK (@kapable/sdk) with typed clients

Next

Getting Started · Authentication