> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auriko.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Canonical model records
> Lists normalized model records with canonical IDs, capabilities, and provider availability.
`GET /v1/registry/models` returns a compact record for each canonical model. Use this endpoint when you need normalized model IDs, capabilities, authors, and provider availability for catalog views.
For provider routes, context windows, modalities, and pricing tiers, use the [Model directory](/api-reference/model-directory).
This endpoint is public and does not require authentication.
All parameters, request/response schemas, and examples are auto-generated from the [OpenAPI specification](/api-reference/overview).
## OpenAPI
````yaml GET /v1/registry/models
openapi: 3.1.0
info:
title: Auriko API
version: 1.0.0
description: >
Intelligent LLM routing API with OpenAI-compatible interface.
## Overview
Auriko provides a unified API for accessing multiple LLM providers with
intelligent
routing based on cost, latency, throughput, and availability.
## OpenAI Compatibility
The API is compatible with OpenAI's Chat Completions API. You can use any
OpenAI SDK by changing the base URL and API key.
## Auriko Extensions
Beyond OpenAI compatibility, Auriko adds:
- **Multi-model routing**: Request multiple models with `gateway.models[]`
array
- **Routing options**: Control provider selection with `routing` object
- **Provider extensions**: Pass provider-specific parameters with
`extensions` object
- **Routing metadata**: Get transparency into routing decisions via
`routing_metadata`
contact:
name: Auriko Support
url: https://auriko.ai
license:
name: Proprietary
url: https://auriko.ai/terms
servers:
- url: https://api.auriko.ai
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Chat
description: Chat completion endpoints
- name: Responses
description: OpenAI Response API endpoints
- name: Callable Models
description: Model IDs available for authenticated inference requests
- name: Model Catalog
description: Public model and provider catalog endpoints
- name: Workspaces
description: Workspace management
- name: Budgets
description: Spend control and budget management
- name: API Keys
description: API key management
- name: BYOK
description: Bring-your-own-key provider key management
- name: Billing
description: Credit balance and billing
- name: Account
description: API key introspection
- name: Messages
description: Anthropic Messages API endpoints
- name: Routing
description: Workspace routing configuration
- name: Usage
description: Usage statistics and request lookup
- name: Members
description: Workspace member and invite management
- name: Audit
description: Workspace audit event log
paths:
/v1/registry/models:
get:
tags:
- Model Catalog
summary: Canonical model records
description: |
Returns compact canonical model records with normalized model IDs,
capabilities, authors, and provider availability.
operationId: listRegistryModels
responses:
'200':
description: Canonical model records
headers:
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/ModelsListResponse'
example:
models:
- id: gpt-4o-2024-08-06
family: gpt-4o-2024-08-06
display_name: GPT-4o
capabilities:
supports_tools: true
supports_vision: true
supports_json_mode: true
supports_reasoning: false
supports_streaming: true
supports_web_search: true
supports_computer_use: false
supports_prompt_caching: false
supports_code_interpreter: false
supports_structured_output: true
input_modalities:
- image
- text
output_modalities:
- text
author: openai
providers:
- openai
has_free_provider: false
count: 127
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
'502':
$ref: '#/components/responses/GatewayUnavailable'
'503':
$ref: '#/components/responses/ServiceUnavailable'
security: []
x-codeSamples:
- lang: bash
label: curl
source: |
curl https://api.auriko.ai/v1/registry/models
components:
headers:
X-Request-ID:
description: |
Unique request identifier for debugging and support.
Include this in support requests for fast resolution.
schema:
type: string
example: req_abc123def456
X-Error-Type:
description: |
Same value as the `error.type` field in the response body, exposed as a
header for programmatic routing without body parsing.
schema:
type: string
enum:
- invalid_request_error
- rate_limit_error
- api_error
- authentication_error
- not_found_error
- permission_error
example: invalid_request_error
X-Error-Retryable:
description: |
Whether the client should retry this request.
'true' for api_error and rate_limit_error types; 'false' for all others.
schema:
type: string
enum:
- 'true'
- 'false'
example: 'false'
schemas:
ModelsListResponse:
type: object
required:
- models
- count
properties:
models:
type: array
items:
$ref: '#/components/schemas/CanonicalModelResponse'
count:
type: integer
description: Total number of models
playground_defaults:
type: array
items:
type: string
description: >-
Ordered list of model IDs recommended as playground defaults.
Frontend should select the first available.
CanonicalModelResponse:
type: object
description: A canonical model with provider availability
required:
- id
- family
- display_name
- capabilities
- input_modalities
- output_modalities
- providers
- has_free_provider
properties:
id:
type: string
description: Canonical model ID (lowercase-hyphenated)
example: gpt-4o
family:
type: string
description: Model family
example: gpt-4o
display_name:
type: string
description: Human-readable model name
example: GPT-4o
capabilities:
type: object
additionalProperties:
type: boolean
description: >
Capability flags for this model. A true value means at least one
routable provider supports this capability. For per-provider truth,
use /v1/directory/models.
example:
supports_tools: true
supports_reasoning: false
supports_streaming: true
input_modalities:
type: array
items:
type: string
description: |
Union of input modalities across all routable providers.
example:
- text
- image
output_modalities:
type: array
items:
type: string
description: |
Union of output modalities across all routable providers.
example:
- text
author:
type:
- string
- 'null'
description: Model author/creator
example: openai
providers:
type: array
items:
type: string
description: Provider IDs offering this model
example:
- openai
- fireworks_ai
- together_ai
has_free_provider:
type: boolean
description: Whether at least one provider offers this model for free
ErrorResponse:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorObject'
ErrorObject:
type: object
description: OpenAI-compatible error format
required:
- message
- type
- param
- code
properties:
message:
type: string
description: Human-readable error message
type:
type: string
description: Error category per guide §4.
enum:
- invalid_request_error
- authentication_error
- permission_error
- not_found_error
- rate_limit_error
- api_error
param:
type:
- string
- 'null'
description: Parameter that caused the error (null if not applicable)
code:
type: string
description: Canonical code per guide §5 and docs/reference/error_codes.json.
enum:
- invalid_api_key
- expired_api_key
- insufficient_permissions
- feature_disabled
- mfa_required
- invalid_recovery_code
- mfa_verification_failed
- invalid_request
- missing_required_parameter
- invalid_parameter_value
- payload_too_large
- context_length_exceeded
- content_filtered
- idempotency_conflict
- idempotency_replay_unavailable
- field_immutable
- operation_not_allowed
- unknown_field
- state_precondition_failed
- duplicate_resource
- method_not_allowed
- payment_declined
- payment_method_invalid
- tools_not_supported
- json_mode_not_supported
- structured_output_not_supported
- tools_with_structured_output_not_supported
- vision_not_supported
- reasoning_not_supported
- thinking_disable_not_supported
- streaming_not_supported
- non_streaming_not_supported
- batch_only
- tier_opt_in_required
- tool_choice_required_not_supported
- cost_constraint_exceeded
- latency_constraint_exceeded
- throughput_constraint_not_met
- provider_not_in_allowlist
- provider_blocked
- required_params_not_supported
- byok_keys_required
- platform_keys_unavailable
- unsupported_modalities
- no_compatible_endpoint
- no_responses_endpoint
- input_requires_responses_endpoint
- response_api_only
- hosted_tool_not_supported
- model_not_found
- resource_not_found
- rate_limit_exceeded
- budget_exhausted
- insufficient_quota
- no_provider_available
- upstream_error
- upstream_timeout
- client_disconnected
- stream_duration_exceeded
- model_unavailable
- internal_error
- service_unavailable
doc_url:
type: string
description: Link to the canonical documentation page for this error code.
provider:
type:
- string
- 'null'
description: >-
Upstream provider that generated the error (e.g.,
"google_ai_studio", "openai"). Null for errors not attributable to
an upstream provider (local validation, auth, internal config).
suggestion:
type: string
description: >-
Actionable fix hint for routing, capability, or model-not-found
errors. Absent for other error types.
responses:
RateLimited:
description: |
Rate limit exceeded. Two sub-causes share this status:
- `rate_limit_exceeded`: throughput-based rate limit.
- `budget_exhausted`: account or project budget reached (self-service;
not auto-retried by SDKs — requires adding credits or raising the limit).
headers:
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
X-Error-Type:
$ref: '#/components/headers/X-Error-Type'
X-Error-Retryable:
$ref: '#/components/headers/X-Error-Retryable'
Retry-After:
description: >-
Seconds until rate limit resets. Standard HTTP header for retry
backoff.
schema:
type: integer
example: 60
X-Rate-Limit-Source:
description: >-
Identifies whether the rate limit originated from an upstream
provider or from Auriko's routing layer.
schema:
type: string
enum:
- provider
- routing
required: false
example: provider
X-RateLimit-Limit-Requests:
description: Request limit per window (present on throughput-based rate limits)
schema:
type: integer
required: false
example: 60
X-RateLimit-Remaining-Requests:
description: >-
Remaining requests in window (present on throughput-based rate
limits)
schema:
type: integer
required: false
example: 0
X-RateLimit-Reset-Requests:
description: >-
When limit resets (ISO 8601 format; present on throughput-based rate
limits)
schema:
type: string
format: date-time
required: false
example: '2026-06-15T12:01:00.000Z'
X-Budget-Exceeded:
description: Present on budget-exhaustion 429s.
schema:
type: string
enum:
- 'true'
- 'false'
required: false
example: 'true'
X-Budget-Exceeded-Period:
description: Period of the exceeded budget (present on budget-exhaustion 429s).
schema:
type: string
enum:
- daily
- weekly
- monthly
required: false
example: monthly
X-Budget-Exceeded-Scope:
description: Scope of the exceeded budget (present on budget-exhaustion 429s).
schema:
type: string
enum:
- workspace
- api_key
- byok_provider
required: false
example: workspace
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
rate_limit_exceeded:
summary: Throughput-based rate limit
value:
error:
message: Rate limit exceeded. Retry after 60 seconds.
type: rate_limit_error
param: null
code: rate_limit_exceeded
budget_exhausted:
summary: Account budget exhausted
value:
error:
message: Account budget exhausted. Add credits to continue.
type: rate_limit_error
param: null
code: budget_exhausted
InternalError:
description: Internal server error
headers:
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
X-Error-Type:
$ref: '#/components/headers/X-Error-Type'
X-Error-Retryable:
$ref: '#/components/headers/X-Error-Retryable'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
message: >-
An unexpected error occurred. Contact support with the request
ID.
type: api_error
param: null
code: internal_error
GatewayUnavailable:
description: |
API gateway is temporarily unavailable.
headers:
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
X-Error-Type:
$ref: '#/components/headers/X-Error-Type'
X-Error-Retryable:
$ref: '#/components/headers/X-Error-Retryable'
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
message: Gateway is temporarily unavailable. Retry in a few seconds.
type: api_error
param: null
code: upstream_error
ServiceUnavailable:
description: >
Service unavailable — transient issue. Possible causes:
- All providers for the model are rate-limited or temporarily
unavailable (`no_provider_available`)
- Transient infrastructure issue (`service_unavailable`)
Note: If the model doesn't support a requested capability (e.g.,
reasoning),
the response is 400 with a specific code (e.g.,
`reasoning_not_supported`), not 503.
If routing constraints excluded all providers, the response is 400 with
a
specific constraint code (e.g., `cost_constraint_exceeded`).
headers:
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
X-Error-Type:
$ref: '#/components/headers/X-Error-Type'
X-Error-Retryable:
$ref: '#/components/headers/X-Error-Retryable'
Retry-After:
description: Seconds to wait before retrying (present on transient failures)
schema:
type: integer
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
no_providers:
summary: No providers available for the model
value:
error:
message: >-
No provider available for model 'gpt-4o'. Try a different
model.
type: api_error
param: null
code: no_provider_available
service_unavailable:
summary: Transient infrastructure issue
value:
error:
message: Service is temporarily unavailable. Retry in a few seconds.
type: api_error
param: null
code: service_unavailable
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: |
API key authentication.
Keys start with `ak_` prefix.
Example: `Authorization: Bearer ak_live_xxxxxxxxxxxx`
````