REST API

Base URL: https://api.cleverouter.eu/v1. Authentication: Authorization: Bearer <key>.

Endpoint summary

Endpoint	Purpose	Kind
`POST /v1/chat/completions`	Chat (stream + non-stream)	`chat`
`POST /v1/embeddings`	Vector embeddings	`embedding`
`POST /v1/rerank`	Document re-ranking	`rerank`
`POST /v1/audio/transcriptions`	Speech-to-text (multipart upload)	`audio`
`GET /v1/models`	Live model registry	—

Every body and response shape follows the OpenAI spec — same SDKs, same serialisation.

`POST /v1/chat/completions`

Headers

Header	Required	Purpose
`Authorization: Bearer <key>`	yes	API key
`Content-Type: application/json`	yes	—
`X-CleverRouter-Strategy`	no	`default` `cheapest` `fastest` `best`
`X-CleverRouter-Provider`	no	`scaleway` `tensorix` `bedrock`
`Last-Event-ID`	no	SSE reconnect — set automatically by the SDK

Request body

Field	Type	Default	Notes
`model`	string	—	`<family>/<model>`
`messages`	array	—	OpenAI message-object shape
`stream`	boolean	`false`	Enable SSE
`temperature`	number	`1.0`	0–2
`max_tokens`	integer	—	Hard cap on completion tokens
`top_p`	number	`1.0`	Nucleus sampling
`tools`	array	—	See Function calling
`tool_choice`	string / object	`auto`	—
`response_format`	object	—	`{ type: 'json_object' }` or JSON Schema
`seed`	integer	—	Where the provider supports it
`reasoning_effort`	`low	medium	high`

Example

curl https://api.cleverouter.eu/v1/chat/completions \
  -H "Authorization: Bearer $CLEVERROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-CleverRouter-Strategy: cheapest" \
  -d '{
    "model": "mistral/mistral-small-3.2",
    "messages": [{ "role": "user", "content": "Hello." }]
  }'

Response headers

X-CleverRouter-Provider: scaleway
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 47
X-Request-Id: 0193adc8-…

`GET /v1/models`

curl https://api.cleverouter.eu/v1/models \
  -H "Authorization: Bearer $CLEVERROUTER_API_KEY"

curl 'https://api.cleverouter.eu/v1/models?kind=embedding' \
  -H "Authorization: Bearer $CLEVERROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "mistral/mistral-small-3.2",
      "object": "model",
      "kind": "chat",
      "owned_by": "mistral"
    }
  ]
}

Query filter: ?kind=chat | embedding | rerank | audio.

This endpoint is free — it doesn't count against your rate limit and never bills.

`POST /v1/embeddings`

curl https://api.cleverouter.eu/v1/embeddings \
  -H "Authorization: Bearer $CLEVERROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/embed-v4",
    "input": ["Hello from the EU."]
  }'

See Embeddings for encoding_format, dimensions, and the response shape.

`POST /v1/rerank`

curl https://api.cleverouter.eu/v1/rerank \
  -H "Authorization: Bearer $CLEVERROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/rerank-v3-5",
    "query": "EU GDPR",
    "documents": ["doc1", "doc2", "doc3"],
    "top_n": 2
  }'

See Rerank.

`POST /v1/audio/transcriptions`

Multipart form-data:

curl https://api.cleverouter.eu/v1/audio/transcriptions \
  -H "Authorization: Bearer $CLEVERROUTER_API_KEY" \
  -F file=@audio.mp3 \
  -F model=systran/faster-whisper-large-v3 \
  -F response_format=verbose_json

See Audio.

Error codes (quick reference)

HTTP	`error.code`	Meaning
400	`validation_error`	Bad request body
401	`unauthorized`	Missing or invalid key
402	`budget_exceeded`	Per-key budget reached
404	`model_not_found`	Model id not in the registry
410	`model_deprecated`	Model retired upstream
429	`rate_limit_exceeded`	Sliding-window rate limit hit
502	`provider_down`	Upstream 5xx with no healthy alternative
503	`provider_down`	All EU providers unavailable
504	`upstream_timeout`	Upstream read timeout

Full taxonomy with SDK error classes: Errors.

Closed beta

Sign-up is invite-only during the closed beta. Existing org admins can invite — see Organisations.

Errors — typed SDK handling.
Changelog — what's new.
Authentication — header details.

On this page