# info.description
Machine-readable contract for stable NanoGPT public API endpoints. This spec intentionally omits browser-session and account-management routes that are not safe to treat as public API-key endpoints.

# paths./api/v1/chat/completions.post.summary
Create an OpenAI-compatible chat completion

# paths./api/v1/chat/completions.post.description
Routes an OpenAI-compatible chat completion request to a NanoGPT model. Streaming responses use Server-Sent Events.

# paths./api/v1/chat/completions.post.responses.200.description
Chat completion object or SSE stream when stream is true

# paths./api/v1/responses.post.description
Creates a response using the OpenAI Responses API shape. Supports streaming, background processing, tools, multimodal input, and optional storage.

# paths./api/v1/responses.post.responses.200.description
Response object or SSE stream when stream is true

# paths./api/v1/messages.post.description
Accepts Anthropic Messages request bodies and returns Anthropic-compatible responses.

# paths./api/v1/messages/count_tokens.post.summary
Count tokens for an Anthropic-compatible message request

# paths./api/v1/completions.post.summary
Create a legacy OpenAI-compatible text completion

# paths./api/v1/completions.post.description
Best-effort legacy completions endpoint. Prefer /api/v1/chat/completions for new integrations.

# paths./api/personalized/v1/models.get.description
Returns an OpenAI-compatible model list scoped to the authenticated account's visible model preferences.

# paths./api/v1/images/generations.post.summary
Create an OpenAI-compatible image generation

# paths./api/v1/api-keys/current.get.summary
Retrieve metadata and usage for the current API key

# paths./api/v1/usage.get.description
Returns bounded, aggregate usage for the authenticated API key. Defaults to the current API key and the last 30 UTC days. totalTokens is inputTokens + outputTokens; reasoningTokens is reported separately. Legacy usage query parameters such as duration, page, pageSize, sort, dir, filter, weekOffset, tz, and include_summary are rejected.

# paths./api/v1/usage.get.parameters[].description
current_key and api_key both return the authenticated API key's usage.

# paths./api/v1/usage.get.parameters[].description
Optional current API key id. Requests for a different API key are rejected.

# paths./api/v1/usage.get.parameters[].description
Start date in UTC, formatted as YYYY-MM-DD. Must be used with to.

# paths./api/v1/usage.get.parameters[].description
End date in UTC, formatted as YYYY-MM-DD. Inclusive. Must be used with from.

# paths./api/v1/usage.get.parameters[].description
Controls which aggregate arrays are returned. Defaults to day,model. model,day is accepted as an alias for day,model.

# paths./api/check-balance.post.summary
Check account balance for the authenticated API key

# paths./api/transaction/status/{ticker}/{txId}.get.description
Poll the status of an API-key-compatible crypto deposit request. Fiat checkout status, including usd, is not part of this public GET contract.

# paths./api/v1/private/tinfoil/status.get.summary
Describe NanoGPT Private Mode for Tinfoil

# paths./api/v1/private/tinfoil/status.get.responses.200.description
Private Mode status and visibility contract

# paths./api/v1/private/tinfoil/attestation.get.summary
Get the Tinfoil attestation bundle used by Private Mode

# paths./api/v1/private/tinfoil/preflight.post.summary
Validate account, API key, balance, and model before encrypted dispatch

# paths./api/v1/private/tinfoil/preflight.post.description
The local Private Mode proxy calls this plaintext endpoint before sending an encrypted EHBP request, so common account errors can be returned before encryption starts. Balance and API-key spend limits are checked against a high-water reserve because NanoGPT cannot inspect encrypted prompt size before dispatch.

# paths./api/v1/private/tinfoil/v1/chat/completions.post.summary
Forward an encrypted Private Mode chat completion

# paths./api/v1/private/tinfoil/v1/chat/completions.post.description
Low-level encrypted EHBP passthrough endpoint. Most users should call the local @nanogpt/private-mode proxy at /v1/chat/completions instead of calling this route directly. NanoGPT verifies Tinfoil's returned enclave metadata matches the authorized private model before billing or returning a successful encrypted response.

# paths./api/v1/private/tinfoil/v1/chat/completions.post.responses.200.headers.Ehbp-Response-Nonce.description
Encrypted-body nonce header returned by Tinfoil.

# paths./api/v1/private/tinfoil/v1/chat/completions.post.responses.200.headers.X-Tinfoil-Usage-Metrics.description
Usage metrics returned by Tinfoil and used for NanoGPT billing.

# paths./api/v1/private/tinfoil/v1/chat/completions.post.responses.200.headers.Tinfoil-Enclave.description
Tinfoil-selected enclave metadata used by NanoGPT to verify the authorized private model before billing.

# components.parameters.ProviderHeader.description
Optional provider selection override for supported models.

# components.parameters.Ticker.description
API-key-compatible crypto deposit ticker. Fiat checkout routes such as usd are intentionally not part of this public API contract.

# components.parameters.DepositStatusTicker.description
Crypto deposit ticker with API-key-compatible status polling.

# components.parameters.PrivateModelsQuery.description
When true, return only NanoGPT Private Mode models.

# components.parameters.IncludePrivateModelsQuery.description
When true, include NanoGPT Private Mode models alongside the normal text model catalog.

# components.parameters.PrivateTinfoilModelHeader.description
Private model ID from /api/v1/private/tinfoil/models, for example private/kimi-k2-6.

# components.parameters.TinfoilEnclaveUrlHeader.description
Verified Tinfoil enclave origin selected by the local Private Mode proxy.

# components.parameters.EhbpEncapsulatedKeyHeader.description
Encrypted-body key header produced by the Tinfoil EHBP client.

# components.parameters.NanoGPTPrivateStreamHeader.description
Private Mode v1 currently requires false or omitted; streaming is not yet supported.

# components.schemas.UsageValues.description
Aggregate request, spend, refund, and token counters. totalTokens is inputTokens + outputTokens; reasoningTokens is reported separately.

# components.schemas.UsageModel.allOf[].properties.model.description
Public model label. Internal routing provider names are not exposed.

# components.schemas.UsageDayModel.allOf[].properties.model.description
Public model label. Internal routing provider names are not exposed.

# components.schemas.UsageAggregateResponse.properties.byDay.description
Returned when group_by is day or day,model.

# components.schemas.UsageAggregateResponse.properties.byModel.description
Returned when group_by is model or day,model.

# components.schemas.PrivateModeStatus.properties.enabled.description
True when the backend Private Mode surface is available.

# components.schemas.TinfoilAttestationBundle.description
Tinfoil attestation bundle proxied from the configured Tinfoil attestation service.