Compatibility and product differences

Cloakray provides one inference API and discounted model access. Compatible request shapes do not mean a shared account, identical product entitlements or unrestricted access to every model a reference service lists. See the endpoint reference for exact paths and formats.

Models and discovery

Use canonical public IDs from GET /v1/models, including namespaces containing /. A slash can be part of a canonical model ID; do not strip it or invent a serving-provider prefix. Aliases resolve only when the catalogue declares them.

Discovery is not invocation permission. A published record, a package record, a registered route and a successful paid request are different evidence. Public listings can change between releases, and model availability depends on your account and the selected endpoint. Never infer “all package records work” from a package count.

endpoints is the currently callable subset, while declared_endpoints is the full interface declaration. Check api_availability for the requested endpoint: available, unavailable and unverified are distinct states, and an overall availability: "available" does not certify every interface.

Reference option	Product boundary
`mapped=true`	Unsupported: serving-provider-pinned mappings are not public.
`include_restricted=true`	Cannot expose another customer's private models or bypass your invocation entitlements.
`include_deactivated`, `exclude_deprecated`	Only supported when retirement metadata can be enforced; otherwise the API must explicitly reject the filter.
`no_training`	Only supported when its data-handling guarantee can be enforced; do not treat an unrecognized filter as a guarantee.

Authenticated discovery is private and not a shared cache response. Invalid supplied credentials must fail, even where public unauthenticated discovery exists. Use your own key when building a model picker for a particular workspace.

OpenAI and Anthropic SDKs

For the OpenAI SDK, set the base URL to https://api.cloakray.com/v1. For Anthropic, use https://api.cloakray.com; its SDK appends /v1/messages. Keep the project key on your server. See the quickstart for working text examples.

The SDK may expose methods that are not registered here. /v1/completions, /v1/models/{model_id} and /v1/systemone are not compatibility routes. Use /v1/chat/completions and /v1/decisions. Stored Responses retrieval and compaction have explicit contracts; their presence does not imply cancel or delete routes.

AI SDK Gateway protocol

The AI SDK Gateway wire protocol is separate from OpenAI-compatible JSON. Its public prefixes are /v1/ai, /v2/ai, /v3/ai and /v4/ai. Each has POST /language-model and authenticated GET /config.

AI SDK configuration lists canonical model IDs only. Function tools, supported multimodal inputs and streams use their versioned protocol. Unsupported native tools or providerOptions produce typed warnings rather than being presented as implemented.

A request carries the model in ai-language-model-id, not the JSON body's model. ai-language-model-streaming: true enables streaming. ai-language-model-specification-version selects version 2, 3 or 4; absent or unrecognized values use 4 in the reference. Version 2 uses flat token usage while versions 3 and 4 use nested input/output counts. The URL prefix alone does not select the wire format.

curl "https://api.cloakray.com/v4/ai/language-model" \
-H "Authorization: Bearer $CLOAKRAY_API_KEY" \
-H "Content-Type: application/json" \
-H "ai-language-model-id: $MODEL" \
-H "ai-language-model-specification-version: 4" \
-H "ai-language-model-streaming: false" \
-d '{"prompt":[{"role":"user","content":[{"type":"text","text":"Hello"}]}]}'

GET /v1/key describes your local API-key scope and entitlements. GET /v1/credits describes your local organization's balance and usage. Neither returns the balance, credentials, IDs or permissions of a shared account elsewhere. Token Plan allowances are not automatically interchangeable with pay-as-you-go credit.

MCP and OAuth

/mcp is a separate Model Context Protocol interface, not a URL to substitute into an OpenAI client. The reference offers stateless Streamable HTTP JSON-RPC with POST; older GET/SSE/session behavior is a distinct compatibility mode, not proof every MCP transport is offered.

The current implementation offers stateless POST JSON/SSE only; GET /mcp returns 405. Legacy SSE/session transport and provider-analytics tools are not offered. OAuth supports authorization_code with S256 and one exact registered redirect URI. Local tokens last one hour; refresh tokens and client_credentials grants are not offered. These are intentional differences from the reference, not equivalent substitutes.

OAuth discovery uses /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource, with /mcp-suffixed discovery variants. The flow uses GET /oauth/authorize, POST /oauth/register and POST /oauth/token. Identity, user consent, token scope, expiry and revocation must belong to this service. Authorization codes and redirect URIs must be validated, and PKCE uses S256. A shared upstream API key is never a customer's MCP credential.

Use https://api.cloakray.com/mcp only with an MCP client and an authentication flow this deployment advertises. OpenAI SDK compatibility alone is not MCP or OAuth compatibility; an unavailable protocol must fail explicitly, not expose somebody else's account.

Privacy and stored content

Public responses retain generated content and caller metadata, but do not expose the serving provider, provider mappings, internal model names, upstream cost fields, internal media URLs, account IDs or credentials. A model creator's name in the public catalogue is not a disclosure of who served an individual request. Errors remain neutral rather than naming internal routing services.

Do not send a long-lived API key to browser code or in a query string. Stored response and video IDs remain project-scoped, including lookups through aliases.

Responses storage is explicit: the reference stores responses for 30 days by default, and store: false is required for a non-stored request. Do not promise zero retention for stored responses. A service's own minimal accounting records are not a promise about every model's content-retention policy; consult the applicable terms and choose supported data-handling options.

Realtime

Realtime WebSocket sessions (/v1/realtime and /v1/realtime/client_secrets) are not offered yet. Models that are served only through realtime sessions are not listed.

Pricing and Token Plans

Prices describe the model's list-price basis and the discount applicable to your organization, not the serving provider's internal cost. No gateway fees are added on requests or top-ups. Units vary by capability; page, duration, character or request prices must not be represented as ordinary text-token prices.

API compatibility does not expand a Token Plan. New non-text capabilities are pay-as-you-go unless explicitly included. Existing image inclusion switches, model exclusions, active plan limits and deployment billing modes remain in force. A disabled purchase mode does not erase an existing balance or cancel an existing plan.

Versioned contract

The anonymous, cacheable public OpenAPI document publishes the current contract version and this deployment's API origin. It documents local account and OAuth contracts, not another service's account, and distinguishes supported stateless MCP from rejected legacy methods.