Model discovery and discovery permission

Since v0.9.0, applications can discover public aliases both allowed by their Gateway Key’s Project and served by the current route table. This reads Halro configuration locally: no upstream call, no Ledger event, and no disclosure of Provider accounts or model identifiers.

experimental

These endpoints have Gateway contract tests but are not yet covered by the official SDK black-box matrix. The SDK example illustrates usage; it does not claim end-to-end verification for that SDK version.

Permissions and requests

The Key needs both inference and discovery scopes. Existing Keys, Keys with omitted scopes, and Keys minted by halro key create default to inference only. Missing discovery permission returns 403 gateway_key_scope_denied. Ask an operator to choose the required scopes through the Console Key dialog or Admin API.

Inject $HALRO_GATEWAY_KEY securely. Replace the example hostname and chat with your Gateway and public alias.

curl -fsS https://halro.example.com/v1/models \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY"
curl -fsS https://halro.example.com/v1/models/chat \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY"

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://halro.example.com/v1",
    api_key=os.environ["HALRO_GATEWAY_KEY"],
    max_retries=0,
)
for model in client.models.list().data:
    print(model.id)

Response fields and boundaries

{
  "object": "list",
  "data": [{"id": "chat", "object": "model", "created": 0, "owned_by": "halro"}]
}

Response fields and boundaries

Field or behavior	Meaning
id	Public alias; an operator may replace its backing Deployment without changing it
created	Always 0; Halro does not invent an alias creation time
owned_by	Always halro; upstream identity is not disclosed
List order	Sorted by alias without duplicates; an empty list is valid
Individual retrieval	Unauthorized and nonexistent aliases both return 404 model_not_found
Query parameters	Currently unmodeled and ignored; there is no pagination protocol

A listing does not guarantee that any request will succeed. An alias may support another operation and return 400 unsupported_feature on use. Aliases whose targets are all unhealthy or suspended may still be listed and return 503 on use. Aliases excluded from the route table itself, for example after capability drift or removal of a Provider with an unreachable egress proxy, are omitted. Discovery carries no capabilities; it cannot replace capability verification.

Rate limits and failures

Discovery has fixed ceilings of 600 requests/minute per Key and 5,000/minute per Project. Exceeding them returns 429 rate_limit_exceeded with Retry-After. This is separate from Project RPM/TPM for billed inference and cannot be disabled through configuration. The fixed ceiling also covers Files, Batches, Async, and deferred Responses resource endpoints; operations reaching upstream still pass Project admission.

503 configuration_stale means persisted configuration has not safely activated; discovery is refused too. For 403, fix scopes; for 404, inspect alias authorization and routes; for 429, back off for the indicated interval. These failures do not all mean an unavailable Provider. See authentication and errors.