SDK

Use the UseBelha SDK from TypeScript, Python, or any HTTP client. It provides a simple interface for agent management and chat.

Installation

bash

npm install @usebelha/sdk

Initialize the client

bash

import { Belha } from '@usebelha/sdk';

const belha = new Belha({
  baseUrl: 'https://your-domain.com',
  apiKey: 'your-api-key',
});

Chat with an agent

bash

const result = await belha.agents.chat({
  agentId: 'ag_xxx',
  sessionId: 'user_123',
  message: 'Hello!',
});

console.log(result.text);

Chat with a template

bash

const result = await belha.agents.chat({
  templateId: 'tpl_search',
  sessionId: 'test',
  message: 'What is the latest AI news?',
});

console.log(result.text);

List agents

bash

const agents = await belha.agents.list();

Create an agent from template

bash

const agent = await belha.agents.createFromTemplate('tpl_search', {
  name: 'My Search Bot',
});

Authentication

The SDK supports three authentication methods:

Method	Use Case	Header
API Key	Server-to-server	`x-api-key`
Bearer Token	Mobile/SPA apps	`Authorization: Bearer ...`
Cookie	Same-origin browser	Automatic

Error Handling

bash

try {
  const result = await belha.agents.chat({
    agentId: 'ag_xxx',
    sessionId: 'test',
    message: 'Hello',
  });
} catch (error) {
  // The SDK throws BelhaApiError with { status, body }
  if (error?.name === 'BelhaApiError') {
    console.log('Request failed:', error.status, error.message);
  } else {
    console.log('Unexpected error:', error);
  }
}

Rate Limits

Mode	Limit
Demo (tenant_demo)	10 requests/minute
Authenticated	100 requests/minute
System (automation runs)	1000 requests/minute

Rate limit info is returned in response headers:

X-RateLimit-Remaining - Requests left in window
X-RateLimit-Reset - Seconds until reset