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 (Optional API Key or Account Client Token)

Public endpoints work without authentication. If you are signed in to your own Andy API account, either an API key or your account client token can move chat and embedding requests into the authenticated rate-limit buckets and unlock higher-tier server models for that account. For shared integrations, use an API key.

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
  }'

Routing Notes

Andy API routes between server-hosted models provided directly by Andy API and pool models provided by connected clients. That server-vs-pool split is what drives the request-limit buckets below.

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 & Request Limits

All public read-only endpoints remain available without authentication. The request-limit policy below applies to /api/v1/chat/completions and /api/v1/embeddings.

Target	Auth State	Daily Limit	Minute Limit	Concurrent Limit
Server-hosted models	None	100/day	3/min	1
Server-hosted models	API key or account client token	No daily cap	6/min	2
Pool/client-hosted models	None	1000/day	6/min	1
Pool/client-hosted models	API key or account client token	No daily cap	12/min	2

Unauthenticated requests can still use the public API, but only authenticated traffic can move out of the anonymous IP bucket. Server tiers determine access to server-hosted models. API keys no longer carry custom per-key RPM overrides.

Get Your API Key

API keys are optional, but they are the simplest way to get the authenticated request buckets. If you are signed in and using your own Andy API tooling, your account client token can also be sent in the X-Client-Token header. For public apps, shared scripts, or deployed integrations, use an API key instead.

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: Bearer ... header for authenticated usage

Using API Keys and Client Tokens

Use an API key for normal application auth. Use your account client token only when you want user-scoped auth for your own signed-in Andy API client tooling or local pool connections.

# Public, unauthenticated endpoints
curl "https://andy.mindcraft-ce.com/api/v1/models"
curl "https://andy.mindcraft-ce.com/api/pool_status"

# API key auth for chat or embeddings
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": "Hello"}]}'

# Account client token auth for your own signed-in tooling
curl -X POST "https://andy.mindcraft-ce.com/api/v1/chat/completions" \
  -H "X-Client-Token: YOUR_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "sweaterdog/andy-4:latest", "messages": [{"role": "user", "content": "Hello"}]}'

API Reference

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

Chat Completions

POST /api/v1/chat/completions

Create a text chat completion using the distributed model pool. Authentication is optional, but it changes the request bucket.

Message content is currently text-only on the public endpoint.

Parameter	Type	Required	Description
`model`	string	Yes	Model name (e.g., "sweaterdog/andy-4:latest")
`messages`	array	Yes	Array of message objects with string `role` and `content` fields. Use a leading `system` message for high-level instructions.
`temperature`	number	No	Sampling temperature (0-2, default: 1)
`max_tokens`	integer	No	Maximum tokens to generate

Embeddings Parameters

POST /api/v1/embeddings

Generate text embeddings using available embedding models. Authentication is optional, but it changes the request bucket.

Parameter	Type	Required	Description
`model`	string	No	Embedding model name (default: "nomic-embed-text")
`input`	string or array	Yes	Text or an array of text strings to generate embeddings for
`encoding_format`	string	No	Optional upstream encoding format
`user`	string	No	Optional end-user identifier forwarded with the request

Other Endpoints

GET /api/v1/models

List the currently available public/base-tier 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 the current status of the compute pool, including active hosts and available models. No API key required.

GET /api/metrics

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

Advanced Usage

Current Request Behavior

The public OpenAI-compatible route currently honors model, messages, max_tokens, and temperature for chat requests, and returns standard JSON responses. Streamed SSE chat responses are not currently exposed on this public frontend route.

Use the messages array for prompt shaping, including optional system instructions. Controls like top_p, presence_penalty, frequency_penalty, stop, and seed are not currently handled by the backend.

Content Safety

Chat and embedding text are checked against local heuristic safety rules before routing. Likely CSAM-related text is blocked with a structured content_policy_violation error.

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 == 400:
                body = response.json()
                if body.get("code") == "content_policy_violation":
                    raise ValueError(body.get("message", "Request blocked by content policy"))
                response.raise_for_status()
            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": "..."
}

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. This endpoint is public and does not require an API key.

curl "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. The current local-client setup is the Go client, and your account client token acts as the stable identity for reconnecting pool sessions.

Setup Local Client Go Local Client

Monitor Network Health

Pool Dashboard Live Metrics Available Models

Support

GitHub Repository Discord Community Try the Chat Interface

Quick Navigation

Andy API Documentation