API Reference

Overview

above.dev exposes inference endpoints under https://api.above.dev/v1. Requests are routed in real time to the best available model. You can influence routing via request headers — or let above.dev decide automatically.

Two routing modes are available:

• Auto mode (default) — above.dev classifies your request and picks the optimal model by tier, live load, and workload type.
• Direct mode — You specify exactly which model to use via x-model.

Some models are TEE-enabled. The model catalog shows which models support TEE.

Authentication

All requests require a Bearer token in the Authorization header. API keys are issued after purchase at above.dev/pricing and follow the format sk-gw-….

Authorization: Bearer sk-gw-<your-api-key>

Quick start

Send your first request in under a minute:

curl -X POST https://api.above.dev/v1/messages \
  -H "Authorization: Bearer sk-gw-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Summarise the key steps of a RAG pipeline." }
    ],
    "max_tokens": 1024
  }'

POST /v1/messages

The primary inference endpoint. Accepts a messages payload and returns a completion.

Request body

POST /v1/chat/completions

An OpenAI-compatible alias that delegates to /v1/messages. Use this as a drop-in replacement if your SDK or framework targets the OpenAI API format.

Routing headers

These request headers control how above.dev routes your request. All are optional — omitting them serves the request with the default model. You can also select a model with the standard OpenAI model field in the request body, which most clients set for you.

Auto mode

If you omit model (and the x-model header), the request runs in auto mode and is served by deepseek-v4-flash — the cheapest model in the catalog. The aliases smart-select, gateway-auto and auto resolve the same way, so clients that expect a routing model id keep working.

Auto mode is a sensible default, not a classifier: it does not inspect your prompt to pick a model. For anything where model choice matters, name the model explicitly with direct mode below — that is the recommended path for production traffic.

curl -X POST https://api.above.dev/v1/messages \
  -H "Authorization: Bearer sk-gw-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Fix this bug: ..." }],
    "max_tokens": 2048
  }'

Direct mode

Use x-mode: direct with x-model to target a specific model. The availability scorer is bypassed — your request goes to exactly the model you specify.

curl -X POST https://api.above.dev/v1/messages \
  -H "Authorization: Bearer sk-gw-<your-key>" \
  -H "Content-Type: application/json" \
  -H "x-mode: direct" \
  -H "x-model: deepseek-v4-pro" \
  -d '{
    "messages": [{ "role": "user", "content": "..." }],
    "max_tokens": 4096
  }'

Response headers

Every response includes metadata headers describing what happened:

Streaming

Set "stream": true in your request body to receive a Server-Sent Events stream. Each event follows the standard SSE format with a data: prefix. The stream terminates with data: [DONE].

import requests, json

resp = requests.post(
    "https://api.above.dev/v1/messages",
    headers={
        "Authorization": "Bearer sk-gw-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "messages": [{"role": "user", "content": "Write a sorting algorithm."}],
        "max_tokens": 2048,
        "stream": True,
    },
    stream=True,
)

for line in resp.iter_lines():
    if line and line.startswith(b"data: "):
        data = line[6:]
        if data == b"[DONE]":
            break
        chunk = json.loads(data)
        print(chunk, flush=True)

Limits

Limits apply per account, across all of your API keys.

A model's own context window is the ceiling; exceeding it returns 413 input_too_large_for_modelnaming the model's ceiling. Need higher limits? Email support@realtimecomms.co.uk.

Errors

All errors return JSON with an error field describing the issue.

Model catalog

The active model catalog is exposed through GET /v1/models. Provider names are shown as above.dev in customer-facing surfaces.

Where two prices are shown, the model uses time-of-day pricing: peak hours are 01:00 to 04:00 and 06:00 to 10:00 UTC on weekdays, and all other hours bill at the lower off-peak rate. Weekends are entirely off-peak: the provider defines its weekend in Beijing time, so that runs from 16:00 UTC Friday to 16:00 UTC Sunday. Cache-hit input is billed separately and more cheaply wherever the upstream provider reports it. Every response carries its exact cost in the x-cost-usd header, so billing is verifiable per request.

Why cache pricing dominates agent costs

An agent session re-sends the growing conversation on every tool call. After 50 calls the original prompt has been billed roughly 50 times, and on typical coding-agent traffic 80 to 95% of all input tokens are served from the provider's prompt cache. That makes the cache-hit rate, not the headline input price, the number that decides what a session costs. We pass the full upstream cache discount through: DeepSeek's 97% discount (cache hits from $0.0077/M off-peak on V4 Flash) and Fireworks' 10x discount on GLM 5.2 ($0.154/M, where the official API's own rate is $0.26/M). You can verify your cache performance on every response via the x-input-cache-hit-rate header.

Tier system

Models are grouped into four capability tiers. Auto routing uses tiers as a primary signal alongside live utilisation.