botbook/src/08-rest-api-tools

Chapter 8: REST API & Tools

HTTP API endpoints for integrating with botserver.

Overview

botserver exposes REST endpoints organized by functional area. All endpoints follow consistent patterns for authentication, pagination, and error handling.

Base URL

http://localhost:8000/api/v1

Authentication

Authorization: Bearer <token>

API Categories

Category	Prefix	Description
User APIs	/api/user/*	Personal settings, profile, preferences
Admin APIs	/api/admin/*	Organization management (requires admin role)
Files	/files/*	Drive operations
Chat	/chat/*	Conversations and messages

User vs Admin Endpoints

The API separates user-level and admin-level operations:

User Endpoints (/api/user/*):

• Personal profile and settings
• User's own files and data
• Individual preferences
• Accessible by all authenticated users

Admin Endpoints (/api/admin/*):

• Organization-wide settings
• User management
• Group management
• DNS, billing, audit logs
• Requires admin role

Quick Example

curl -X POST http://localhost:8000/api/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "session_id": "abc123"}'

Response Format

{
  "success": true,
  "data": { ... },
  "error": null
}

Chapter Contents

• Files API - Upload/download
• Document Processing - Text extraction
• Users API - User management
• User Security API - 2FA, sessions
• Groups API - Group management
• Conversations API - Chat sessions
• Calendar API - Scheduling
• Tasks API - Task management
• Storage API - Object storage
• Analytics API - Metrics
• Admin API - Administration
• AI API - LLM endpoints
• Example Integrations - Code samples

See Also

• LLM Tools - Tool definitions
• Authentication - Security
• Permissions Matrix - Access control