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/{routerId}

Replace {router_id} with your actual router ID from the dashboard. Appending /v1 ensures full OpenAI SDK compatibility.

How Routers Work

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

  1. Create a router in the dashboard with your preferred models and optimization strategy
  2. Get your router ID (e.g., router_abc123)
  3. Use the Router URL as your base URL in OpenAI SDKs
  4. 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 for router auto-selection, or set to agent:your-agent-name to invoke an agent
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/{routerId}/chat/completions
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"
  }
}
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