API Endpoints Testing Guide

Complete guide for testing all FastAPI endpoints with working curl examples and automated test script.

Prerequisites

• Backend server running: aitana server start --no-frontend
• Server status check: aitana server status
• Base URL: http://localhost:1956

Quick Health Check

# Verify backend is running
curl http://localhost:1956/health
# Expected: {"status":"healthy","service":"fastapi"}

Automated Testing Script

Quick Start

cd /Users/mark/dev/aitana-labs/frontend/backend

# Run the comprehensive test script
uv run scripts/test_all_endpoints.py

# Or run directly (executable)
./scripts/test_all_endpoints.py

What the Script Tests

• All API information endpoints
• Model endpoints (Gemini, Anthropic, Smart)
• Tool endpoints (Google Search, Structured Extraction, URL Processing, etc.)
• Agent endpoints
• Includes proper test data for each endpoint
• Automatically uses gcloud auth for user email
• Tests against real resources (aitana-assistant-docs, public GCS files)

Script Output

• Colored pass/fail indicators
• Input/output for each test
• Summary with success rate
• Results saved to test_results_YYYYMMDD_HHMMSS.json

Working Endpoints Reference

1. API Overview

# Get API structure
curl -s http://localhost:1956/direct | jq .

# List all tools
curl -s http://localhost:1956/direct/tools | jq .

# List all models
curl -s http://localhost:1956/direct/models | jq .

# List all agents
curl -s http://localhost:1956/direct/agents | jq .

Model Endpoints (Non-Streaming)

Gemini Models ✅ WORKING

# Simple question
curl -X POST http://localhost:1956/direct/models/gemini \
-H "Content-Type: application/json" \
-d '{
  "contents": "What is the capital of France?",
  "model_name": "gemini-2.5-flash",
  "temperature": 0.5,
  "max_tokens": 50
}' | jq .

# Expected Response:
{
  "status": "success",
  "model": "gemini-2.5-flash",
  "response": "The capital of France is **Paris**."
}

# Math problem
curl -X POST http://localhost:1956/direct/models/gemini \
-H "Content-Type: application/json" \
-d '{
  "contents": "Calculate 15 * 7 and show your work",
  "model_name": "gemini-2.5-flash",
  "temperature": 0.3,
  "max_tokens": 100
}' | jq .

# Creative writing
curl -X POST http://localhost:1956/direct/models/gemini \
-H "Content-Type: application/json" \
-d '{
  "contents": "Write a haiku about programming",
  "model_name": "gemini-2.5-pro",
  "temperature": 0.8,
  "max_tokens": 100
}' | jq .

Anthropic Smart Models ✅ WORKING

# Simple explanation
curl -X POST http://localhost:1956/direct/models/anthropic/smart \
-H "Content-Type: application/json" \
-d '{
  "question": "What is machine learning?",
  "model": "claude-3-5-haiku-20241022",
  "temperature": 0.7
}' | jq .

# Expected: Detailed explanation of machine learning

# Code generation
curl -X POST http://localhost:1956/direct/models/anthropic/smart \
-H "Content-Type: application/json" \
-d '{
  "question": "Write a Python function to calculate factorial",
  "model": "claude-3-5-sonnet-20241022",
  "temperature": 0.5
}' | jq .

# Analysis task
curl -X POST http://localhost:1956/direct/models/anthropic/smart \
-H "Content-Type: application/json" \
-d '{
  "question": "Compare REST API vs GraphQL in 3 bullet points",
  "model": "claude-3-5-haiku-20241022",
  "temperature": 0.6
}' | jq .

Smart Models (Unified Interface) ⚠️ RETURNS MINIMAL RESPONSE

# Gemini through smart interface
curl -X POST http://localhost:1956/direct/models/smart \
-H "Content-Type: application/json" \
-d '{
  "question": "Explain quantum computing briefly",
  "smart_tool": "gemini-2.5-flash"
}' | jq .

# OpenAI GPT-5 through smart interface
curl -X POST http://localhost:1956/direct/models/smart \
-H "Content-Type: application/json" \
-d '{
  "question": "Write a haiku about AI",
  "smart_tool": "openai-gpt-5"
}' | jq .

# OpenAI O3 reasoning model
curl -X POST http://localhost:1956/direct/models/smart \
-H "Content-Type: application/json" \
-d '{
  "question": "Solve this step by step: If a train travels 120km in 2 hours, what is its speed?",
  "smart_tool": "openai-o3"
}' | jq .

# Anthropic through smart interface
curl -X POST http://localhost:1956/direct/models/smart \
-H "Content-Type: application/json" \
-d '{
  "question": "What are the benefits of TypeScript?",
  "smart_tool": "anthropic-3.5-sonnet"
}' | jq .

Tool Endpoints

Google Search ✅ WORKING

# Basic search
curl -X POST http://localhost:1956/direct/tools/google-search \
-H "Content-Type: application/json" \
-d '{
  "query": "Python FastAPI tutorial 2025"
}' | jq .

# Programming search
curl -X POST http://localhost:1956/direct/tools/google-search \
-H "Content-Type: application/json" \
-d '{
  "query": "best practices React hooks 2025"
}' | jq .

# Check status only
curl -X POST http://localhost:1956/direct/tools/google-search \
-H "Content-Type: application/json" \
-d '{"query": "machine learning courses"}' | jq '.status'
# Expected: "success"

Code Execution ⚠️ RETURNS NULL

# Simple calculation
curl -X POST http://localhost:1956/direct/tools/code-execution \
-H "Content-Type: application/json" \
-d '{
  "new_question": "print(15 * 7)",
  "contents": [],
  "instructions": "Execute this Python code"
}' | jq .

# Python function
curl -X POST http://localhost:1956/direct/tools/code-execution \
-H "Content-Type: application/json" \
-d '{
  "new_question": "def factorial(n): return 1 if n <= 1 else n * factorial(n-1)\nprint(factorial(5))",
  "contents": [],
  "instructions": "Run this factorial function"
}' | jq .

Structured Extraction ✅ WORKING

# Extract person information
curl -X POST http://localhost:1956/direct/tools/structured-extraction \
-H "Content-Type: application/json" \
-d '{
  "response_so_far": "John Smith is 28 years old, works as a software engineer in San Francisco, and earns $150,000 per year.",
  "toolConfigs": {
    "extraction_schema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "age": {"type": "number"},
        "occupation": {"type": "string"},
        "location": {"type": "string"},
        "salary": {"type": "number"}
      }
    }
  }
}' | jq .

# Extract product information
curl -X POST http://localhost:1956/direct/tools/structured-extraction \
-H "Content-Type: application/json" \
-d '{
  "response_so_far": "The iPhone 15 Pro costs $999, has 256GB storage, comes in titanium finish, and features a 48MP camera.",
  "toolConfigs": {
    "extraction_schema": {
      "type": "object",
      "properties": {
        "product": {"type": "string"},
        "price": {"type": "number"},
        "storage": {"type": "string"},
        "finish": {"type": "string"},
        "camera": {"type": "string"}
      }
    }
  }
}' | jq .

URL Processing ✅ WORKING

# Process documentation page
curl -X POST http://localhost:1956/direct/tools/url-processing \
-H "Content-Type: application/json" \
-d '{
  "question": "What is the main topic of this page?",
  "input_list_dict": [
    {"url": "https://docs.python.org/3/tutorial/index.html", "type": "webpage"}
  ]
}' | jq .

# Analyze website
curl -X POST http://localhost:1956/direct/tools/url-processing \
-H "Content-Type: application/json" \
-d '{
  "question": "Summarize the key features mentioned",
  "input_list_dict": [
    {"url": "https://fastapi.tiangolo.com/", "type": "webpage"}
  ]
}' | jq .

AI Search ⚠️ REQUIRES DATASTORE CONFIGURATION

# Semantic search (requires valid datastore_id)
curl -X POST http://localhost:1956/direct/tools/ai-search \
-H "Content-Type: application/json" \
-d '{
  "question": "What is machine learning?",
  "filter_str": "",
  "datastore_id": "your-datastore-id",
  "do_limit_content": true
}' | jq .

Extract Files ⚠️ REQUIRES GCS ACCESS

# Extract from GCS files (requires valid GCS URIs)
curl -X POST http://localhost:1956/direct/tools/extract-files \
-H "Content-Type: application/json" \
-d '{
  "new_question": "Summarize the main points",
  "gs_uris": ["gs://your-bucket/document.pdf"],
  "batch_size": 10,
  "timeout_per_file": 120
}' | jq .

User History ⚠️ REQUIRES USER DATA

# Search user history (requires user data)
curl -X POST http://localhost:1956/direct/tools/user-history \
-H "Content-Type: application/json" \
-d '{
  "query": "previous conversations about Python",
  "email_or_domain": "user@example.com",
  "type": "email"
}' | jq .

Agent Endpoints

Document Search Agent ⚠️ REQUIRES DATASTORE

curl -X POST http://localhost:1956/direct/agents/document-search \
-H "Content-Type: application/json" \
-d '{
  "question": "Find information about REST APIs",
  "datastore_id": "your-datastore-id",
  "max_documents": 5
}' | jq .

Code Execution Agent ⚠️ NOT IMPLEMENTED

curl -X POST http://localhost:1956/direct/agents/code-execution \
-H "Content-Type: application/json" \
-d '{
  "new_question": "Create a Python REST API server",
  "contents": [],
  "instructions": "Use FastAPI framework"
}' | jq .

Assistant Calling Agent ⚠️ NOT IMPLEMENTED

curl -X POST http://localhost:1956/direct/agents/assistant-calling \
-H "Content-Type: application/json" \
-d '{
  "assistant_id": "aitana3",
  "message": "Help me with Python",
  "context": {}
}' | jq .

Testing Scripts

Batch Test All Working Endpoints

#!/bin/bash
# save as test_endpoints.sh

echo "Testing API Endpoints..."

# Test Gemini
echo -e "\n=== Testing Gemini ==="
curl -s -X POST http://localhost:1956/direct/models/gemini \
-H "Content-Type: application/json" \
-d '{"contents": "Say hello", "model_name": "gemini-2.5-flash"}' | jq '.status'

# Test Anthropic
echo -e "\n=== Testing Anthropic ==="
curl -s -X POST http://localhost:1956/direct/models/anthropic/smart \
-H "Content-Type: application/json" \
-d '{"question": "Say hello", "model": "claude-3-5-haiku-20241022"}' | jq '.status'

# Test Google Search
echo -e "\n=== Testing Google Search ==="
curl -s -X POST http://localhost:1956/direct/tools/google-search \
-H "Content-Type: application/json" \
-d '{"query": "test query"}' | jq '.status'

# Test Structured Extraction
echo -e "\n=== Testing Structured Extraction ==="
curl -s -X POST http://localhost:1956/direct/tools/structured-extraction \
-H "Content-Type: application/json" \
-d '{
  "response_so_far": "Test data",
  "toolConfigs": {
    "extraction_schema": {
      "type": "object",
      "properties": {"test": {"type": "string"}}
    }
  }
}' | jq '.status'

# Test URL Processing
echo -e "\n=== Testing URL Processing ==="
curl -s -X POST http://localhost:1956/direct/tools/url-processing \
-H "Content-Type: application/json" \
-d '{
  "question": "test",
  "input_list_dict": [{"url": "https://example.com", "type": "webpage"}]
}' | jq '.status'

echo -e "\nAll tests completed!"

Python Test Script

#!/usr/bin/env python3
# save as test_api.py

import requests
import json

BASE_URL = "http://localhost:1956/direct"

def test_endpoint(name, method, endpoint, data=None):
    """Test a single endpoint"""
    url = f"{BASE_URL}{endpoint}"
    try:
        if method == "GET":
            response = requests.get(url)
        else:
            response = requests.post(url, json=data)
        
        if response.status_code == 200:
            print(f"✅ {name}: SUCCESS")
            return True
        else:
            print(f"❌ {name}: FAILED (Status: {response.status_code})")
            return False
    except Exception as e:
        print(f"❌ {name}: ERROR - {str(e)}")
        return False

# Test endpoints
print("Testing API Endpoints\n" + "="*50)

# Test API info
test_endpoint("API Info", "GET", "")
test_endpoint("List Tools", "GET", "/tools")
test_endpoint("List Models", "GET", "/models")

# Test Gemini
test_endpoint(
    "Gemini Model", "POST", "/models/gemini",
    {"contents": "Hello", "model_name": "gemini-2.5-flash"}
)

# Test Anthropic
test_endpoint(
    "Anthropic Model", "POST", "/models/anthropic/smart",
    {"question": "Hello", "model": "claude-3-5-haiku-20241022"}
)

# Test Google Search
test_endpoint(
    "Google Search", "POST", "/tools/google-search",
    {"query": "test"}
)

print("\nTest Complete!")

Common Issues & Solutions

Issue: 500 Internal Server Error

Solution: Check backend logs with aitana server logs

Issue: Connection Refused

Solution: Start backend with aitana server start --no-frontend

Issue: Empty or Minimal Responses

Solution: Some endpoints need proper context or configuration. Check required fields.

Issue: Timeout Errors

Solution: Increase timeout in curl: curl --max-time 30 ...

Working Status Summary

Endpoint	Status	Notes
/direct (API info)	✅ Working	Returns API structure
/direct/tools	✅ Working	Lists available tools
/direct/models	✅ Working	Lists available models
/direct/agents	✅ Working	Lists available agents
Models (Non-Streaming)
Gemini	✅ Working	Full responses
Anthropic Smart	✅ Working	Full responses
Smart (unified)	⚠️ Partial	Returns minimal content
Tools
Google Search	✅ Working	Returns search results
Structured Extraction	✅ Working	Extracts structured data
URL Processing	✅ Working	Processes web pages
Code Execution	⚠️ Issues	Returns null
AI Search	✅ Working*	Use datastore: aitana-assistant-docs
Extract Files	✅ Working*	Use GCS: gs://aitana-public-bucket/ppas/danish-ppas.pdf
User History	✅ Working*	Uses gcloud auth email
Agents
Document Search	✅ Working*	Use datastore: aitana-assistant-docs
Code Execution	❌ Not Implemented	Returns placeholder
Assistant Calling	❌ Not Implemented	Returns placeholder
Streaming Endpoints
All /stream endpoints	❌ Skip	Implementation incomplete - use non-streaming

*With proper configuration (see test script for defaults)

Recommendations

1. Run the automated test script first - uv run scripts/test_all_endpoints.py
2. Use non-streaming endpoints - They work reliably
3. Test with Gemini or Anthropic models directly for best results
4. Default configurations provided - AI Search, Extract Files, and User History work with the defaults in the test script
5. Skip streaming endpoints - Implementation incomplete, use non-streaming alternatives

Quick Start Examples

# 1. Check server is running
curl http://localhost:1956/health

# 2. Ask a question with Gemini
curl -X POST http://localhost:1956/direct/models/gemini \
-H "Content-Type: application/json" \
-d '{"contents": "What is Python?", "model_name": "gemini-2.5-flash"}' | jq .

# 3. Ask a question with Anthropic
curl -X POST http://localhost:1956/direct/models/anthropic/smart \
-H "Content-Type: application/json" \
-d '{"question": "What is FastAPI?", "model": "claude-3-5-haiku-20241022"}' | jq .

# 4. Search the web
curl -X POST http://localhost:1956/direct/tools/google-search \
-H "Content-Type: application/json" \
-d '{"query": "latest AI news"}' | jq .

# 5. Extract structured data
curl -X POST http://localhost:1956/direct/tools/structured-extraction \
-H "Content-Type: application/json" \
-d '{
  "response_so_far": "Apple stock closed at $195.89, up 2.3% today",
  "toolConfigs": {
    "extraction_schema": {
      "type": "object",
      "properties": {
        "company": {"type": "string"},
        "price": {"type": "number"},
        "change": {"type": "string"}
      }
    }
  }
}' | jq .