OpenRouter API Integration

A unified API gateway for accessing 400+ LLM models with standardized interfaces for tool calling, structured outputs, and context management.

Overview

OpenRouter provides a single API endpoint that normalizes the schema across all supported models and providers, meaning developers only need to learn one API format to access models from OpenAI, Anthropic, Google, Meta, and many others. This makes it ideal for building AI-powered documentation assistants that need flexibility in model selection.

API Fundamentals

Base Configuration

Required Headers

const headers = {
  'Authorization': 'Bearer <OPENROUTER_API_KEY>',
  'Content-Type': 'application/json',
  'HTTP-Referer': '<YOUR_SITE_URL>',      // Optional: for app attribution
  'X-Title': '<YOUR_APP_NAME>'            // Optional: for app attribution
};

The HTTP-Referer and X-Title headers are optional but recommended for app attribution and discoverability on the OpenRouter platform.[Source: OpenRouter API Reference]

Model Fetching and Selection

Models API

OpenRouter provides programmatic access to browse and filter all available models. The Models API returns detailed information about each model's capabilities, pricing, and supported parameters.

// Fetch all available models
const response = await fetch('https://openrouter.ai/api/v1/models');
const { data: models } = await response.json();

// Filter models that support tool calling
const toolCapableModels = models.filter(
  model => model.supported_parameters?.includes('tools')
);

Model Object Schema

Recommended Models for Documentation Assistants

Model Parameters

Complete Parameter Reference

System Instructions

Message Roles

OpenRouter supports four message roles:

Assistant Prefill

OpenRouter supports asking models to complete a partial response, which is useful for guiding response format:

const messages = [
  { role: 'system', content: systemPrompt },
  { role: 'user', content: 'How do I implement RAG?' },
  { role: 'assistant', content: 'Based on the documentation:\n\n' }
];

Context Management

Message Transforms (Middle-Out Compression)

When prompts exceed context limits, OpenRouter's middle-out transform automatically compresses them by removing or truncating messages from the middle of the prompt until it fits within the model's context window. This preserves the most recent context and system instructions.

{
  "model": "anthropic/claude-sonnet-4.5",
  "messages": [...],
  "transforms": ["middle-out"]
}

RAG Implementation

Embeddings API

OpenRouter provides an embeddings endpoint for generating vector representations, essential for RAG implementations:

const response = await fetch('https://openrouter.ai/api/v1/embeddings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'openai/text-embedding-3-small',
    input: 'Text to embed'
  })
});

const { data } = await response.json();
const embedding = data[0].embedding; // Vector array

Tool Calling

Overview

Tool calling (function calling) allows LLMs to request external tool execution. The LLM doesnot call tools directly—it suggests which tool to call with what arguments. The application executes the tool and returns results to the LLM.

Three-Step Process

Step 1: Send request with tool definitions

const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    model: 'anthropic/claude-sonnet-4.5',
    messages: [
      { role: 'user', content: 'Search the documentation for RAG' }
    ],
    tools: [
      {
        type: 'function',
        function: {
          name: 'search_documentation',
          description: 'Search the documentation for relevant sections',
          parameters: {
            type: 'object',
            properties: {
              query: { type: 'string', description: 'Search query' }
            },
            required: ['query']
          }
        }
      }
    ]
  })
});

Step 2: Execute tool locally

const result = response.choices[0];
if (result.finish_reason === 'tool_calls') {
  const toolCall = result.message.tool_calls[0];
  const args = JSON.parse(toolCall.function.arguments);
  
  // Execute the tool
  const searchResults = await searchDocumentation(args.query);
}

Step 3: Return results to LLM

const finalResponse = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    model: 'anthropic/claude-sonnet-4.5',
    messages: [
      ...previousMessages,
      {
        role: 'tool',
        tool_call_id: toolCall.id,
        content: JSON.stringify(searchResults)
      }
    ],
    tools: [...] // Include tools again
  })
});

Tool Choice Configuration

// Let model decide (default)
{ tool_choice: 'auto' }

// Disable tool usage
{ tool_choice: 'none' }

// Force specific tool
{
  tool_choice: {
    type: 'function',
    function: { name: 'search_documentation' }
  }
}

MCP Integration

Converting MCP to OpenRouter Format

OpenRouter supports MCP (Model Context Protocol) tool definitions by converting them to OpenAI-compatible format:

// MCP tool definition
const mcpTool = {
  name: 'search_docs',
  description: 'Search documentation',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string' }
    },
    required: ['query']
  }
};

// Convert to OpenRouter format
const openRouterTool = {
  type: 'function',
  function: {
    name: mcpTool.name,
    description: mcpTool.description,
    parameters: mcpTool.inputSchema
  }
};

Structured Outputs

Use structured outputs to enforce JSON schema validation on model responses, which is essential for building reliable, hallucination-resistant systems:

{
  "model": "openai/gpt-4o",
  "messages": [...],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "verified_response",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "answer": { "type": "string" },
          "confidence": { "type": "number" },
          "citations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "claim": { "type": "string" },
                "source": { "type": "string" }
              }
            }
          }
        },
        "required": ["answer", "confidence", "citations"]
      }
    }
  }
}

References

1. OpenRouter API Reference Overview
2. OpenRouter Models Documentation
3. OpenRouter Parameters Documentation
4. OpenRouter Message Transforms
5. OpenRouter Embeddings API
6. OpenRouter Tool Calling
7. OpenRouter MCP Servers Guide
8. OpenRouter Structured Outputs