eurouter-integration

EUrouter Integration Guide

You are helping a developer integrate EUrouter into their application. EUrouter is a drop-in replacement for the OpenAI API, purpose-built for EU customers requiring GDPR compliance. It routes AI requests to 10 providers through a single OpenAI-compatible API at https://api.eurouter.ai.

Supported providers: OpenAI, Anthropic, Mistral, Scaleway (FR), GreenPT, Microsoft Foundry, Nebius, IONOS (DE), OVHcloud (FR), AWS Bedrock.

When helping developers, always load the relevant reference files from the references/ directory in this skill folder based on what they need. Do not load all references at once.

---

Authentication

EUrouter uses API keys in the format eur_<publicId>.<secret>.

Send the key via either header:

• Authorization: Bearer eur_...
• x-api-key: eur_...

For organization-scoped requests, add: x-org-id: <uuid>

Keys are created via POST /api/v1/keys and the full key is shown only once at creation. It cannot be retrieved later.

---

Drop-in Migration from OpenAI

EUrouter is designed as a drop-in replacement. Only two things change:

Python (openai SDK):

from openai import OpenAI

# Before (OpenAI direct)
# client = OpenAI(api_key="sk-...")

# After (EUrouter) — change base_url and api_key
client = OpenAI(
    base_url="https://api.eurouter.ai/api/v1",
    api_key="eur_YOUR_KEY_HERE"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

Node.js (openai SDK):

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.eurouter.ai/api/v1",
  apiKey: "eur_YOUR_KEY_HERE",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

Important: All existing OpenAI model names work as-is (e.g., gpt-4o, claude-3-5-sonnet, mistral-large-3). No model name changes needed when migrating.

---

Core Endpoints

All endpoints are prefixed with /api. Base URL: https://api.eurouter.ai

Endpoint	Method	Auth	Description
/api/v1/chat/completions	POST	Yes	Chat completions (streaming, tools, vision, audio, reasoning)
/api/v1/completions	POST	Yes	Legacy text completions
/api/v1/embeddings	POST	Yes	Text embeddings
/api/v1/responses	POST	Yes	OpenAI Responses API compatible
/api/v1/models	GET	No	List/filter model catalog
/api/v1/providers	GET	No	List available providers
/api/v1/credits	GET	Yes	Check credit balance (EUR)
/api/v1/keys	CRUD	Yes	Manage API keys
/api/v1/routing-rules	CRUD	Yes	Manage named routing configs
/health	GET	No	Health check

For full endpoint schemas, load references/endpoints.md.

---

EU/GDPR Compliance

This is EUrouter's key differentiator. Add a provider object to any generation request to enforce compliance:

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello"}],
  "provider": {
    "data_residency": "eu",
    "eu_owned": true,
    "data_collection": "deny",
    "max_retention_days": 0
  }
}

Field	Type	Description
data_residency	string	Region code — "eu", "de", "fr", etc. Only endpoints in that region
eu_owned	boolean	Only EU-headquartered providers (Scaleway, IONOS, OVHcloud, GreenPT, Mistral)
data_collection	"allow" | "deny"	"deny" excludes providers that use data for training
max_retention_days	number	Max data retention. 0 = zero-data-retention only

Ready-to-use compliance profiles:

// Strict GDPR: EU owned, no training data, zero retention, EU hosted
{ "eu_owned": true, "data_collection": "deny", "max_retention_days": 0, "data_residency": "eu" }

// EU hosted, cheapest price
{ "data_residency": "eu", "sort": "price" }

// Specific EU providers only
{ "only": ["scaleway", "ionos", "ovhcloud"] }

For all provider preference fields, load references/provider-preferences.md.

---

Model Fallback

Pass a models array to try multiple models in order. If all providers for the first model fail, EUrouter tries the next:

{
  "models": ["claude-3-5-sonnet", "gpt-4o", "mistral-large-3"],
  "messages": [{"role": "user", "content": "Hello"}],
  "provider": { "data_residency": "eu" }
}

Note: Model fallback is NOT supported for embeddings (vector dimensions differ between models). Only provider fallback (same model, different provider endpoint) works for embeddings.

---

Routing Rules

Create reusable routing configurations to avoid repeating provider preferences on every request:

// Create a rule once:
// POST /api/v1/routing-rules
{
  "name": "gdpr-strict",
  "provider": {
    "eu_owned": true,
    "data_collection": "deny",
    "max_retention_days": 0,
    "data_residency": "eu"
  }
}

// Then reference it by name:
{
  "model": "gpt-4o",
  "rule_name": "gdpr-strict",
  "messages": [{"role": "user", "content": "Hello"}]
}

You can also reference by UUID with rule_id. Per-request provider preferences merge with the rule — request-level values take precedence.

Dry-run testing: Use POST /api/v1/routing-rules/dry-run to preview which providers satisfy a routing config without making a real request.

For full routing rules API, load references/routing-rules.md.

---

Model Discovery

GET /api/v1/models
GET /api/v1/models?provider=scaleway
GET /api/v1/models?supported_parameters=tools,vision
GET /api/v1/models?category=embedding

Prices are returned as strings in the model's pricing object with a currency field. Credits are in EUR.

---

Response Headers

Every generation endpoint returns routing transparency headers:

Header	Description
x-provider-id	Internal provider UUID
x-provider-slug	Provider name (e.g., openai, scaleway)
x-routing-strategy	Strategy used for routing
x-model-used	Actual model slug used
x-model-variant	Variant suffix if applicable (:free, :nitro)
x-fallback-count	Number of provider fallbacks (only present if > 0)
x-model-fallback-count	Number of model fallbacks (only present if > 0)

---

Streaming

Set "stream": true for SSE streaming. Format is OpenAI-compatible:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0,"finish_reason":null}]}

data: [DONE]

For usage stats in the final chunk, add "stream_options": { "include_usage": true }.

---

Error Format

All errors follow:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Model not found"
  },
  "requestId": "uuid"
}

Key error codes: UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), BAD_REQUEST (400), INSUFFICIENT_QUOTA (402), SERVICE_UNAVAILABLE (503).

---

Reference Files

Load these based on the developer's specific need:

Need	File
Full endpoint request/response schemas	references/endpoints.md
All provider routing preference fields	references/provider-preferences.md
Routing rules CRUD + dry-run API	references/routing-rules.md
Python code examples (openai SDK)	references/code-examples-python.md
Node.js/TypeScript code examples	references/code-examples-node.md
curl examples	references/code-examples-curl.md