Docs without the scavenger hunt.

01 · FIRST REQUEST

Start with cURL

Anonymous traffic needs no API key. Signed-in traffic uses a key created on the account page.

curl https://andy.mindcraft-ce.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer andy_YOUR_KEY" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Explain redstone simply."}],
    "max_tokens": 800
  }'

Routes

The same routes under /v1 remain available for compatibility. New integrations should prefer /api/v1.

02 · CLIENT LIBRARIES

Use OpenAI-compatible SDKs

from openai import OpenAI

client = OpenAI(
    base_url="https://andy.mindcraft-ce.com/api/v1",
    api_key="andy_YOUR_KEY",
)

result = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Show me how to debounce a Mindcraft bot event."}],
    max_tokens=800,
)
print(result.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://andy.mindcraft-ce.com/api/v1",
  apiKey: "andy_YOUR_KEY",
});

const result = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Show me how to debounce a Mindcraft bot event." }],
  max_tokens: 800,
});
console.log(result.choices[0].message.content);

03 · ROUTING

Models and preference routers

auto keeps the administrator-defined neutral order. Every auto/… router applies endpoint, modality, provider, and context eligibility checks first, then stably reorders the surviving candidates by one preference. Retryable provider failures continue through the entire remaining pool. A preference is never a capability guarantee, and a concrete model ID always pins that model without rerouting.

Open the live Models page to preview the server's exact current target order and seven-day performance measurements.

Built-in preferences

context and output prefer larger supported windows. multimodal prefers image-capable models even for text-only requests. light and pro sort the administrator-set request multiplier low-to-high or high-to-low; it is a usage policy, not a published price.

fast, latency, and reliable use Andy API's own rolling seven-day observations. They activate only when at least two viable models each have 20 matching endpoint, input-class, and streaming-mode samples. Until then, they use exact neutral order. Measured models are ranked by p50 throughput, p50 time to first response data, or observed eligible success rate; LOW DATA candidates remain afterward in neutral order. auto/fast is neutral for embeddings.

Tag preferences

Any other valid lowercase suffix, such as auto/mindcraft, prefers models carrying that tag and then falls through the rest of the pool. Unknown or currently unused tags fall back to exact neutral auto; the response includes X-Andy-Router-Fallback: auto. Built-in suffixes are reserved, tags cannot override them, and combined paths such as auto/mindcraft/context are not supported.

API-key model scopes

An empty key allowlist authorizes every enabled model and router. Selecting auto authorizes the complete auto and auto/* family; omitting it denies that family. Concrete selections remain exact. Router scopes do not narrow the router's global candidate pool.

Context and output

The context window is the combined input-plus-reserved-output window Andy API supports for that route. It may deliberately be lower than the upstream provider's advertised maximum. Set max_tokens or max_output_tokens explicitly; asking for an unnecessarily large output can leave too little room for the prompt and make an auto candidate ineligible. A model-wide system prompt configured by an administrator also uses this room and counts as input tokens.

04 · RETRIEVAL

Embeddings

Choose a live model whose metadata lists the embeddings endpoint, or use auto to try only embedding-capable models in order. Send a text string or an array of text strings. Embedding requests are non-streaming and have no output-token setting.

curl https://andy.mindcraft-ce.com/api/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer andy_YOUR_KEY" \
  -d '{
    "model": "your-embedding-model",
    "input": ["Searchable document one.", "Searchable document two."]
  }'

Text is screened before it reaches the embedding provider and input tokens count toward authenticated quotas. Token-ID arrays, images, files, audio, and video are rejected because the current safety path cannot inspect them.

05 · LIVE POLICY

Rate limits

Rate limits control request speed. Anonymous requests use only their network identity. A valid API key makes traffic authenticated, then both its account tier and the shared registered-network limit apply; the stricter value wins.

A zero or omitted value means unlimited for that field. Concurrent limits cap requests that are in flight, not requests per time window.

06 · ALLOWANCE

Usage quotas

Quotas are separate from rate limits. Session windows use shared five-hour UTC boundaries for every account; daily resets at UTC midnight and weekly at UTC Monday. Account and per-key self-imposed caps can only tighten the tier allowance.

Request multiplier

A model’s multiplier affects request units only. At 2×, one successful request consumes 2 request units in every active quota window. At 0.5×, two successful requests consume 1 unit total. Token usage is never multiplied—it uses the provider’s reported input and output tokens.

Quota admission is preflight-only. The final admitted request can pass a token ceiling because its exact token count is known only after the provider responds.

07 · SSE

Streaming

Set "stream": true for OpenAI-style server-sent events. For authenticated requests Andy asks the provider to include a final usage frame so token quotas remain accurate. If the provider omits it, a conservative preflight estimate is booked.

curl "https://andy.mindcraft-ce.com/api/v1/chat/completions" \
  -H "Authorization: Bearer andy_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","stream":true,"max_tokens":800,
       "messages":[{"role":"user","content":"Explain how to handle a Mindcraft bot reconnect."}]}'

A failure before the first SSE frame can fail over. Once response bytes reach the client, a mid-stream provider failure cannot be replayed safely.

08 · INPUT SAFETY

Images and moderation

Text and image inputs are screened before generation. Choose a model whose live metadata declares image input. Audio, video, uploaded files, and file IDs are rejected because they cannot be inspected by the current safety path.

Moderation fails closed: if the safety provider is unavailable or returns an unreadable verdict, the generation provider is not contacted.

09 · DEBUGGING

Error reference

10 · DATA

What usage data contains

Public metrics store only hour, public model, endpoint, request count, and successful response count. Private account analytics add account/key identifiers, request units, and input/output token totals. Neither system stores prompt text, response text, raw IPs, emails in public metrics, API secrets, or request bodies.

API key secrets are returned once. Only keyed hashes are stored, so a key cannot be recovered later—create a replacement if it is lost.

Andy API is for Mindcraft-related engineering; unrelated use is unsupported. Read the full Privacy Policy and Terms of Service. For Mindcraft integrations or higher-tier requests, email [email protected]; never send API keys or sensitive prompts.