Botz API

API Documentation

Botz Platform API Documentation

Complete REST API reference for the Botz platform. Create, manage, and interact with custom AI bots using simple HTTP requests. Perfect for building AI-powered applications with minimal setup.

🚀 Explore Demo Applications
Base URL Main API https://botz.pages.dev
Live API Explorer Experiment with Create, Update, Chat, Delete, List, Info APIs https://botz.pages.dev/api-explorer
User Admin Panel Manage your Botz via a user friendly interface https://botz.pages.dev/admin-panel
Vibe Guide Create Your own AI-powered apps with Botz https://botz.pages.dev/botz-vibe-guide.md
Demo Apps Explore some vibe coded Botz-enabled apps https://botz.pages.dev/demos
Landing Page Main platform overview and getting started https://botz.pages.dev/landing.html

Authentication

All Botz API endpoints require an auth token for an individual or team workspace. Tokens available on request to the Digital Innovation Team.

Authorization Header
Authorization: Bearer your-auth-token

Token-Based Isolation

Each auth token creates a completely isolated environment:

  • Token A can create "my-bot"
  • Token B can also create "my-bot"
  • These are completely separate bots that cannot access each other
  • Enables separate workspace environments for multi-tenant applications and user isolation
POST
/v1/{bot_id}/create

Creates a new AI bot with custom configuration.

Request

HTTP Request
POST /v1/{bot_id}/create Content-Type: application/json Authorization: Bearer your-token
Request Body (JSON)
{ "config": { "model": "gpt-4.1-mini", "instructions": "You are a helpful assistant specialized in...", "web_search": true, "max_tokens": 1000, "temperature": 0.7, "name": "My Assistant", "description": "Description of what this bot does" } }

Required Fields

model Required
AI model (see supported models below)
instructions Required
System prompt (1-5000 characters)
web_search Required
Boolean for web search capability
max_tokens Required
Response length limit (1-2000)

Optional Fields

temperature Optional
Creativity level (0-2, default 0.7)
name Optional
Display name (max 100 chars)
description Optional
Bot description (max 300 chars)

Response

Response Body (JSON)
{ "bot_id": "my-assistant", "config": { "model": "gpt-4.1-mini", "instructions": "You are a helpful assistant...", "web_search": true, "max_tokens": 1000, "temperature": 0.7, "name": "My Assistant", "description": "Description of what this bot does", "created_at": "2024-08-04T10:30:00.000Z", "updated_at": "2024-08-04T10:30:00.000Z" }, "endpoints": { "info": "https://botz-api.pages.dev/v1/my-assistant/info", "chat": "https://botz-api.pages.dev/v1/my-assistant/chat", "update": "https://botz-api.pages.dev/v1/my-assistant/update", "delete": "https://botz-api.pages.dev/v1/my-assistant/delete" }, "message": "Bot created successfully", "timestamp": "2024-08-04T10:30:00.000Z" }
POST
/v1/bots/list

Returns all bots in your token-scoped namespace.

Request

HTTP Request
POST /v1/bots/list Content-Type: application/json Authorization: Bearer your-token
Request Body (JSON)
{}

Response

Response Body (JSON)
{ "bots": [ { "bot_id": "my-assistant", "name": "My Assistant", "description": "A helpful AI assistant", "model": "gpt-4.1-mini", "created_at": "2024-08-04T10:30:00.000Z", "updated_at": "2024-08-04T10:30:00.000Z", "web_search": true, "max_tokens": 1000, "temperature": 0.7 } ], "total": 1, "timestamp": "2024-08-04T10:30:00.000Z" }
POST
/v1/{bot_id}/chat

Send a message to a bot and receive a response.

Request

Request Body (JSON)
{ "message": "Hello, can you help me with...", "previous_response_id": "resp_abc123def456", "oai_response": false }

Fields

message Required
User message (max 10,000 characters)
previous_response_id Optional
ID from previous response for conversation continuity
oai_response Optional
Include full OpenAI Responses API response (default: false)

Response

Default Response (oai_response=false)
{ "response": "AI response text here...", "response_id": "resp_abc123def456", "bot_id": "my-assistant", "model": "gpt-4.1-mini", "usage": { "input_tokens": 25, "output_tokens": 150, "total_tokens": 175, "input_tokens_details": { "cached_tokens": 10 }, "output_tokens_details": { "reasoning_tokens": 50 } } }
Enhanced Response (oai_response=true)
{ "response": "AI response text here...", "response_id": "resp_abc123def456", "bot_id": "my-assistant", "model": "gpt-4.1-mini", "usage": { "input_tokens": 25, "output_tokens": 150, "total_tokens": 175 }, "oai_response": { "id": "resp_abc123def456", "object": "response", "created_at": 1691140500, "model": "gpt-4.1-mini", "output": [ { "id": "msg_abc123", "type": "message", "role": "assistant", "content": [ { "type": "text", "text": "AI response text here...", "annotations": [] } ] } ], "usage": { "input_tokens": 25, "output_tokens": 150, "total_tokens": 175 }, "reasoning": { "effort": "medium", "summary": "Response reasoning summary" } } }

Response Options

Default (oai_response=false)
Clean response with basic usage statistics and bot info
Enhanced (oai_response=true)
Includes full OpenAI Responses API metadata, web search annotations, tool usage details, reasoning information, and complete response structure
POST
/v1/{bot_id}/info

Retrieve configuration and metadata for a specific bot.

Request

Request Body (JSON)
{}

Response

Response Body (JSON)
{ "bot_id": "my-assistant", "config": { "model": "gpt-4.1-mini", "instructions": "You are a helpful assistant...", "web_search": true, "max_tokens": 1000, "temperature": 0.7, "name": "My Assistant", "description": "Description of what this bot does", "created_at": "2024-08-04T10:30:00.000Z", "updated_at": "2024-08-04T10:30:00.000Z" }, "timestamp": "2024-08-04T10:30:00.000Z" }
POST
/v1/{bot_id}/update

Update an existing bot's configuration.

Request

Request Body (JSON)
{ "config": { "temperature": 0.9, "max_tokens": 1500, "instructions": "Updated instructions...", "name": "Updated Bot Name" } }

Notes

  • Only include fields you want to update
  • All fields from the create endpoint are supported
  • updated_at timestamp will be automatically set

Response

Response Body (JSON)
{ "bot_id": "my-assistant", "config": { "model": "gpt-4.1-mini", "instructions": "Updated instructions...", "web_search": true, "max_tokens": 1500, "temperature": 0.9, "name": "Updated Bot Name", "description": "Description of what this bot does", "created_at": "2024-08-04T10:30:00.000Z", "updated_at": "2024-08-04T11:15:00.000Z" }, "message": "Bot updated successfully", "timestamp": "2024-08-04T11:15:00.000Z" }
POST
/v1/{bot_id}/delete

Permanently delete a bot and all its data.

Request

Request Body (JSON)
{ "confirm": true }

Fields

confirm Required
Must be true to confirm deletion

Response

Response Body (JSON)
{ "bot_id": "my-assistant", "message": "Bot deleted successfully", "timestamp": "2024-08-04T11:20:00.000Z" }
GET
/v1/{bot_id}/webchat

Access a web-based chat interface for a bot.

Request

HTTP Request
GET /v1/{bot_id}/webchat?token=your-token&message=optional-initial-message

Query Parameters

token Required
Your auth token
message Optional
Optional initial message to send

Response

Returns an HTML web chat interface for interacting with the bot.

Supported Models

Model Type Best For Relative Cost
gpt-5 Next-Gen Premium Most advanced reasoning and analysis Highest
gpt-5-mini Next-Gen Balanced Advanced performance, cost-effective Medium-High
gpt-5-nano Next-Gen Lightweight Fast next-gen responses Medium
gpt-4.1 Premium Complex reasoning, analysis High
gpt-4.1-mini Balanced General assistance, cost-effective Medium
gpt-4.1-nano Lightweight Simple tasks, fastest response Low-Medium
gpt-4o Multimodal Text + vision tasks High
gpt-4o-mini Efficient Quick multimodal tasks Medium
o3 Reasoning Advanced reasoning and problem-solving Very High
o3-mini Reasoning (Efficient) Fast reasoning tasks High

HTTP Status Codes

Code Meaning Description
200 OK Request successful
201 Created Bot created successfully
400 Bad Request Validation error in request
401 Unauthorized Invalid or missing auth token
404 Not Found Bot doesn't exist
409 Conflict Bot already exists (create only)
500 Internal Server Error Server error
502 Bad Gateway AI service error
503 Service Unavailable API key not configured

Bot ID Requirements

  • 3-50 characters
  • Alphanumeric characters, underscores, and hyphens only
  • No spaces
  • Must be unique within your token scope
  • Examples: my-bot, customer_support, data-analyst-v2

Conversation Management

The API uses OpenAI's Responses API for conversation continuity:

New Conversation: Send message without previous_response_id
Continue Conversation: Include previous_response_id from previous response
Context Preservation: All conversation history is maintained automatically