Backend API How-To Guide

This document provides comprehensive guidance on how to use the Aitana backend API, including authentication, model configuration, and chat history persistence.

Quick Start

Authentication Setup

You need proper Google Cloud authentication to access the backend API:

# Install gcloud CLI if not already installed
# https://cloud.google.com/sdk/docs/install

```sh
gcloud auth login
gcloud auth application-default login

Access Requirements

You need the following IAM roles:

  • Cloud Run Invoker: To use the API
  • Cloud Run Developer: To add image tags

Access the backend API Cloud Run service: https://console.cloud.google.com/run/detail/europe-west1/backend-api/logs?project=aitana-multivac-production

The preferred way to interact with the backend is using existing assistant configurations. There are two endpoints available:

  • Endpoint: /vac/assistant/<assistant_id>/sse
  • Method: POST
  • Purpose: Real-time streaming with thinking content preservation
  • Used by: Frontend in production

Legacy Endpoint

  • Endpoint: /vac/assistant/<assistant_id>
  • Method: POST
  • Purpose: Non-streaming responses (backward compatibility)
  • Status: Still supported but not recommended

For detailed information about the SSE endpoint, see Assistant SSE Streaming API.

Example assistantIds:

  • echo - 360762b1-5f00-4b3c-847c-83959e36aad7
  • vanilla-anthropic - ffa74615-f2e4-42e2-8f92-4b403d4ee223
  • ONE news anchor - 566aa49b-9e58-42b2-b76f-5d31c19c5600
  • (On test) - MiguelCEO - ee4253d6-e204-4781-853a-ff613434b232
  • (on test) - Simon - 1d31542d-66aa-49cb-9bf2-d3a6c5198827
  • API helper - https://ai.aitana.chat/assistant/a766169a-703f-468a-afcd-06db06a994ee
curl -X POST http://localhost:1956/vac/assistant/360762b1-5f00-4b3c-847c-83959e36aad7 \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Hello",
    "chat_history": [],
    "currentUser": {
        "email": "user@example.com",
        "sessionId": "session-123"
    },
    "selectedItems": []
  }'

Getting Assistant IDs

You can find assistant IDs from the web interface URL:

  • URL: https://ai.aitana.chat/assistant/ffa74615-f2e4-42e2-8f92-4b403d4ee223
  • Assistant ID: ffa74615-f2e4-42e2-8f92-4b403d4ee223

Example Assistant IDs

  • Echo: 360762b1-5f00-4b3c-847c-83959e36aad7
  • Vanilla Anthropic: ffa74615-f2e4-42e2-8f92-4b403d4ee223
  • ONE News Anchor: 566aa49b-9e58-42b2-b76f-5d31c19c5600
  • API Helper: a766169a-703f-468a-afcd-06db06a994ee

Chat History Persistence

The backend API now supports persistent chat history stored in Firestore, allowing you to maintain conversation context across multiple API calls.

Chat History Parameters

Parameter Type Default Description
save_to_history boolean false When true, saves the current conversation (user message and assistant response) to Firestore
read_from_history boolean false When true, loads previous chat history from Firestore if no chat_history is provided
history_limit integer 50 Maximum number of messages to load from history (only used when read_from_history is true)
chat_history array [] Manual chat history. If provided, this takes precedence over read_from_history

Basic Usage Examples

Save Conversation to History

curl -X POST http://localhost:1956/vac/assistant/a766169a-703f-468a-afcd-06db06a994ee \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "What is renewable energy?",
    "save_to_history": true,
    "currentUser": {
      "email": "mark@aitanalabs.com",
      "sessionId": "session-123-chat-history-test"
    }
  }'

Load Previous History

curl -X POST http://localhost:1956/vac/assistant/a766169a-703f-468a-afcd-06db06a994ee \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Can you summarise the last 5 messages?",
    "read_from_history": true,
    "save_to_history": true,
    "confirm_past_pause": true,
    "history_limit": 20,
    "currentUser": {
      "email": "mark@aitanalabs.com",
      "sessionId": "session-123-chat-history-test"
    }
  }'

Combine Both Features

curl -X POST http://localhost:1956/vac/assistant/a766169a-703f-468a-afcd-06db06a994ee \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Continue our conversation from where we left off",
    "read_from_history": true,
    "save_to_history": true,
    "history_limit": 100,
    "currentUser": {
      "email": "user@example.com",
      "displayName": "John Doe",
      "sessionId": "session-456"
    }
  }'

Advanced Usage

Manual History Override

Even with read_from_history enabled, you can still provide manual chat_history which will take precedence:

curl -X POST http://localhost:1956/vac/assistant/a766169a-703f-468a-afcd-06db06a994ee \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Continue based on this specific context",
    "read_from_history": true,
    "save_to_history": true,
    "chat_history": [
      {"role": "human", "content": "What are solar panels?"},
      {"role": "ai", "content": "Solar panels are devices that convert sunlight into electricity..."}
    ],
    "currentUser": {
      "email": "user@example.com",
      "sessionId": "session-789"
    }
  }'

Data Storage Structure

Messages are stored in Firestore at: assistants/{assistantId}/messages/{messageId}

Each message contains:

{
  "sender": "user" | "assistant",
  "content": "The message content",
  "userName": "User's display name",
  "userEmail": "user@example.com",
  "photoURL": "URL to user's photo (optional)",
  "read": true | false,
  "timestamp": 1234567890000,
  "traceId": "trace-id-if-provided",
  "thinkingContent": "Internal thinking content (for assistant messages only)"
}

Best Practices

  1. Performance: Use history_limit to control the amount of history loaded
  2. Privacy: Only save conversations that need to be persistent
  3. Consistency: Always use save_to_history: true for conversations you want to continue later
  4. Error Handling: The API gracefully handles failures - if history loading fails, the conversation continues with empty history

Integration with Frontend

  • Messages saved via API appear in the frontend’s message history
  • Frontend conversations can be continued via API using read_from_history
  • Both share the same Firestore storage structure

Assistants List API

The backend provides an endpoint to list available assistants and templates from Firestore. This is useful for discovering assistants programmatically or building custom interfaces.

Endpoint

GET /assistants/list

Query Parameters

Parameter Type Default Description
include_templates boolean false Include template assistants in the response
include_instances boolean true Include assistant instances in the response
limit integer 100 Maximum number of assistants to return per type

Usage Examples

List Assistant Instances Only (Default)

curl -X GET "http://localhost:8080/assistants/list"

List Template Assistants Only

curl -X GET "http://localhost:8080/assistants/list?include_templates=true&include_instances=false"

List Both Assistants and Templates

curl -X GET "http://localhost:8080/assistants/list?include_templates=true&include_instances=true&limit=50"

Response Format

{
  "assistants": [
    {
      "assistantId": "1d31542d-66aa-49cb-9bf2-d3a6c5198827",
      "type": "instance",
      "name": "Simon",
      "avatar": "/images/avatars/simon.jpg",
      "tools": ["preview", "file-browser", "vertex_search"],
      "toolConfigs": {
        "file-browser": {
          "bucketUrl": "aitana-documents-bucket"
        },
        "vertex_search": {
          "datastore_id": "aitana3"
        }
      },
      "instructions": "I am Simon, your assistant for energy market analysis.",
      "persona": "Expert energy analyst",
      "isPublic": false,
      "createdAt": 1640995200000
    }
  ],
  "templates": [
    {
      "assistantId": "template-001",
      "type": "template",
      "name": "Energy Analyst Template",
      "avatar": "/images/avatars/analyst.jpg",
      "tools": ["vertex_search", "code_execution"],
      "isTemplate": true,
      "category": "Energy",
      "description": "Template for creating energy analysis assistants"
    }
  ],
  "total_count": 2
}

Response Fields

Common Fields (Both Assistants and Templates)

  • assistantId: Unique identifier for the assistant
  • type: Either “instance” or “template”
  • name: Display name of the assistant
  • avatar: Path to avatar image
  • tools: Array of enabled tools
  • toolConfigs: Configuration for each tool (if applicable)

Assistant Instance Fields

  • instructions: Custom instructions for the assistant
  • persona: Personality description
  • isPublic: Whether the assistant is publicly accessible
  • createdAt: Creation timestamp

Template Fields

  • isTemplate: Always true for templates
  • category: Template category for organization
  • description: Template description

Error Handling

If an error occurs, the endpoint returns null and logs the error. Example error response:

null

Check the server logs for detailed error information.

Use Cases

  1. Assistant Discovery: List all available assistants for a user interface
  2. Template Selection: Show available templates when creating new assistants
  3. Assistant Management: Build admin interfaces for managing assistants
  4. API Integration: Programmatically discover and interact with assistants

Integration with Assistant API

Use the assistantId from the list response to interact with specific assistants:

curl -X POST http://localhost:1956/vac/assistant/a766169a-703f-468a-afcd-06db06a994ee \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Hello",
    "currentUser": {
      "email": "user@example.com",
      "sessionId": "session-123"
    }
  }'

Proxy Setup (Optional)

If you prefer to use a local proxy instead of direct Cloud Run access:

Install Sunholo CLI

# Install uv package manager
# https://github.com/astral-sh/uv

# Install sunholo CLI
uv tool install --from "sunholo[cli,gcp,http]" sunholo 
sunholo

Start Proxy

# Set config folder path
export VAC_CONFIG_FOLDER=/path/to/multivac-apps/config

# Start proxy
sunholo --project aitana-multivac-production proxy start backend-api

# Check proxy status
sunholo proxy list

Then use http://localhost:1956 instead of the Cloud Run URL in your API calls.

Error Handling

The API provides comprehensive error handling:

  • Authentication errors: Return 401/403 status codes
  • Missing parameters: Return 400 with descriptive error messages
  • Assistant not found: Return 404 with assistant ID
  • Internal errors: Return 500 with error details (without exposing sensitive info)

Security Considerations

  1. Authentication: Always use proper Google Cloud authentication
  2. Rate Limiting: The API implements rate limiting to prevent abuse
  3. Data Privacy: User data is isolated and access-controlled
  4. Input Validation: All inputs are validated and sanitized

Testing

The chat history functionality is thoroughly tested. Run tests with:

cd backend
python -m pytest tests/test_assistant_config_chat_history.py -v

Additional Resources