Skip to main content

API Reference

Complete reference for the Agentlify 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://agentlify.co/api/router

Use this as your base URL with any OpenAI-compatible SDK. Pass your router ID in the model field of each request — see below. Appending /v1 is also supported for full OpenAI SDK compatibility.

How Routers Work

Agentlify uses routers to handle model selection automatically. You don't choose models per request — the router does.

  1. Create a router in the dashboard with your preferred models and optimization strategy
  2. Get your router ID (e.g., router_abc123)
  3. Pass it as the model field in your request body — Agentlify reads it as the router ID and ignores it as a literal model name
  4. Router automatically selects the best model based on your configuration

💡 Tip: You can also embed the router ID directly in the URL path (/api/router/routerId) if your SDK or platform requires it — endpoint path always takes priority over the model field.

Endpoints

POST
/chat/completions
Create a chat completion

Request Body

messagesrequiredArray of message objects
modelrecommendedPass your router ID here — Agentlify reads this as the router to use and ignores it as a literal model name. The router selects the actual model automatically. Use agent:your-agent-name to invoke an agent instead.
streamoptionalBoolean (default: false)
temperatureoptionalNumber 0-2 (default: 1)
max_tokensoptionalMaximum tokens to generate
toolsoptionalArray of tool definitions

Example Request

json
POST https://agentlify.co/api/router/chat/completions
Authorization: Bearer mp_your_api_key

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

// Alternative: embed router ID in the URL path instead
// POST https://agentlify.co/api/router/router_abc123/chat/completions
// (model field can then be omitted or set to anything)

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"
  }
}
Agentlify Metadata

The _meta field contains additional Agentlify-specific information:

Router requests
  • 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
Agent requests model: agent:name
  • execution_id - Unique execution identifier
  • agent_name - Agent slug name
  • steps_executed - Number of workflow steps run
  • total_cost - Combined cost across all steps
  • total_latency - End-to-end latency in ms
  • models_used - Array of models used across steps

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