BLLM REST API

The BLLM API lets you programmatically execute agents, manage conversations, and query knowledge bases. All endpoints are under /api/v1/ and require API key authentication.

Base URL:

https://your-domain.com/api/v1

Authentication

Every request must include an API key. Create and manage keys under Settings → Public API keys (REST integrations). LLM provider keys are separate. Each key has scoped permissions, optional IP allowlists, and custom rate limits.

Pass the key via either header:

Authorization: Bearer bllm_pk_a1b2c3d4e5f6...
# or
X-API-Key: bllm_pk_a1b2c3d4e5f6...

Key format

Keys are prefixed with bllm_pk_ followed by 32 hex characters. The raw key is shown once at creation — only a SHA-256 hash is stored server-side.

Scopes

Each key is granted one or more scopes that control what it can access:

Error Handling

All errors return a consistent JSON envelope:

{
  "error": {
    "code": "API_KEY_INVALID",
    "message": "The provided API key is invalid.",
    "status": 401
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6g7h8",
    "timestamp": "2026-03-19T10:00:00.000Z"
  }
}

Error codes

Rate Limits

Each API key has a configurable rate limit (default: 60 requests/minute). Every response includes rate limit headers:

Pagination

List endpoints use cursor-based pagination. Pass ?limit=20&cursor=clx... as query parameters. Responses include a pagination object:

{
  "data": [...],
  "pagination": {
    "cursor": "clx...",
    "hasMore": true,
    "limit": 20
  },
  "meta": { ... }
}

Returns a paginated list of published agents accessible to this API key.

Query parameters

Response

{
  "data": [
    {
      "id": "clx...",
      "name": "Support Agent",
      "description": "Handles customer questions",
      "published": true,
      "createdAt": "2026-03-01T00:00:00.000Z",
      "updatedAt": "2026-03-15T12:00:00.000Z"
    }
  ],
  "pagination": { "cursor": null, "hasMore": false, "limit": 20 },
  "meta": { "requestId": "req_...", "timestamp": "..." }
}

Returns details for a single published agent.

Path parameters

Response

{
  "data": {
    "id": "clx...",
    "name": "Support Agent",
    "description": "Handles customer questions",
    "published": true,
    "createdAt": "2026-03-01T00:00:00.000Z",
    "updatedAt": "2026-03-15T12:00:00.000Z"
  },
  "meta": { ... }
}

Execute an agent. Creates a new conversation (or continues an existing one) and returns the agent's response events.

Request body

{
  "userInput": "What is my order status?",
  "conversationId": "clx..."
}

Response

{
  "data": {
    "events": [
      { "type": "message", "content": "Let me look that up for you..." },
      { "type": "message", "content": "Your order #1234 shipped on March 15." },
      { "type": "done" }
    ],
    "newState": { "order_id": "1234", "status": "shipped" },
    "currentNodeId": null,
    "conversationId": "clx...",
    "success": true
  },
  "meta": { ... }
}

Event types: message (agent text), wait_input (agent is waiting for user), error (execution error), done (flow finished successfully — omitted when the run ends with errors). handoff may appear for human handoff flows.

success: true when the run completed with a done event and no terminal errors; false on failure; omitted when the run is only paused on wait_input.

List conversations for your agents. Scoped to the API key's allowed agents if configured.

Query parameters

Response

{
  "data": [
    {
      "id": "clx...",
      "agentId": "clx...",
      "agentName": "Support Agent",
      "title": "API Conversation",
      "status": "ACTIVE",
      "createdAt": "...",
      "updatedAt": "..."
    }
  ],
  "pagination": { ... },
  "meta": { ... }
}

Create a new conversation for a published agent.

Request body

Response (201)

{
  "data": {
    "id": "clx...",
    "agentId": "clx...",
    "title": "API Conversation",
    "status": "ACTIVE",
    "createdAt": "..."
  },
  "meta": { ... }
}

Get details for a single conversation.

Response

{
  "data": {
    "id": "clx...",
    "agentId": "clx...",
    "agentName": "Support Agent",
    "title": "API Conversation",
    "status": "ACTIVE",
    "createdAt": "...",
    "updatedAt": "..."
  },
  "meta": { ... }
}

List messages in a conversation, ordered oldest-first.

Query parameters

Response

{
  "data": [
    { "id": "clx...", "role": "user", "content": "Hello", "createdAt": "..." },
    { "id": "clx...", "role": "assistant", "content": "Hi! How can I help?", "createdAt": "..." }
  ],
  "pagination": { ... },
  "meta": { ... }
}

Send a message in an existing conversation. This triggers agent execution using the conversation's agent and returns the response events.

Request body

{ "content": "What is my order status?" }

Response

Same format as the Execute Agent response — includes events, newState, and conversationId.

List knowledge bases belonging to the API key's owner.

Response

{
  "data": [
    {
      "id": "clx...",
      "name": "Product Docs",
      "description": "Internal documentation",
      "documentCount": 12,
      "createdAt": "...",
      "updatedAt": "..."
    }
  ],
  "pagination": { ... },
  "meta": { ... }
}

Run a semantic search against a knowledge base. Returns the most relevant document chunks with similarity scores.

Request body

{ "query": "How do I reset my password?", "limit": 3 }

Response

{
  "data": {
    "query": "How do I reset my password?",
    "results": [
      {
        "content": "To reset your password, go to Settings > Security...",
        "similarity": 0.92,
        "metadata": null
      }
    ],
    "total": 1
  },
  "meta": { ... }
}

API Key Management

These endpoints are authenticated via your session (browser login), not API keys. Use them from the dashboard or your own admin tooling.

{
  "name": "Production Key",
  "scopes": ["agents:read", "agents:execute", "conversations:write"],
  "allowedAgentIds": ["clx..."],
  "allowedIPs": ["203.0.113.0/24"],
  "expiresAt": "2027-01-01T00:00:00Z",
  "rateLimitPerMinute": 100
}