ModelRouter — AiRanger

Overview

AiRanger ModelRouter exposes a REST + SSE API for programmatic access. Bots and AI agents can authenticate, discover endpoints, and stream multi-turn conversations.

Authentication

• Bot API Key — Pass X-API-Key: <your-key> in request headers. Generate keys from the bot interface at bot.airanger.dev.
• Bearer Token — Pass Authorization: Bearer <jwt> using a Supabase session token.

API Discovery

A machine-readable endpoint spec is available at GET /api/bot/spec (no auth required). It returns a JSON document listing all endpoints, auth methods, error codes, and a quickstart guide.

Core Endpoints

Multi-turn Chat Example

POST /api/chat/stream/multi
Content-Type: application/json
X-API-Key: your-key

{
  "model": "meta/llama-3.1-8b-instruct",
  "messages": [
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi there!"},
    {"role": "user", "content": "What can you do?"}
  ],
  "system": "You are a helpful assistant.",
  "temperature": 0.7,
  "max_tokens": 1024
}

The response is an SSE stream with events: token (content chunk), error (error detail), done (completion signal).

Structured Error Responses

All error responses follow a consistent format:

{
  "detail": "Human-readable error message",
  "error_code": "MACHINE_READABLE_CODE"
}

How Routing Works

ModelRouter aggregates models from multiple AI providers behind a single API. Each model is cataloged with its publisher, capabilities, and availability status determined by periodic probe tests.

Capabilities

• chat — Conversational text generation
• code — Code generation and completion
• vision — Image understanding and analysis
• embedding — Vector embeddings for semantic search

Filtering Models

Use query parameters to filter the model list:

GET /api/models?capability=chat&publisher=meta&search=llama

Combine with /api/models/available to only get models that passed their last probe check.

Probe Tests

The Probes tab runs live endpoint checks against all models. Results are streamed in real time and stored as a report. Use GET /api/reports/latest to fetch the last report programmatically.

1. Create an Account

Sign up via the authentication panel in the sidebar. A verified email address is required.

2. Browse Available Models

Use the Models tab to explore all models. Filter by publisher or capability using the sidebar controls. Status dots indicate availability from the last probe run.

3. Start a Chat Session

On the Home tab, select an available model from the dropdown, optionally set a system prompt, and click Start Chat. Messages are streamed in real time.

4. Run Probes

Switch to the Probes tab to run endpoint checks. Configure parallel workers, delay, and timeout, then click Run Probes. Results stream into the terminal pane with color-coded status indicators.

5. API Integration

For programmatic access, generate a bot API key at bot.airanger.dev and use the endpoints listed in the Bot & Agent API Integration entry above. Start with GET /api/bot/spec for full API discovery.