SDK / API reference

How you talk to the Crew gateway depends on where your code runs. This page maps each surface to the right API.

There is no published TypeScript gateway-client npm package. The kirocrew-client method names below describe the canonical Gateway API surface — the same endpoints any client (including raw fetch) talks to.

Dashboard UI pages import permission-scoped hooks from @kirocrew/app-sdk, resolved at runtime via the host import map:

import { useAppApi, useAppEvents } from '@kirocrew/app-sdk'

function MyPage() {
  const api = useAppApi()               // permission-scoped GET/POST/PUT/PATCH/DELETE
  useAppEvents('notification', (e) => console.log(e))
  // ...
}

useAppApi() returns a client whose methods (get, post, put, patch, del) call the Gateway endpoints listed below, scoped to your permissions.api allowlist. Out-of-scope paths throw an error. The host injects auth automatically.

Import from @kirocrew/app-sdk/ui:

Card, CardTitle, Btn, SendBtn, Input, SearchInput, Badge, AimBadge, StatCard, Skeleton, ContentSkeleton, EmptyState, PageHeader, Toggle, InfoTip, SegmentedControl, MarkdownRenderer.

pip install kirocrew-client

Standalone async client using aiohttp. No dependency on the Crew main package.

from kirocrew_client import CrewClient

async with CrewClient(app_name="my-app") as mc:
    ok = await mc.ping()
    slots = await mc.list_slots()
    task_id = await mc.dispatch_agent_async("my-agent", "Analyze ticket T-123")
    result = await mc.get_task_result(task_id)

CrewClient(
    base_url="",              # default: http://localhost:{KIROCREW_PORT or 5476}
    token="",                 # optional for localhost
    app_name="",              # enables app-scoped storage + auto-auth
    timeout=30,               # request timeout seconds
    max_retries=3,
    retry_base_delay=1.0,
    message_length_limit=40000,
    on_auth_expired=None,     # async callback returning new token
)

When app_name is set and no explicit auth is provided, the client auto-reads the app secret from ~/.kiro/crew/apps/{name}/.app_secret and exchanges it for a short-lived token via POST /api/apps/{name}/token.

Method names below use snake_case for Python; TypeScript names shown for readability. The same endpoints are reachable via raw fetch() from Node or a browser.

All subscription methods return an unsubscribe function.

Event types (partial list): chat_chunk, chat_done, chat_message, chat_error, tool_call, notification, slots, slot_title, dashboard, log, refresh, approval, subagent_done, task_update, task_complete, proactive_notification, app_reload, error.

Silent background context — appears in the next user-initiated turn without triggering a response.

Options: { source?: string, ephemeral?: boolean, maxAge?: number }.

For app backends: verify a request was signed by the gateway reverse proxy.

Signature is HMAC-SHA256(timestamp:method:/api/path[?query]:sha256(body)) with the app secret as the key. Timestamps must be within ±60 s of now. Uses constant-time comparison.

For app-lifecycle operations beyond the client wrappers:

kirocrew-client also ships two helpers for install automation.

Validate and serialize app.json:

from kirocrew_client import AppManifest

m = AppManifest.from_dict({"name": "my-app", "version": "1.0.0", ...})
errors = m.validate()   # list[str] — empty if valid
data = m.to_dict()

Manage app installation via the Gateway REST API:

from kirocrew_client import CrewClient, AppLifecycle

async with CrewClient() as mc:
    lifecycle = AppLifecycle(mc)
    await lifecycle.install("/path/to/my-app")
    await lifecycle.enable("my-app")
    await lifecycle.disable("my-app")
    await lifecycle.uninstall("my-app")
    apps = await lifecycle.list()

Manage the Crew gateway process (start, stop, health check):

from kirocrew_client import GatewayManager

gm = GatewayManager(port=5476)
await gm.start()
healthy = await gm.is_healthy()
await gm.stop()

All kirocrew-client errors are CrewError instances with code, message, status, body.

from kirocrew_client import CrewError

try:
    await mc.send_message("slot-1", "hello")
except CrewError as e:
    print(e.code, e.message, e.status)