Bot Agent Runtime API

This API provides runtime services for bot agents including LLM chat completions, model catalog, token management, and workspace access.

Interactive Documentation

Overview

The Runtime API provides the core services that bot agents use during execution. All endpoints require JWT Bearer authentication obtained through the OAuth 2.0 device flow or bootstrap token exchange.

Key Features

• LLM Chat: OpenAI-compatible chat completions with streaming support
• Model Catalog: List available LLM models and their capabilities
• Token Management: Bootstrap and refresh agent access tokens
• Workspace Access: Download project workspace files

Endpoints

LLM Chat Completion

POST /api/runtime/chat

OpenAI-compatible chat completion endpoint with streaming support.

Headers:

Authorization: Bearer <access_token>
x-conversation-id: <optional_conversation_id>
x-bot-agent-product-id: <agent_id>

Request:

{
  "llmId": "llm",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" }
  ],
  "temperature": 0.7,
  "stream": false
}

Features:

• Streaming and non-streaming modes
• Automatic model failover
• Request rate limiting
• Priority conversation support
• Token usage tracking

List LLM Models

GET /api/runtime/llms

Get the catalog of available LLM models and their capabilities.

Headers:

Authorization: Bearer <access_token>
x-bot-agent-product-id: <agent_id>

Response:

{
  "projectId": "proj-123",
  "defaultLlmId": "llm",
  "llms": [
    {
      "id": "llm",
      "name": "Standard LLM",
      "enabled": true,
      "supportsTools": true,
      "supportsImages": false,
      "contextWindowTokens": 128000,
      "maxOutputTokens": 4096,
      "primaryProviderId": "openai",
      "primaryProviderName": "OpenAI",
      "primaryModel": "gpt-4o",
      "tags": null
    }
  ],
  "refreshedAt": 1672531200000
}

Token Management

Bootstrap Token Exchange

POST /api/runtime/session/exchange

Exchange a bootstrap token for access and refresh tokens.

Request:

{
  "bootstrapToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Refresh Access Token

POST /api/runtime/session/refresh

Exchange a refresh token for new tokens.

Request:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Download Workspace

GET /api/runtime/workspace?projectId=<project_id>

Download the entire project workspace as a ZIP archive.

Headers:

Authorization: Bearer <access_token>

Response:

Content-Type: application/zip

Authentication

All endpoints require a valid JWT access token in the Authorization header:

Authorization: Bearer <access_token>

Access tokens are obtained via:

• OAuth 2.0 device flow
• Bootstrap token exchange

Rate Limiting

• Monthly request limits per project (configurable)
• API key overrides can bypass project limits for specific conversations
• Priority conversations bypass latency-based failover

Failover & Reliability

• Automatic model failover on backend unavailability
• Latency-based failover for non-priority conversations
• Sticky per-conversation failover on client disconnects

Token Lifetimes

Next Steps

• View full interactive documentation with try-it-out functionality
• OAuth 2.0 API - Device authorization flow
• Projects API - Project management