Skip to content
Imbrace SDK

Overview

The Imbrace SDK is the official client for the Imbrace Gateway, available in TypeScript and Python. Both SDKs wrap the same Gateway API with the same resource namespaces, the same auth model, and the same retry/error semantics — pick whichever language fits your stack.

Key Features

FeatureDetail
Type safetyTypeScript types and Python type hints across every resource
Two credential typesapiKey or accessToken — see Authentication
Auto retry429 and 5xx retry with exponential backoff, no config needed
Streaming AISSE / async iterator for streamChat and AI completions
Async & sync (Py)ImbraceClient (sync) and AsyncImbraceClient (async)
Cancellation (TS)AbortSignal propagation for in-flight cancellation

Install

Current version: @imbrace/sdk v1.4.0 (npm) · imbrace v1.2.1 (PyPI)

Terminal window
npm install @imbrace/sdk

Hello, world

import { ImbraceClient } from "@imbrace/sdk"


const client = new ImbraceClient({ apiKey: "api_your_key" })
const me = await client.platform.getMe()

Available resources

Every namespace is on both SDKs. Methods follow the language conventions — client.aiAgent.streamChat() in TS, client.ai_agent.stream_chat() in Python.

NamespaceMicroservicePurpose
client.aiAgent / client.ai_agentai-agentStreaming AI chat, embeddings, parquet, chat-client sub-API
client.chatAi / client.chat_aiai-service-v2AI Agent CRUD (create/update/delete/list AI agents)
client.documentAi / client.document_aiai-service-v2Document parsing, extraction, and AI over files
client.agentmarketplaceAI agent templates + use-cases (atomic create of assistant + workflow + channel via createUseCase)
client.workflowsworkflow-engineWorkflow automation — flows, triggers, runs
client.boardsdata-boardCRM boards — CRUD, items, fields, search, segments, CSV; KnowledgeHub folders & files
client.platform, client.organizations, client.teamsplatformUsers, organizations, teams, business units
client.contacts, client.conversations, client.messages, client.channel, client.categories, client.campaign, client.outboundchannel-serviceContacts, conversations, messaging, channel/campaign management
client.marketplacemarketplaceMarketplace files, email templates, channel workflows
client.fileServicefile-serviceContext-aware file uploads (board attachments, contact files, financial files, presigned URLs)
client.ips, client.scheduleipsInter-process scheduling / automation rules
client.aiai-service-v2OpenAI-compatible completions, embeddings, providers, guardrails
client.authplatform / legacy backendSign-in (OTP, password, SSO), token exchange

For the complete list and method reference, see Resources.

The full API surface — client.api (TypeScript)

Since v1.3.0 the TypeScript SDK also ships a generated surface covering every operation the Imbrace services expose to AI agents — 272 operations across 5 services, generated from their agent-tools OpenAPI specs:

const boards = await client.api.dataBoard.listBoards<{ data: Board[] }>();
const flows  = await client.api.workflow.listFlows();

Namespaces: client.api.dataBoard, .channel, .platform, .marketplace, .workflow.

It is complete and always in sync with the deployed services, but most operations return unknown (their specs declare no response schema) — pass a type argument when you know the shape. Prefer the hand-written resources above when they cover your call; reach for client.api for anything they don’t, instead of hand-rolling a fetch.

The same operation registry powers the gateway’s hosted MCP server and the CLI’s imbrace mcp command, both of which expose these operations as MCP tools for AI agents.

When to pick which credential

API Key (api_...)Access Token (eyJ...)
How you get itImbrace Dashboard → Generate External TokenOTP login (requestOtp / loginWithOtp)
Best forServer scripts, backend integrations, CI pipelinesUser-facing apps where each end-user logs in
ScopeYour organization — full API accessPer-user session — scoped to that user’s permissions

Full decision tree: Authentication → · Get an API Key →

Next steps