Setup Guide

This guide covers everything you need to go from zero to a working Imbrace SDK integration — installation, credentials, environments, and service URL overrides.

---

System Requirements

Requirement	Minimum version
Node.js	18.0.0+
npm	8.0.0+
Python	3.9+
pip	23.0+

---

Installation

TypeScript

From npm registry:

npm install @imbrace/sdk
# or
yarn add @imbrace/sdk
# or
pnpm add @imbrace/sdk

Monorepo / local development:

# Step 1 — install dependencies and build
cd ts
npm install
npm run build

# Step 2 (optional) — link globally to use in another project on the same machine
npm link

Then in your external project:

npm link @imbrace/sdk

Verify:

import { ImbraceClient } from "@imbrace/sdk";
console.log("SDK loaded:", typeof ImbraceClient); // 'function'

Python

From PyPI:

pip install imbrace
# or
uv add imbrace

Monorepo / local development (editable mode):

cd py
pip install -e ".[dev]"

The [dev] flag installs: pytest, pytest-asyncio, pytest-httpx, ruff, mypy.

Verify:

from imbrace import ImbraceClient
print("SDK loaded:", ImbraceClient)

---

Configure Credentials

Create a .env file

The SDK does not auto-read environment variables — you pass credentials directly to the constructor. A .env file is a user convention for storing secrets; use dotenv or your framework’s env loader to read them.

# Credentials
IMBRACE_API_KEY=your_api_key_here
IMBRACE_ACCESS_TOKEN=your_jwt_token_here

# Organization ID — sent with every request
IMBRACE_ORGANIZATION_ID=your_org_id_here

# Optional: override the gateway URL directly
IMBRACE_BASE_URL=https://app-gatewayv2.imbrace.co

Get an API Key

Option 1 — Imbrace Portal: log in and go to Settings → API Keys.

Option 2 — via API (requires an existing access token):

curl -X POST https://app-gatewayv2.imbrace.co/private/backend/v1/third_party_token \
  -H "x-access-token: <your_existing_token>" \
  -H "Content-Type: application/json" \
  -d '{"expirationDays": 30}'

The value you need is response.apiKey.apiKey.

---

Environments

Name	Gateway URL	Use when
develop	https://app-gateway.dev.imbrace.co	Internal development
sandbox	https://app-gateway.sandbox.imbrace.co	Integration testing
stable	https://app-gatewayv2.imbrace.co	Production (default)

Switch environments via the env constructor option, or override the URL directly with baseUrl:

TypeScript

const client = new ImbraceClient({ env: "sandbox" });

Python

client = ImbraceClient(env="sandbox")

---

Initialize the Client

TypeScript

import { ImbraceClient } from "@imbrace/sdk";

// Server-side — API Key
const client = new ImbraceClient({
  apiKey:         process.env.IMBRACE_API_KEY,
  organizationId: process.env.IMBRACE_ORGANIZATION_ID,
  baseUrl:        "https://app-gatewayv2.imbrace.co", // or use env: "stable"
});

// Client-side — Access Token (e.g. after OTP login)
const client = new ImbraceClient({
  accessToken: process.env.IMBRACE_ACCESS_TOKEN,
  baseUrl:     "https://app-gatewayv2.imbrace.co",
});

// OTP login flow
const anon = new ImbraceClient({ baseUrl: "https://app-gatewayv2.imbrace.co" });
await anon.requestOtp("user@example.com");
await anon.loginWithOtp("user@example.com", "123456");
// Token is stored automatically on the client

Python (sync)

import os
from imbrace import ImbraceClient

# Server-side — API Key
client = ImbraceClient(
    api_key=os.environ["IMBRACE_API_KEY"],
    organization_id=os.environ.get("IMBRACE_ORGANIZATION_ID"),
    env="stable",
)

# Client-side — Access Token
client = ImbraceClient(
    access_token="eyJhbGci...",
    organization_id="org_xxx",
)

# OTP login flow
anon = ImbraceClient(env="stable")
anon.request_otp("user@example.com")
anon.login_with_otp("user@example.com", "123456")

Python (async)

from imbrace import AsyncImbraceClient

async def main():
    async with AsyncImbraceClient(api_key="sk-...") as client:
        me = await client.platform.get_me()
        print(me)

---

Quick Usage Examples

TypeScript

import { ImbraceClient } from '@imbrace/sdk'

const client = new ImbraceClient({ apiKey: process.env.IMBRACE_API_KEY })

// Get current user
const me = await client.platform.getMe()

// List channels
const channels = await client.channel.listChannels()

// Send a message
await client.channel.sendMessage('conv_123', { content: 'Hello!', type: 'text' })

// AI completion
const result = await client.ai.complete({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Summarize this.' }],
})

// AI streaming
for await (const chunk of client.ai.stream({ model: 'gpt-4o', messages: [...] })) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '')
}

// AI Agent — streaming chat
const response = await client.aiAgent.streamChat({
  id: 'chat_id',
  assistant_id: 'asst_abc',
  organization_id: 'org_abc',
  messages: [{ role: 'user', content: 'Hello' }],
})

Python

from imbrace import ImbraceClient

with ImbraceClient(api_key="sk-...") as client:
    # Get current user
    me = client.platform.get_me()

    # List channels and boards
    channels = client.channel.list_channels()
    boards   = client.boards.list()
    items    = client.boards.get_items(boards[0]["id"])

    # AI completion
    result = client.ai.complete(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}],
    )

    # AI Agent — streaming chat
    response = client.ai_agent.stream_chat({
        "id": "chat_id",
        "assistant_id": "asst_abc",
        "organization_id": "org_abc",
        "messages": [{"role": "user", "content": "Hello"}],
    })
    for line in response.iter_lines():
        print(line)

---

Override Service URLs

Use this when a microservice runs at a different address (e.g. local dev, dedicated staging).

TypeScript

const client = new ImbraceClient({
  env: "develop",
  services: {
    aiAgent: "http://localhost:4000/ai-agent",
    dataBoard: "http://localhost:3001/data-board",
    channelService: "http://localhost:3002/channel-service",
  },
});

Python

client = ImbraceClient(
    env="develop",
    services={
        "ai_agent":       "http://localhost:4000/ai-agent",
        "data_board":     "http://localhost:3001/data-board",
        "channel_service":"http://localhost:3002/channel-service",
    },
)

All valid service keys:

Python key	TypeScript key	Service
gateway	gateway	App Gateway
platform	platform	Platform service
channel_service	channelService	Channel service
data_board	dataBoard	Data Board
backend	backend	Board/Items backend (/v1/backend)
ips	ips	IPS service
ai	ai	AI service
marketplaces	marketplaces	Marketplace service
file_service	fileService	File service
message_suggestion	messageSuggestion	Message Suggestion service
predict	predict	Predict service
activepieces	activepieces	ActivePieces
ai_agent	aiAgent	AI Agent service

---

Troubleshooting

Cannot find package '@imbrace/sdk'

Package is not linked. Re-run from ts:

npm link
cd /path/to/your-project && npm link @imbrace/sdk

ERR_MODULE_NOT_FOUND for files in dist/

Package has not been built yet:

cd ts && npm run build

ModuleNotFoundError: No module named 'imbrace'

cd py && pip install -e ".[dev]"

401 Unauthorized

API Key expired or invalid. Generate a new one:

curl -X POST https://app-gatewayv2.imbrace.co/private/backend/v1/third_party_token \
  -H "x-access-token: <your_existing_token>" \
  -H "Content-Type: application/json" \
  -d '{"expirationDays": 30}'

UserWarning: ImbraceClient: no credentials provided

No api_key or access_token passed. If intentional (e.g. login-only flow), ignore this warning. Otherwise check your .env file.