Model Catalog

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

The model catalog exposes the models your Orqestra deployment can route to. Operators inspect the catalog, then create model_policy assets that pin governed provider routes, limits, and review posture for release binding.

What the catalog is for

The catalog is read-only. It helps operators answer:

• which providers are enabled
• which models support tool use or streaming
• what the context window and token limits are
• what cost metadata is attached to a model

GET /v1/models/ is authenticated but not workspace-scoped. The control plane proxies the normalized catalog from runtime-gateway; runtime-gateway loads it from the model catalog cache backed by the LiteLLM client. If runtime-gateway cannot load the catalog, the control plane returns 502 rather than serving a stale or partial control-plane-only view.

Model entry fields

Execution Leaderboards

While the catalog is static metadata, the leaderboard ranks model_config_ref by observed cost, latency, and reliability from actual workspace execution evidence — the hourly execution_evidence_rollup tick. It always serves the most recently computed period for the requested grain; there is no historical period selector, since the leaderboard is a live “current standing” view rather than a time-series query.

orqestractl leaderboard get --workspace-id <workspace-id> --order-by latency_rank --tier production

grain is one of hourly, daily, weekly, or monthly; order_by is one of cost_rank, latency_rank, or reliability_rank; tier optionally filters to production or experiment rows.

The model_policy asset

A model_policy is the governed asset you bind into a release for provider-routed workload behavior.

The catalog answers “what models exist.” A model_policy answers “which approved route may this workload use, under which residency, sensitivity, fallback, and cost posture.” Runtime execution reads the release-bound model_policy; provider-routed release definitions should bind model policies, not model_config assets.

Example content

{
  "provider": "your-provider",
  "model": "your-provider/your-model",
  "provider_route": {
    "route_id": "your-provider-prod-us",
    "provider_id": "11111111-1111-4111-8111-111111111111",
    "provider": "your-provider",
    "model": "your-provider/your-model",
    "account_slot": "your-provider-prod",
    "region": "us-east-1",
    "residency": "us",
    "state": "approved",
    "sensitivity_tiers": ["public", "internal"],
    "capability_tags": ["chat", "tool_use"],
    "cost_class": "standard",
    "prompt_caching": "allowed",
    "logging": "redacted"
  },
  "fallback_routes": [],
  "embedding_route": {
    "route_id": "your-provider-embed-us",
    "provider_id": "11111111-1111-4111-8111-111111111111",
    "provider": "your-provider",
    "model": "your-provider/your-embedding-model",
    "account_slot": "your-provider-prod",
    "region": "us-east-1",
    "residency": "us",
    "state": "approved",
    "sensitivity_tiers": ["public", "internal"],
    "capability_tags": ["embedding"],
    "cost_class": "standard",
    "prompt_caching": "not_applicable",
    "logging": "redacted"
  },
  "supports_streaming": true,
  "supports_tool_use": true,
  "cost_per_input_token": 0.000001,
  "cost_per_output_token": 0.000004,
  "temperature": 0.3,
  "max_tokens": 4096
}

See Governed Providers for a concrete, worked provider/model example.

Review and approval

Create and review model policies from Assure > Policies > Model policies. Creation writes a model_policy asset and its first version through POST /v1/provider-governance/model-policies. Approval is a separate reviewer action on a specific version; the release binding UI lists active policy assets and labels approved policy versions before they are bound.

If a version is rejected or not ready, leave it unapproved and create another version. If activation later fails because provider posture changed, bind the last approved version that still satisfies the release posture or create and approve a corrected version. Do not edit an active version in place.

Route validation

Provider route validation runs when a model_policy version is created and again when a release is activated. The public contract is intentionally provider-neutral. The rules below apply to model_policy.route_policy, which carries a top-level provider/model that must match its provider_route:

Use account_slot to name the release-local logical provider account slot. Bind that slot to an environment-specific connection on each release. Do not put API keys, tokens, passwords, access keys, or client secrets in the asset payload.

Multi-model tiering

A model_policy can declare a tiers object to route different internal tasks to different models without changing the workload definition.

kind: model_policy
content:
  provider: your-provider
  model: your-provider/your-capable-model
  provider_route:
    route_id: your-provider-prod-us
    provider: your-provider
    model: your-provider/your-capable-model
    account_slot: your-provider-prod
    region: us-east-1
    residency: us
    state: approved
    sensitivity_tiers: [internal, confidential]
    capability_tags: [chat, reasoning]
    cost_class: premium
    prompt_caching: allowed
    logging: redacted
  fallback_routes: []
  tiers:
    fast: your-provider/your-fast-model
    capable: your-provider/your-capable-model
    reasoning: your-provider/your-reasoning-model

If tiers is not present, the runtime uses the top-level model for all internal tasks. Tiers only affect runtime-internal routing — the workload contract and release binding are unchanged.

Runtime behavior

When a release-bound flow contains llm_call, agent, or embedding, release validation expects a binding with role model_policy where present, otherwise the release is not ready for activation. At execution time, runtime-gateway normalizes the primary route into the active provider/model, checks the model allowlist, records the provider-route decision, and uses the configured route for provider calls.

Fallback routes are part of the governance decision and are surfaced as route IDs. They are not a place to store alternate credentials. Each fallback route must carry the same structured posture fields as the primary route.

Create a model_policy asset

curl -X POST "http://localhost:8000/v1/provider-governance/model-policies?workspace_id=$WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "prod-primary-model",
    "owner_ref": "team:platform",
    "version_label": "v1",
    "content": {
      "provider": "your-provider",
      "model": "your-provider/your-model",
      "provider_route": {
        "route_id": "your-provider-prod-us",
        "provider_id": "11111111-1111-4111-8111-111111111111",
        "provider": "your-provider",
        "model": "your-provider/your-model",
        "account_slot": "your-provider-prod",
        "region": "us-east-1",
        "residency": "us",
        "state": "approved",
        "sensitivity_tiers": ["public", "internal"],
        "capability_tags": ["chat", "tool_use"],
        "cost_class": "standard",
        "prompt_caching": "allowed",
        "logging": "redacted"
      },
      "fallback_routes": [],
      "supports_streaming": true,
      "supports_tool_use": true,
      "temperature": 0.3,
      "max_tokens": 4096
    }
  }'

Approve the reviewed version before binding it:

curl -X POST "http://localhost:8000/v1/provider-governance/model-policies/prod-primary-model/versions/{asset_version_id}/approve?workspace_id=$WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "approved",
    "review_metadata": {
      "source": "operator-review"
    }
  }'

Bind it to a release

Use the exact role name model_policy for new releases:

curl -X POST http://localhost:8000/v1/releases/{release_id}/bindings \
  -H "Content-Type: application/json" \
  -d '{
    "asset_version_id": "<model_policy_version_id>",
    "role": "model_policy"
  }'

approved -> active validation expects a model_policy binding to be present when the release’s bound flow contains provider-routed steps such as llm_call, agent, or embedding.

List catalog entries

curl http://localhost:8000/v1/models

Example response:

[
  {
    "model": "your-provider/your-model",
    "provider": "your-provider",
    "context_window_size": 400000,
    "max_output_tokens": 8192,
    "supports_streaming": true,
    "supports_tool_use": true,
    "cost_per_input_token": 0.000001,
    "cost_per_output_token": 0.000004,
    "capability_tags": ["chat", "tool_use"],
    "source": "governed",
    "identity_id": null,
    "confirmation_revision": 0
  }
]

SDK and portal usage

async with OrqestraClient(base_url=url, api_key=key) as client:
    models = await client.models.list()

In the portal, use Assure > Policies > Model policies to create, version, and approve model policies. The general asset library also lists model_policy assets, and the release binding UI exposes model_policy as the provider-routing binding.

Platform admins can also administer the governed catalog directly from the Model catalog page (Connect › Models › Model catalog, /operator/models) — Add model, Edit (full entry payload), an Enabled toggle, and Delete with confirmation. The Add/Edit dialog carries the pricing fields (input/output ¢ per 1M tokens) and a change reason; adding or changing pricing in the dialog writes the row the cost governor reads, so a newly-configured model is immediately runnable. Non-admin operators see the catalog read-only.

Cross-provider identity grouping is a separate namespace-admin action. Create an identity and confirm each catalog alias with its current revision using orqestractl model identity; ordinary model add/update and discovery do not assign or change identity. The catalog response exposes a confirmed identity_id and confirmation_revision. A never-confirmed alias returns identity_id: null and revision 0; a cleared alias remains null but retains its incremented positive revision. No name similarity is treated as evidence that two provider models are the same. See Governed Providers for the confirmation workflow.

Troubleshooting

Related guides

• Assets
• Releases
• Governed Providers