API Reference

Overview

above.dev exposes inference endpoints under https://api.above.dev/v1. You choose the model with the standard model field in the request body, or with the x-model header. If you name no model, the request is served by a fixed default.

Two routing modes are available:

• Default mode — if you name no model, the request is served by a single fixed default model. Nothing inspects your prompt.
• 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.1-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, or just set the model field in the body, which most clients do for you. Either way your request goes to exactly the model you name. This 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" \
  -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_model, naming that model's ceiling.

Every model in the catalog accepts up to 131,072 output tokens. The two free-tier routes, glm-5.3-flash-modal and deepseek-v4.1-flash-modal, are capped at 16,384 instead, because they share a fixed concurrency pool. A max_tokens above the cap is reduced to it rather than rejected, and each model reports its own figure as max_completion_tokens in GET /v1/models.

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. Tiers are descriptive, to help you pick a model: nothing routes on them automatically.