Quick Start

Create an organization, generate an API key, and chat with your first agent in minutes.

Try It in Demo Mode

Open the Demo Dashboard (no sign-in required)
Template chat is available via API using x-tenant-id: tenant_demo (rate limited)

bash

# Demo template chat (no account)
curl -X POST "https://dev.usebelha.com/api/agents?template=tpl_basic&action=chat" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: tenant_demo" \
  -d '{"sessionId": "demo", "message": "Hello!"}'

Step 1: Create Your Account

Create your user account

Use the dashboard and APIs

Step 2: Create an Organization & API Key

Go to Organization and create an organization. Then create an API key for SDK/server access.

API keys are scoped to your org

Use x-api-key for server-to-server requests. Keep keys secret.

Step 3: Create an Agent

bash

curl -X POST "https://dev.usebelha.com/api/agents" \
  -H "x-api-key: $BELHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "systemPrompt": "You are a helpful assistant.",
    "tools": { "googleSearch": { "enabled": true } },
    "status": "active"
  }'

Step 4: Chat with Your Agent

bash

curl -X POST "https://dev.usebelha.com/api/agents?id=ag_xxx&action=chat" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BELHA_API_KEY" \
  -d '{"sessionId": "session_123", "message": "Hello!"}'

Step 5: Automations (Optional)

To run an agent from cron/webhooks, enable system calls on the agent and trigger /api/internal/run-automation. See Automations for more.

bash

# Allow system runs for this agent
curl -X PUT "https://dev.usebelha.com/api/agents?id=ag_xxx" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BELHA_API_KEY" \
  -d '{"allowedCallers":["user","system"]}'

# Trigger a system run (idempotent)
curl -X POST "https://dev.usebelha.com/api/internal/run-automation" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BELHA_API_KEY" \
  -H "x-trigger-type: schedule" \
  -H "x-automation-id: daily-run" \
  -d '{"target":"ag_xxx","input":{"message":"Run scheduled workflow"},"idempotencyKey":"daily-2025-01-01"}'

Step 6: Add Knowledge (Optional)

Create a knowledge store for the agent:

bash

curl -X POST "https://dev.usebelha.com/api/knowledge" \
  -H "x-api-key: $BELHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "ag_xxx", "displayName": "Product Docs"}'

Upload a document:

bash

curl -X POST "https://dev.usebelha.com/api/knowledge" \
  -H "x-api-key: $BELHA_API_KEY" \
  -F "agentId=ag_xxx" \
  -F "file=@./handbook.pdf" \
  -F "displayName=Handbook"

Next Steps

Authentication - API keys, bearer tokens, and org tenancy
Tools - Search, code execution, HTTP actions, and File Search
Channels - API + widget embedding
SDK - Minimal TypeScript and Python clients

Self-hosting?

See the repository README.md for local setup, env vars, and deployment.