Radient API Reference

The Radient API is one HTTP surface over one balance. Inference, tools, usage and billing calls all live under a single base URL and are paid for from your Radient Pass:

https://api.radienthq.com/v1

Everything except the health check is under /v1. Responses are JSON; request bodies are JSON unless stated otherwise.

# The smallest useful call: check the API is up.
curl https://api.radienthq.com/health
# {"msg":"OK"}

#Authentication at a glance

Send exactly one credential in the Authorization header:

Authorization: Bearer YOUR_API_KEY

• API key (rad-prod-…) — for servers and tools calling inference and tool endpoints. Create one in the console's Applications page.
• User token — for anything tenant- or account-scoped: keys, usage, billing, members, plans, transfers.
• Client token — only for the public contact form.

A missing credential answers 401 {"error":"missing Authorization header"}. Full detail, including which credential reaches which routes and the key-revocation behaviour: Authentication.

#Response conventions

Two success shapes exist:

• Raw JSON (OpenAI-shaped, no envelope): chat completions, completions, embeddings, decisions, models, the account usage summary, and the tools endpoints that answer JSON directly (search, media). Transcription answers the result envelope, and speech answers audio with X-Radient-Cost-* headers.
• Envelope {"msg": "…", "result": …}: everything else — applications, tenants, usage records and rollups, billing, ledger, auto-reload, transfers, members, invites, plans, billing sources, agents and teams, notifications, prices, client-token.

Billed calls also answer with a versioned cost object stating what the call charged — top level on raw bodies, inside result on the enveloped tool responses. See Cost reporting.

Error responses are one shape everywhere:

{ "error": "insufficient credits" }

Some errors add a machine-readable code and optional details:

{ "code": "idempotency_key_required",
  "error": "an Idempotency-Key header of 16-128 [A-Za-z0-9_-] characters is required" }

{ "code": "transfer_insufficient_giftable", "details": { "giftable": 0 },
  "error": "granted credits can no longer be transferred" }

The error string is stable for a given cause; match on status and code where present, and treat error as human-readable text.

#Status codes and common bodies

#The credit gate

Paid routes are admitted by a credit gate before any work is sent to a model. It applies to:

• POST /v1/chat/completions, POST /v1/completions, POST /v1/embeddings, POST /v1/decisions
• every route under /v1/tools/… except GET /v1/tools/media/status, GET /v1/tools/media/result, POST /v1/tools/media/cancel, GET /v1/tools/media/models, and GET /v1/tools/speech/voicing

Note that read-only-looking tool calls such as GET /v1/tools/search and GET /v1/tools/images/providers are gated too: they are priced calls.

How it works:

1. Estimate. The API estimates the maximum cost of the call from the model's published rates, your prompt and your max_tokens / max_completion_tokens (assumed 8192 when absent). When the cost cannot be estimated — the literal auto model id, tool submissions, bodies it cannot parse — the reservation is a flat $1.00. Decision requests reserve their own estimate, capped at $0.30.
2. Reserve. The estimate is held against your account's in-flight budget (released after 10 minutes if the call never settles).
3. Admit. The call is admitted only if balance − (others' in-flight holds) − floor ≥ estimate. The floor is −$1.00 for accounts that have ever been funded with real money, and $0 otherwise. A funded account can therefore go slightly negative once; a promotional-only balance cannot dip below zero.

Example: on an account holding $0.50, model: "auto" (flat $1.00 reservation) answers 402 {"error":"insufficient credits"}, while a named model with a small max_tokens is admitted.

Refusals:

After the call, the actual cost is written to your ledger and the reservation is released. Streaming calls bill when the stream ends. Media generations are charged when their result is first observed — poll GET /v1/tools/media/status or /result, because a generation that is never fetched is never charged and its reservation expires after two hours.

#Cost reporting

Billed calls answer with a versioned cost object stating what the call charged, in USD. The object is additive: every field that existed before keeps its meaning, and a client that does not read it sees the same responses as always.

"cost": {
  "v": 1,
  "amount_usd": 0.0001627,
  "basis": "billed",
  "units": 1447,
  "unit": "token",
  "provider": "openrouter",
  "model": "openai/gpt-6-luna-pro",
  "usage_record_id": "6ac9dfbf705ad8633a87dfc4"
}

(The figure above is a chat completion's charge from a live call.)

#The cost object

Two reading rules. Amounts are the stored doubles, never re-rounded for display, so a figure can show representation noise (0.00030000000000000003 is ordinary): round for display and reconcile by numeric value, never by comparing decimal strings. And keys are omitted when they do not apply — absence is not zero; v, amount_usd and basis are always present when the object is.

basis says what the amount is:

#Where to read the charge, per surface

How the object is emitted, in brief: charged calls carry it; error responses and credit-gate refusals (401 / 402) do not — nothing was admitted, nothing was charged. A settled zero (a failed media generation; a decision answered with no readable usage) is billed with amount 0 — a recorded zero, distinguishable from silence. And absence is never "free": a streamed turn with no usage frame is still billed, and the usage surface is the check.

#Reconciling a charge

cost.usage_record_id joins a response to the server-side record of its charge:

1. take the id from the response;
2. GET /v1/tenants/{tenant_id}/usage — the record whose id equals it; its cost equals amount_usd;
3. GET /v1/tenants/{tenant_id}/billing/ledger — the debit whose reference_id equals the same id, with amount equal to the same figure.

Both routes need a user token, and the usage row is written asynchronously after the response — an id can briefly precede its row, and a missing row is not permission to read the call as uncharged. A zero-cost success writes no ledger row, and a team-paid call debits the payer's account rather than yours. The full set of caveats — including what a media quote's id means before settlement — is in Usage and credits API.

#Client correlation headers

Two optional headers let your logs point at the server-side record of a call: X-Radient-Client-Session-Id and X-Radient-Client-Request-Id.

• The grammar is [A-Za-z0-9._:-]{1,64}; anything else is ignored — never a 400, because an optional telemetry header must not fail a paid request.
• The values are opaque: never parsed as money, never used for routing, never logged. A session id means whatever your client means by it.
• A valid value is stored on your own usage row (client_session_id, client_request_id — additive fields, omitted when absent) and is readable back only through the tenant-scoped usage surface. A media generation captures the values at submission and writes them with the settlement charge.

#Rate cards

GET /v1/prices (no auth) publishes the platform's rate cards for pre-call estimates — per-character speech prices, per-second transcription, per-search and per-email charges — alongside the promotional credit amounts. It is served with an ETag and Cache-Control: public, max-age=300: revalidate with If-None-Match after the TTL instead of pinning figures — a match (including the weak form a proxy may hand you) answers 304 Not Modified. Estimates are advisory; the cost object on the response is the record of what was charged. See Usage and credits API.

#Rate limits

What is enforced today:

• There is no request-rate limit on the paid inference and tools routes (chat, completions, embeddings, decisions, search, speech, transcription, images, media). They are bounded only by the credit gate and by the serving models' own limits. No X-RateLimit-* headers are emitted; the only rate header is Retry-After on the routes below.
• Publishing and uploading (agents and hub teams) is rate-limited: per-IP 1 request / 15 s (burst 10) and per-account 1 / 60 s (burst 10), answering 429 {"error":"Too many publish requests. Wait a moment and try again.","code":"rate_limited"} with Retry-After.
• Signup verification is rate-limited per source address (claim: 1 per 5 s).
• Invites and transfer invitations: reading an invite token is limited (1/s, burst 5), sending is capped at 3 emails per address per day, and a transfer resend has a 12-hour cooldown.

If you need higher throughput than a serving model allows, use a different model or spread requests across models.

#CORS

The API sets permissive CORS for browser callers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Expose-Headers: Retry-After

Two consequences for browsers:

• PATCH is not in the allowed methods and Idempotency-Key is not in the allowed headers. A cross-origin browser call using either fails its preflight. Server-to-server callers (which do not preflight) are unaffected.
• Credentials are not used: the Authorization header is what authenticates, and Allow-Origin: * means any site can call the API with a key it already has — so never embed your key in a page. Keep keys server-side.

#Versioning

The path prefix /v1 is the version. Within it, changes are additive: new endpoints and new response fields may appear at any time, and clients should ignore fields they do not know. Behaviour that would break an existing integration is shipped under a new prefix.

#The route list

Every client-callable route, grouped by surface. “Gate” marks the credit gate; “Auth” column values: Key = application API key, User = user token, Both = either, None = anonymous, Optional = anonymous allowed with richer results when authenticated.

#Inference

#Tools

#Usage and billing

#Account, applications and keys

#Team and membership

#Agents and hub teams

Writes in the last two groups are rate-limited (see Rate limits).

#Sign-in, tokens and web

#Other endpoints

• Personal tunnels (/v1/tunnels/…) are a separate bearer scheme used by the tunnel connector and your authorized browsers; they are managed from the Tunnels page and documented in Personal Tunnels. They are not part of the API-key surface.
• Service-account and internal routes (operator billing, OAuth client registration, plan grants, Stripe webhooks) are intentionally not documented here and are not callable with customer credentials.
• The console (console.radienthq.com) is the supported way to manage plans, payment methods, tunnels and team settings; its screens call a mix of these routes on your behalf.

#Where to go next

• Authentication — keys, tokens and revocation.
• Chat API · Embeddings API · Decisions API · Speech API · Transcription API · Search API · Image API · Video and media API
• Usage and credits API — balances, ledger, auto-reload, transfers, team pooling.
• Radient Automatic — the auto model and reasoning effort.