SDK Overview
TypeScript SDK for Protobox — tools, toolsets, knowledge, prompts, MCP, and chat
The Protobox SDK gives you typed, programmatic access to your workspace: define tools and toolsets, ingest and search knowledge, manage prompts, read your MCP configuration, and chat with your assistant. One package, typed end to end.
Installation
npm install @protoboxai/sdkSetup
import { ProtoboxSDK } from '@protoboxai/sdk';
const client = new ProtoboxSDK({
baseUrl: 'https://platform.protobox.ai',
apiKey: process.env.PROTOBOX_API_KEY,
});Store your API key in an environment variable. Never commit it to source control. baseUrl is required; apiKey (or jwtToken) authenticates the request.
The exported class is ProtoboxSDK (also available as Protobox). Every method returns an ApiResponse<T> wrapper:
const res = await client.tools.list();
if (res.success) {
console.log(res.data.tools);
} else {
console.error(res.message);
}What you can do
Build tools and toolsets
// Create a tool exposed over MCP
const created = await client.tools.create({
name: 'lookup_order',
description: 'Look up order details by order ID',
type: 'http',
inputSchema: {
type: 'object',
properties: {
order_id: { type: 'string', description: 'The order ID' },
},
required: ['order_id'],
},
configuration: {
http: {
method: 'GET',
url: 'https://api.yourstore.com/orders/{{order_id}}',
headers: { Authorization: 'Bearer {{secret:store_api_key}}' },
},
},
});
// Group tools into a toolset for a scoped MCP endpoint
const toolset = await client.toolsets.create({
name: 'Support Tools',
description: 'Tools for customer support clients',
tools: [created.data!.id],
});Ground answers with knowledge
// Add a document (text indexes immediately)
const entry = await client.knowledge.create({
title: 'Return Policy',
source: 'text',
content: 'Returns accepted within 30 days of purchase...',
});
// Search it
const results = await client.knowledge.search({
query: 'What is your return policy?',
mode: 'hybrid',
limit: 5,
});Chat with your assistant
// Open a session, send a message, end the session
const chat = await client.chat.session('agent_abc123');
const reply = await chat.send('What is your return policy?');
console.log(reply.message);
await chat.end();SDK modules
| Module | Description |
|---|---|
client.tools | Create, update, execute, and manage tools |
client.toolsets | Group tools into reusable collections |
client.knowledge | Ingest documents and search with hybrid/vector/text queries |
client.prompts | Manage versioned prompt templates |
client.mcp | Read MCP server configuration and status, list/call MCP tools |
client.chat | Open text chat sessions with your assistant |
client.workspace | List and inspect workspaces |
client.auth | Token exchange and validation |
client.health | API health checks |
Error handling
Every SDK error extends the base ChanlError class. Catch specific subclasses to branch on failure type.
import {
ProtoboxSDK,
ChanlError,
ValidationError,
NotFoundError,
AuthenticationError,
RateLimitError,
} from '@protoboxai/sdk';
const client = new ProtoboxSDK({
baseUrl: 'https://platform.protobox.ai',
apiKey: process.env.PROTOBOX_API_KEY,
});
try {
await client.tools.get('tool_123');
} catch (error) {
if (error instanceof NotFoundError) {
console.log('Not found:', error.message);
} else if (error instanceof ValidationError) {
console.log('Validation failed:', error.fieldErrors);
} else if (error instanceof AuthenticationError) {
console.log('Auth error — check your API key');
} else if (error instanceof RateLimitError) {
console.log('Rate limited, retry after:', error.retryAfter);
} else if (error instanceof ChanlError) {
console.log('API error:', error.code, error.message);
}
}The base error class is exported as ChanlError — it carries code, statusCode, details, and requestId. The product is Protobox; this internal class name is retained from the shared SDK lineage.
See the Error Reference for the full class hierarchy and type guards.
TypeScript types
Full type definitions ship with the package, so your editor gets autocompletion and compile-time safety.
import type {
Tool,
CreateToolInput,
ToolExecution,
Toolset,
CreateToolsetInput,
Knowledge,
CreateKnowledgeData,
SearchKnowledgeData,
SearchResponse,
Prompt,
McpConfigResponse,
ChatMessageResponse,
} from '@protoboxai/sdk';