Bronny AI Assistant - API Documentation

Overview

The Bronny AI Assistant provides a comprehensive REST API built with FastAPI, offering endpoints for chat interactions, agent management, memory operations, file processing, and Google services integration. The API supports both synchronous and streaming responses with WebSocket support for real-time communication.

Base URL

http://localhost:8000

Authentication

All API endpoints require authentication via Bearer token:

Authorization: Bearer <your-jwt-token>

Response Format

All API responses follow a consistent format:

{
  "success": true,
  "data": { ... },
  "message": "Optional message",
  "timestamp": "2024-01-01T00:00:00Z"
}

Error responses:

{
  "success": false,
  "error": "Error description",
  "details": "Additional error details",
  "timestamp": "2024-01-01T00:00:00Z"
}

Endpoints

Health Check

GET /health

Check API health and system status.

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "agents_available": 8,
  "database_connected": true,
  "google_services_authenticated": true
}

Chat Endpoints

POST /api/chat

Send a message to an agent and receive a response.

Request Body:

{
  "message": "Hello, can you help me research AI trends?",
  "agent_id": "orchestrator",
  "session_id": "session_123",
  "stream": false
}

Parameters:

message (string, required): The message to send to the agent
agent_id (string, optional): Agent ID to use (default: "orchestrator")
session_id (string, optional): Session ID for conversation continuity
stream (boolean, optional): Enable streaming response (default: false)

Response (Non-streaming):

{
  "agent_used": "orchestrator",
  "response": {
    "content": "I'd be happy to help you research AI trends! Let me gather some current information...",
    "thought": "User wants to research AI trends, I should use the research agent to gather current information",
    "tool_calls": [
      {
        "name": "web_search",
        "args": {
          "query": "AI trends 2024",
          "max_results": 5
        }
      }
    ]
  },
  "success": true
}

Response (Streaming): Server-Sent Events (SSE) format:

data: {"agent_used": "orchestrator"}

data: {"thought": "I need to research current AI trends for the user"}

data: {"tool_calls": [{"name": "web_search", "args": {"query": "AI trends 2024"}}]}

data: {"content": "Based on my research, here are the key AI trends in 2024..."}

Agent Management

GET /api/agents

List all available agents.

Response:

{
  "orchestrator": {
    "agent_id": "orchestrator",
    "name": "Orchestrator",
    "description": "Coordinates multiple agents and manages workflows",
    "model_id": "gemini-2.5-flash",
    "tools_count": 12,
    "memory_enabled": true,
    "tools": ["web_search", "file_search", "memory_search", "google_gmail", "google_calendar"]
  },
  "researcher": {
    "agent_id": "researcher",
    "name": "Research Agent",
    "description": "Web search, fact-checking, and analysis capabilities",
    "model_id": "gemini-2.5-flash",
    "tools_count": 8,
    "memory_enabled": true,
    "tools": ["web_search", "arxiv_search", "wikipedia_search", "fact_check"]
  }
}

GET /api/agents/{agent_id}

Get detailed information about a specific agent.

Parameters:

agent_id (string, required): The agent ID

Response:

{
  "agent_id": "researcher",
  "name": "Research Agent",
  "description": "Web search, fact-checking, and analysis capabilities",
  "model_id": "gemini-2.5-flash",
  "tools_count": 8,
  "memory_enabled": true,
  "tools": ["web_search", "arxiv_search", "wikipedia_search", "fact_check"]
}

POST /api/agents

Create a new custom agent.

Request Body:

{
  "agent_type": "research",
  "agent_id": "my_custom_researcher",
  "name": "My Custom Researcher",
  "description": "Specialized research agent for my domain",
  "model_id": "gemini-2.5-flash",
  "prompt_template": "You are a specialized research assistant...",
  "tools": ["web_search", "file_search"],
  "enable_memory": true
}

Response:

{
  "agent_id": "my_custom_researcher",
  "name": "My Custom Researcher",
  "description": "Specialized research agent for my domain",
  "model_id": "gemini-2.5-flash",
  "tools_count": 2,
  "memory_enabled": true,
  "tools": ["web_search", "file_search"]
}

Memory Management

GET /api/memory/{user_id}

Retrieve user memories.

Parameters:

user_id (string, required): User ID
memory_type (string, optional): Filter by memory type
limit (integer, optional): Maximum number of memories (default: 50)

Query Parameters:

memory_type: short_term, long_term, user_preference, conversation, task, factual
limit: Number between 1-100

Response:

{
  "memories": [
    {
      "id": "mem_123",
      "content": "User prefers morning meetings",
      "type": "user_preference",
      "importance": 8,
      "created_at": "2024-01-01T00:00:00Z",
      "tags": ["meetings", "schedule"],
      "metadata": {"category": "preferences"}
    }
  ]
}

POST /api/memory/{user_id}

Create a new memory.

Request Body:

{
  "content": "User prefers morning meetings",
  "memory_type": "user_preference",
  "importance": 8,
  "tags": ["meetings", "schedule"],
  "expires_in_hours": 168,
  "metadata": {"category": "preferences"}
}

Parameters:

content (string, required): Memory content
memory_type (string, optional): Memory type (default: "long_term")
importance (integer, optional): Importance score 1-10 (default: 5)
tags (array, optional): Memory tags
expires_in_hours (integer, optional): Expiration time in hours
metadata (object, optional): Additional metadata

Response:

{
  "memory_id": "mem_123",
  "success": true
}

DELETE /api/memory/{user_id}/{memory_id}

Delete a specific memory.

Parameters:

user_id (string, required): User ID
memory_id (string, required): Memory ID

Response:

{
  "success": true
}

GET /api/memory/{user_id}/search

Search memories using semantic similarity.

Parameters:

user_id (string, required): User ID
query (string, required): Search query
limit (integer, optional): Maximum results (default: 20)

Response:

{
  "memories": [
    {
      "id": "mem_123",
      "content": "User prefers morning meetings",
      "type": "user_preference",
      "importance": 8,
      "created_at": "2024-01-01T00:00:00Z",
      "tags": ["meetings", "schedule"]
    }
  ]
}

File Processing

POST /api/files/upload

Upload and process a file for embedding and search.

Request:

curl -X POST "http://localhost:8000/api/files/upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@document.pdf"

Response:

{
  "file_id": "file_123",
  "filename": "document.pdf",
  "size": 1024000,
  "type": "pdf",
  "chunks_created": 45,
  "processing_time": 2.5,
  "success": true
}

GET /api/files/{user_id}

List user's uploaded files.

Response:

{
  "documents": [
    {
      "id": "file_123",
      "name": "document.pdf",
      "size": 1024000,
      "type": "pdf",
      "uploaded_at": "2024-01-01T00:00:00Z",
      "processed": true,
      "metadata": {
        "chunks_count": 45
      }
    }
  ]
}

DELETE /api/files/delete

Delete a user's file and its embeddings.

Request Body:

{
  "file_path": "/path/to/file.pdf"
}

Response:

{
  "success": true,
  "message": "File document.pdf deleted."
}

GET /api/files/{user_id}/search

Search through user's processed files.

Parameters:

user_id (string, required): User ID
query (string, required): Search query
limit (integer, optional): Maximum results (default: 10)

Response:

{
  "results": [
    {
      "content": "Relevant text from document...",
      "source": "document.pdf",
      "page": 1,
      "score": 0.95,
      "metadata": {
        "chunk_id": "chunk_123"
      }
    }
  ]
}

Google Services

GET /api/google/gmail

Retrieve Gmail messages.

Parameters:

query (string, optional): Gmail search query
max_results (integer, optional): Maximum results (default: 10)

Response:

{
  "messages": [
    {
      "id": "msg_123",
      "subject": "Meeting Tomorrow",
      "sender": "colleague@example.com",
      "date": "2024-01-01T00:00:00Z",
      "snippet": "Hi, let's meet tomorrow at 2 PM...",
      "unread": true
    }
  ]
}

POST /api/google/gmail/send

Send an email via Gmail.

Request Body:

{
  "to": "recipient@example.com",
  "subject": "AI-Generated Email",
  "body": "This email was composed with AI assistance!",
  "html": false
}

Response:

{
  "success": true
}

GET /api/google/calendar

Retrieve calendar events.

Parameters:

max_results (integer, optional): Maximum results (default: 10)

Response:

{
  "events": [
    {
      "id": "event_123",
      "summary": "Team Meeting",
      "start": "2024-01-01T14:00:00Z",
      "end": "2024-01-01T15:00:00Z",
      "location": "Conference Room A",
      "attendees": ["user@example.com", "colleague@example.com"]
    }
  ]
}

GET /api/google/drive

List Google Drive files.

Parameters:

query (string, optional): Search query
max_results (integer, optional): Maximum results (default: 10)

Response:

{
  "files": [
    {
      "id": "file_123",
      "name": "Project Document",
      "type": "document",
      "size": 1024000,
      "modified": "2024-01-01T00:00:00Z",
      "shared": true
    }
  ]
}

Authentication

GET /auth/google

Initiate Google OAuth flow.

Response:

{
  "url": "https://accounts.google.com/oauth/authorize?..."
}

POST /auth/logout

Logout user and clear session.

Response:

{
  "message": "Logged out successfully"
}

GET /auth/me

Get current user information.

Response:

{
  "id": "default_user",
  "username": "user",
  "email": "user@example.com",
  "authenticated": true
}

Workflow Execution

POST /api/workflows

Execute a multi-step workflow.

Request Body:

{
  "steps": [
    {
      "id": "research",
      "agent": "researcher",
      "task": "Research AI trends in 2024",
      "dependencies": []
    },
    {
      "id": "document",
      "agent": "creator",
      "task": "Create a comprehensive report based on the research",
      "dependencies": ["research"]
    }
  ],
  "session_id": "workflow_123"
}

Response:

{
  "results": [
    {
      "step_id": "research",
      "agent": "researcher",
      "status": "completed",
      "result": "Research completed with 10 relevant articles found...",
      "execution_time": 15.5
    },
    {
      "step_id": "document",
      "agent": "creator",
      "status": "completed",
      "result": "Report created with 5 sections covering key trends...",
      "execution_time": 25.2
    }
  ]
}

WebSocket Support

Chat Streaming

Connect to WebSocket for real-time chat:

const ws = new WebSocket('ws://localhost:8000/ws/chat');

ws.onopen = function() {
    // Send message
    ws.send(JSON.stringify({
        message: "Hello, can you help me?",
        agent_id: "orchestrator",
        session_id: "session_123"
    }));
};

ws.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log('Received:', data);
};

Error Handling

HTTP Status Codes

200 OK: Request successful
400 Bad Request: Invalid request data
401 Unauthorized: Authentication required
403 Forbidden: Access denied
404 Not Found: Resource not found
422 Unprocessable Entity: Validation error
500 Internal Server Error: Server error

Error Response Format

{
  "success": false,
  "error": "Validation Error",
  "details": {
    "field": "message",
    "issue": "Field is required"
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Rate Limiting

API requests are rate-limited to prevent abuse:

Chat endpoints: 60 requests per minute per user
File upload: 10 requests per minute per user
Memory operations: 100 requests per minute per user
Google services: 30 requests per minute per user

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200

SDKs and Libraries

Python SDK Example

from bronny_client import BronnyClient

client = BronnyClient(
    base_url="http://localhost:8000",
    api_key="your-api-key"
)

# Chat with an agent
response = client.chat(
    message="Hello, help me research AI trends",
    agent_id="orchestrator"
)

# Upload a file
result = client.upload_file("document.pdf")

# Search memories
memories = client.search_memories("meetings")

JavaScript SDK Example

import { BronnyClient } from 'bronny-client';

const client = new BronnyClient({
  baseUrl: 'http://localhost:8000',
  apiKey: 'your-api-key'
});

// Chat with an agent
const response = await client.chat({
  message: 'Hello, help me research AI trends',
  agentId: 'orchestrator'
});

// Upload a file
const result = await client.uploadFile(file);

// Search memories
const memories = await client.searchMemories('meetings');

Testing

API Testing with curl

# Health check
curl -X GET "http://localhost:8000/health"

# Chat with agent
curl -X POST "http://localhost:8000/api/chat" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, can you help me?",
    "agent_id": "orchestrator"
  }'

# List agents
curl -X GET "http://localhost:8000/api/agents" \
  -H "Authorization: Bearer <token>"

Postman Collection

Import the provided Postman collection for easy API testing:

Bronny API Collection

Monitoring and Logging

Health Monitoring

Monitor API health and performance:

# Basic health check
curl http://localhost:8000/health

# Detailed system status
curl http://localhost:8000/health/detailed

Logging

API requests and responses are logged with structured data:

{
  "timestamp": "2024-01-01T00:00:00Z",
  "level": "INFO",
  "method": "POST",
  "path": "/api/chat",
  "user_id": "user_123",
  "agent_id": "orchestrator",
  "response_time": 1.234,
  "status_code": 200
}

Security

Authentication

JWT-based authentication
Token expiration and refresh
Secure token storage recommendations

Data Protection

Input validation and sanitization
SQL injection prevention
XSS protection
Rate limiting and DDoS protection

Privacy

User data isolation
Memory access controls
Audit logging
Data retention policies

Performance

Optimization Tips

Use streaming for long responses: Enable stream: true for better UX
Batch memory operations: Combine multiple memory operations
Cache frequently accessed data: Use appropriate caching headers
Optimize file uploads: Compress files before upload
Use pagination: Limit results for large datasets

Performance Metrics

Average response time: < 500ms for simple queries
File processing: ~2-5 seconds per MB
Memory search: < 100ms for semantic search
Concurrent users: Supports 100+ concurrent connections

Troubleshooting

Common Issues

Authentication errors: Check token validity and format
File upload failures: Verify file size limits and formats
Memory search issues: Ensure memories are properly embedded
Google service errors: Check OAuth credentials and permissions

Debug Mode

Enable debug mode for detailed logging:

DEBUG=true python api/main.py

Support

For API support and issues:

Check the GitHub Issues
Review the Troubleshooting Guide
Contact support via Discord

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

Bronny AI Assistant - API Documentation

Overview

Base URL

Authentication

Response Format

Endpoints

Health Check

GET /health

Chat Endpoints

POST /api/chat

Agent Management

GET /api/agents

GET /api/agents/{agent_id}

POST /api/agents

Memory Management

GET /api/memory/{user_id}

POST /api/memory/{user_id}

DELETE /api/memory/{user_id}/{memory_id}

GET /api/memory/{user_id}/search

File Processing

POST /api/files/upload

GET /api/files/{user_id}

DELETE /api/files/delete

GET /api/files/{user_id}/search

Google Services

GET /api/google/gmail

POST /api/google/gmail/send

GET /api/google/calendar

GET /api/google/drive

Authentication

GET /auth/google

POST /auth/logout

GET /auth/me

Workflow Execution

POST /api/workflows

WebSocket Support

Chat Streaming

Error Handling

HTTP Status Codes

Error Response Format

Rate Limiting

SDKs and Libraries

Python SDK Example

JavaScript SDK Example

Testing

API Testing with curl

Postman Collection

Monitoring and Logging

Health Monitoring

Logging

Security

Authentication

Data Protection

Privacy

Performance

Optimization Tips

Performance Metrics

Troubleshooting

Common Issues

Debug Mode

Support