API Reference

Complete reference for the ModelPilot API with all endpoints, parameters, and examples.

Authentication

API Key Authentication

Include your API key in the Authorization header

http

Authorization: Bearer mp_your_api_key_here

Note: All API keys start with mp_

Base URL

http

https://modelpilot.co/api/router/{router_id}

Replace {router_id} with your actual router ID from the dashboard.

How Routers Work

ModelPilot uses routers to handle model selection automatically. You don't choose models per request.

Create a router in the dashboard with your preferred models and optimization strategy
Get your router ID (e.g., router_abc123)
Include router ID in URL for all API calls
Router automatically selects the best model based on your configuration

💡 Tip: Leave the model parameter empty in requests to let the router optimize.

Endpoints

POST

/chat/completions

Create a chat completion

Request Body

messagesrequiredArray of message objects

modeloptionalLeave empty - router automatically selects best model

streamoptionalBoolean (default: false)

temperatureoptionalNumber 0-2 (default: 1)

max_tokensoptionalMaximum tokens to generate

toolsoptionalArray of tool definitions

Example Request

json

POST https://modelpilot.co/api/router/router_abc123
Authorization: Bearer mp_your_api_key

{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 150
}

Response

json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699999999,
  "model": "mistralai:ministral-8b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  },
  "_meta": {
    "modelUsed": "mistralai:ministral-8b",
    "cost": 0.00045,
    "latencyMs": 850,
    "carbonGrams": 0.12,
    "routerDecision": "cost_optimized"
  }
}

ModelPilot Metadata

The _meta field contains additional ModelPilot-specific information:

modelUsed - Actual model selected by router
cost - Total cost in USD
latencyMs - Response time in milliseconds
carbonGrams - CO2 emissions in grams
routerDecision - Routing strategy used

Error Codes

400

Bad Request

Invalid request parameters or missing required fields

401

Unauthorized

Invalid or missing API key

404

Not Found

Router ID not found or endpoint does not exist

429

Rate Limit Exceeded

Too many requests, please slow down

500

Internal Server Error

Unexpected server error, please try again

503

Service Unavailable

All models temporarily unavailable