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.

In-Gateway hooks only. These helpers are available to backend.hooks.* entry points that run inside the Gateway. Standalone backend processes using kirocrew-client do not receive this context.

Backend hooks receive two helpers on their app context:

Call ctx.scrub.outbound before an app logs or transmits model-authored content. ctx.audit.record is best-effort and is for access decisions, grants, denials, and mutations the app needs to reconstruct later.

Declare runtime UI extensions under contributes in app.json:

The host validates each declaration and mounts only enabled apps. See the manifest reference for the complete field schema and limits.

An MCP server UI routed through the Gateway stub inherits the active dashboard colors, fonts, radii, and shadows, and receives theme changes while mounted.

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)