Routing API Reference

Quick Start

The routing layer is a drop-in replacement for the OpenAI API. Set baseURL to the SwarmSync endpoint and authenticate with your sk-ss-... key.

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.swarmsync.ai/v1',
  apiKey: process.env.SWARMSYNC_ROUTING_KEY, // sk-ss-...
});

const response = await client.chat.completions.create({
  model: 'auto',          // auto-routes to best model
  // model: 'economy',    // → economy tier (same as swarmsync/budget)
  // model: 'premium',    // → premium tier (same as swarmsync/performance)
  messages: [{ role: 'user', content: 'Your prompt here' }],
});

// Every response includes routing metadata
const meta = response.swarmsync;
console.log(meta.routed_model);     // e.g. "claude-sonnet-4-6"
console.log(meta.tier);             // "economy" | "mid" | "premium"
console.log(meta.complexity_score); // 0.0 – 1.0
console.log(meta.estimated_cost);   // USD including 8% platform fee

Authentication

All routing endpoints require a routing API key passed in the Authorization header.

Manage your keys at /console/settings/routing-keys. Keys are scoped per user account and track usage independently.

Endpoints

Base URL: https://api.swarmsync.ai

// Dry-run: see which model would be chosen without spending tokens
const res = await fetch('https://api.swarmsync.ai/v1/route', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-ss-...',
  },
  body: JSON.stringify({
    model: 'auto',
    messages: [{ role: 'user', content: 'Refactor this TypeScript class...' }],
  }),
});
const { model, tier, complexity_score } = await res.json();

Virtual Model Aliases

Pass one of these strings as the model field instead of a specific model ID to use the routing system. You can also pin a specific model (e.g. "claude-sonnet-4-6") to bypass routing entirely.

Routing Response Metadata

Every response from /v1/chat/completions includes a swarmsync object alongside the standard OpenAI fields. Use this to audit routing decisions, track cost savings, and tune your model strategy.

Parameters

All standard OpenAI chat completion parameters are supported and forwarded to the selected provider. The routing layer adds the model alias resolution on top.