Skip to main content

API Reference

Comprehensive API documentation for the Toto ecosystem with clean architecture implementation.

🏗 Architecture Overview​

The Toto ecosystem uses a dual-project architecture with separate API endpoints:

External APIs (toto-app)​

All core business data is served from the main Toto app:

  • Base URL: https://app.betoto.pet/api (Production) | https://stg.app.betoto.pet/api (Staging)
  • Authentication: JWT-based authentication
  • Data: Cases, users, donations, guardians

Local APIs (toto-bo)​

Backoffice-specific features managed locally:

  • Base URL: https://bo.betoto.pet/api (Production) | https://stg.bo.betoto.pet/api (Staging)
  • Authentication: NextAuth.js session-based
  • Data: Collaborators, notifications, audit logs, analytics

AI Hub APIs (toto-ai-hub)​

AI-powered assistance and Twitter monitoring:

  • Base URL: Varies by deployment
  • Authentication: API key or service account
  • Features: AI agents, Twitter monitoring, knowledge base

Wallet APIs (toto-wallet)​

Payment processing with Stellar blockchain:

  • Base URL: Varies by deployment
  • Authentication: Firebase Auth tokens
  • Features: Wallet management, transactions, donations

📚 API Documentation​

Backoffice API Reference​

Complete documentation for all backoffice endpoints:

  • Backoffice API Reference - Comprehensive API documentation (2000+ endpoints)
    • User Management
    • Case Management
    • Donation Management
    • Support System
    • Notifications
    • Audit Logs
    • Analytics & Monitoring
    • Health Checks
    • GDPR Compliance
    • And much more...

AI Hub API Reference​

AI system and Twitter monitoring endpoints:

  • AI Hub API Reference - AI system API documentation
    • Twitter Monitoring
    • Agent Management
    • Review Queue
    • Guardian Management
    • Configuration Management

Internal APIs​

Internal Next.js API routes for UI usage:

  • Internal APIs - Internal API routes
    • Chat Orchestrator
    • Onboarding Orchestrator
    • Gemini Summary
    • User Conversations

Wallet API Reference​

Stellar blockchain wallet and payment APIs:

  • Wallet API Reference - Payment system API documentation
    • Wallet Management
    • Transaction Processing
    • Donation Handling

🔐 Authentication​

External API Authentication (toto-app)​

Authorization: Bearer <jwt_token>
Content-Type: application/json

JWT tokens are obtained from Firebase Auth after user login.

Local API Authentication (toto-bo)​

Cookie: next-auth.session-token=<session_token>
Content-Type: application/json

Session tokens are managed by NextAuth.js.

AI Hub API Authentication​

Authorization: Bearer <api_key>
Content-Type: application/json

API keys are managed through service accounts.

Wallet API Authentication​

Authorization: Bearer <firebase_id_token>
Content-Type: application/json

Firebase ID tokens are obtained from Firebase Auth.

📞 Error Handling​

All APIs follow a consistent error response format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "field_name",
      "value": "invalid_value"
    }
  }
}

Common Error Codes​

  • AUTHENTICATION_ERROR: Invalid or missing authentication
  • AUTHORIZATION_ERROR: Insufficient permissions
  • VALIDATION_ERROR: Invalid request data
  • NOT_FOUND: Resource not found
  • RATE_LIMIT_EXCEEDED: Too many requests
  • INTERNAL_SERVER_ERROR: Server error

For detailed error handling documentation, see Backoffice API Reference - Error Handling.

🔗 Rate Limiting​

Rate Limits​

  • External APIs (toto-app): 100 requests per minute per user
  • Local APIs (toto-bo): 1000 requests per minute per session
  • Authentication: 10 attempts per minute per IP
  • AI Hub APIs: Varies by endpoint

Rate Limit Headers​

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642234567

For detailed rate limiting documentation, see Backoffice API Reference - Rate Limiting.

📚 SDK Examples​

JavaScript/TypeScript​

import { TotoAPI } from '@toto/api-client';

const api = new TotoAPI({
  baseURL: 'https://app.betoto.pet/api',
  token: 'your_jwt_token'
});

// Get cases
const cases = await api.cases.list({
  limit: 20,
  status: 'active'
});

// Create donation
const donation = await api.donations.create({
  caseId: 'case-123',
  amount: 100,
  currency: 'USD',
  donorEmail: 'donor@example.com'
});

Python​

import requests

class TotoAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    
    def get_cases(self, limit=10, status=None):
        params = {'limit': limit}
        if status:
            params['status'] = status
        
        response = requests.get(
            f'{self.base_url}/cases',
            headers=self.headers,
            params=params
        )
        return response.json()

# Usage
api = TotoAPI(
    'https://app.betoto.pet/api',
    'your_jwt_token'
)
cases = api.get_cases(limit=20, status='active')

For more SDK examples and integration guides, see the detailed API references above.

🔗 Related Resources​