Documentation - Andy API

Quick Start

The Andy API is a distributed AI compute pool providing OpenAI-compatible endpoints with automatic load balancing, failover support, and real-time monitoring across multiple hosts.

Free Chat API (No Authentication)

Get started instantly with our free chat endpoint - no API key required:

curl -X POST "https://andy.mindcraft-ce.com/api/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sweaterdog/andy-4:latest",
    "messages": [
      {
        "role": "user",
        "content": "Hello! Can you help me understand how AI models work?"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 150
  }'

Authenticated Requests (API Key Required)

For enhanced limits and additional endpoints, get an API key and include it in your requests:

curl -X POST "https://andy.mindcraft-ce.com/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sweaterdog/andy-4:latest",
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 200
  }'

Python Example

import requests

# Configuration
url = "https://andy.mindcraft-ce.com/api/v1/chat/completions"
api_key = "YOUR_API_KEY_HERE"  # Get from /api-keys page

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}"  # Include for authenticated requests
}

payload = {
    "model": "sweaterdog/andy-4:latest",
    "messages": [
        {
            "role": "user", 
            "content": "Write a short poem about artificial intelligence"
        }
    ],
    "temperature": 0.8,
    "max_tokens": 100
}

# Make the request
response = requests.post(url, json=payload, headers=headers)
result = response.json()

# Print the response
print(result["choices"][0]["message"]["content"])

JavaScript/Node.js Example

const fetch = require('node-fetch');

async function callAndyAPI() {
    const response = await fetch('https://andy.mindcraft-ce.com/api/v1/chat/completions', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer YOUR_API_KEY_HERE'  // For authenticated requests
        },
        body: JSON.stringify({
            model: 'sweaterdog/andy-4:latest',
            messages: [
                {
                    role: 'user',
                    content: 'Explain machine learning in simple terms'
                }
            ],
            temperature: 0.8,
            max_tokens: 150
        })
    });
    
    const data = await response.json();
    console.log(data.choices[0].message.content);
}

callAndyAPI();

Authentication

Endpoint Type	Authentication	Rate Limits
All Endpoints (Free Tier)	None Required	5 concurrent, 1000/day
All Endpoints (With API Key)	API Key Optional	10 concurrent, unlimited/day

Get Your API Key

API keys are completely optional! They only provide higher rate limits.

All endpoints work without authentication: chat, models, embeddings, pool status, metrics, etc.

To get an API key:
1. Create a free account
2. Visit the API Keys page
3. Generate a new API key
4. Include it in the Authorization header for enhanced limits

Using API Keys

API keys are completely optional and only provide enhanced rate limits:

# All endpoints work without authentication (5 concurrent, 1000/day)
curl "https://andy.mindcraft-ce.com/api/v1/models"
curl "https://andy.mindcraft-ce.com/api/v1/embeddings" -d '{"input": "test"}'

# Include API key for higher limits (10 concurrent, unlimited)
curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
     "https://andy.mindcraft-ce.com/api/v1/models"

# Python - API key is optional
headers = {"Authorization": "Bearer YOUR_API_KEY_HERE"}  # Optional for all endpoints

# JavaScript - API key is optional
headers: {"Authorization": "Bearer YOUR_API_KEY_HERE"}  // Optional for all endpoints

API Reference

Base URL: https://andy.mindcraft-ce.com

Chat Completions

POST /api/v1/chat/completions

Create a chat completion using the distributed model pool. API key optional for higher limits.

Parameter	Type	Required	Description
`model`	string	Yes	Model name (e.g., "sweaterdog/andy-4:latest")
`messages`	array	Yes	Array of message objects with "role" and "content"
`temperature`	number	No	Sampling temperature (0-2, default: 1)
`max_tokens`	integer	No	Maximum tokens to generate
`stream`	boolean	No	Stream response chunks (default: false)
`stop`	array	No	Stop sequences

Embeddings Parameters

POST /api/v1/embeddings

Generate embeddings using available embedding models. API key optional for higher limits.

Parameter	Type	Required	Description
`model`	string	No	Embedding model name (default: "nomic-embed-text")
`input`	string	Yes	Text to generate embeddings for

Other Endpoints

GET /api/v1/models

List all available models across the compute pool.

Utility Endpoints

GET /api/ping

Simple health check endpoint that returns a pong response.

GET /api/version

Get the current API version information.

GET /api/pool_status

Get current status of the compute pool including active hosts and load.

GET /api/metrics

Get comprehensive metrics about the API performance, host status, and usage statistics.

Advanced Usage

Streaming Responses

Get real-time streaming responses for longer conversations:

import requests
import json

url = "https://andy.mindcraft-ce.com/api/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY_HERE"  # Optional
}

payload = {
    "model": "sweaterdog/andy-4:latest",
    "messages": [{"role": "user", "content": "Tell me a detailed story"}],
    "stream": True,
    "temperature": 0.8
}

response = requests.post(url, json=payload, headers=headers, stream=True)

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: '):
            data = line[6:]
            if data != '[DONE]':
                chunk = json.loads(data)
                content = chunk['choices'][0]['delta'].get('content', '')
                print(content, end='', flush=True)

OpenAI Library Compatibility

Use Andy API as a drop-in replacement for OpenAI:

from openai import OpenAI

# Initialize client with Andy API
client = OpenAI(
    api_key="YOUR_API_KEY_HERE",  # Optional
    base_url="https://andy.mindcraft-ce.com/api/v1"
)

# Use exactly like OpenAI
response = client.chat.completions.create(
    model="sweaterdog/andy-4:latest",
    messages=[
        {"role": "user", "content": "Explain neural networks"}
    ],
    temperature=0.7,
    max_tokens=300
)

print(response.choices[0].message.content)

Error Handling

import requests
from time import sleep

def safe_api_call(payload, max_retries=3):
    url = "https://andy.mindcraft-ce.com/api/v1/chat/completions"
    
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, timeout=30)
            
            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:  # Rate limited
                sleep(2 ** attempt)  # Exponential backoff
                continue
            else:
                response.raise_for_status()
                
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise e
            sleep(1)
    
    raise Exception("Max retries exceeded")

Monitoring & Metrics

Andy API provides comprehensive monitoring endpoints to track performance, health, and usage patterns across the distributed compute pool.

Health Check

Simple endpoint to verify API availability:

curl "https://andy.mindcraft-ce.com/api/ping"

# Response:
{
  "message": "🏓 Pong!"
}

API Version

Get current API version information:

curl "https://andy.mindcraft-ce.com/api/version"

# Response:
{
  "version": "1.2.5 - Stable"
}

Comprehensive Metrics

The metrics endpoint provides real-time insights into system performance:

curl "https://andy.mindcraft-ce.com/api/metrics"

Metrics Response Structure

Field	Type	Description
`keyMetrics`	object	Overall system health indicators
`hosts`	array	Individual host performance metrics
`chartData`	object	Historical data for visualization

Pool Status

Detailed information about the compute pool (requires API key):

curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
     "https://andy.mindcraft-ce.com/api/pool_status"

# Response includes:
{
  "total_hosts": 5,
  "active_hosts": 3,
  "total_models": 12,
  "hosts": [
    {
      "host_id": "abc123",
      "status": "active",
      "load": 2,
      "max_clients": 4,
      "models": [...],
      "last_seen": 5.2,
      "capabilities": [...]
    }
  ]
}

Integration Examples

Monitor API health in your applications:

import requests
import time

def check_api_health():
    """Simple health check function"""
    try:
        response = requests.get("https://andy.mindcraft-ce.com/api/ping", timeout=5)
        return response.status_code == 200
    except requests.RequestException:
        return False

def get_pool_utilization():
    """Get current pool utilization percentage"""
    try:
        response = requests.get("https://andy.mindcraft-ce.com/api/metrics", timeout=10)
        if response.status_code == 200:
            metrics = response.json()
            return metrics["keyMetrics"]["poolUtilization"]
    except requests.RequestException:
        pass
    return None

# Usage
if check_api_health():
    utilization = get_pool_utilization()
    print(f"API is healthy, pool utilization: {utilization}%")
else:
    print("API health check failed")

Contributing Compute Power

Help grow the Andy API network by contributing your GPU compute power. Join the distributed pool and earn rewards while helping the community access AI models.

Setup Local Client

Monitor Network Health

Pool Dashboard Live Metrics Available Models

Support

GitHub Repository Discord Community Try the Chat Interface

Andy API Documentation

Quick Navigation