API Reference | JoyToken

JoyToken currently exposes an OpenAI-compatible model gateway for developers. Applications can keep using OpenAI SDKs, LangChain, Cursor, Claude Code, Codex CLI, and other OpenAI-compatible tools. JoyToken adds API key validation, policy constraints, model routing, wallet freeze, and usage recording at the gateway layer.

This page only describes public interfaces that are present in the current project. Console, API key management, policy configuration, billing management, and similar backend APIs are currently used by JoyToken Console and are not documented as stable developer APIs.

Base URLs

Scenario	Base URL
OpenAI-compatible model calls	`https://api-dev.joytokens.ai/openai/v1`
Public model catalog	`https://api-dev.joytokens.ai`

Authentication

Model calls require a JoyToken API key. Use the Authorization header because it matches OpenAI SDKs and common AI tool configuration.

Recommended

Authorization: Bearer $JOY_TOKEN_API_KEY

The gateway currently also accepts X-API-Key, mainly for legacy clients and hand-written HTTP calls.

Compatibility

X-API-Key: $JOY_TOKEN_API_KEY

If both headers are present, the current gateway reads X-API-Key first. When migrating to Bearer authentication, do not keep the old X-API-Key on the same request.

Current Public Endpoints

Endpoint	API key required	Purpose
`POST /openai/v1/chat/completions`	Yes	OpenAI-compatible Chat Completions, with non-streaming and SSE streaming support
`GET /api/v1/models`	No	Public model catalog for the model marketplace, model picker, and integration discovery

Request Headers

Header	Required	Description
`Authorization`	Required for model calls	`Bearer $JOY_TOKEN_API_KEY`
`X-API-Key`	Optional	Compatibility authentication header; not recommended for new integrations
`Content-Type`	Recommended	`application/json`
`X-Request-ID`	Optional	Used for logs, billing troubleshooting, and trace correlation; when absent, the gateway generates an internal request ID

Response Headers

Header	Scenario	Description
`X-DAOE-Used-Model`	Successful model call	Actual model used
`X-DAOE-Used-Provider`	Successful model call	Provider that served the request
`X-DAOE-Failover`	Streaming call with provider failover	`1` means provider failover occurred

Response Metadata

For non-streaming successful calls, the gateway merges JoyToken metadata into the OpenAI-compatible JSON metadata field when possible. For streaming calls, it appends a metadata SSE record before [DONE].

Common fields:

Field	Description
`model`	JoyToken-selected model
`tier`	Actual billing/routing tier
`score`	Router score
`model_recommendation`	Candidate model recommendation details, when returned by router
`latency`	Routing, provider, and streaming stage latency
`billing.credits_used`	Credits calculated for this request
`billing.input_tokens` / `billing.output_tokens`	Input/output tokens used for billing

Error Shape

Model call errors use an OpenAI-compatible structure:

Error response

1 {
2   "error": {
3     "message": "missing api key",
4     "type": "missing_api_key"
5   }
6 }

When debugging, record X-Request-ID, request model / tier, HTTP status, error.type, and on successful responses the X-DAOE-Used-Model and X-DAOE-Used-Provider headers.