Request and API conventions

Authentication, model identifiers, request options, metadata, and error conventions.

Authentication

The Nirmos SDK sends the configured key in x-api-key. OpenAI-compatible clients send the same key through their normal bearer authorization flow; the gateway accepts both authentication forms.

Keep credentials in trusted server environments.

API origin

Client	Base URL
Nirmos SDK	`https://api.nirmos.com`
OpenAI SDK	`https://api.nirmos.com/v1`

The Nirmos SDK appends resource paths such as /v1/chat/completions itself.

Model identifiers

Use provider-qualified identifiers when calling a physical model:

openai/gpt-5.4-mini
google/gemini-3.5-flash
anthropic/claude-sonnet-4-6

An unqualified identifier is accepted only when it resolves unambiguously. Prefer qualified names in application configuration.

A model string beginning with nirmos/ is reserved for an active route slug:

nirmos/production-chat

Nirmos request options

Every Nirmos SDK request accepts an optional final RequestOptions argument:

await nirmos.gateway.chat.create(params, {
  signal: request.signal,
  timeoutMs: 10_000,
  maxRetries: 0,
  headers: { "x-request-id": crypto.randomUUID() },
});

idempotencyKey enables retry eligibility for a mutation when the target API supports that key. It does not make an operation idempotent by itself.

Response metadata

Normalized Nirmos SDK responses can include:

Field	Meaning
`requestId`	Request identifier for application logs and support
`traceId`	Identifier for the gateway execution trace
`provider`	Provider selected by direct resolution or routing
`model`	Resolved model when returned by the gateway
`latencyMs`	Gateway response time when available
`cache`	Cache status, layer, and remaining TTL when available

Fields are optional because metadata can arrive in either response headers or the response body and not every endpoint emits every field.

The Nirmos SDK uses camelCase (maxOutputTokens, fallbackModels) and maps to the gateway's wire format (max_tokens, fallback_models). OpenAI-compatible clients use the standard OpenAI field names and response shapes.

Errors

All SDK errors extend NirmosError. HTTP failures extend APIError and preserve status, error code, retryability, request ID, and trace ID when present. See Errors and reliability.