Provision models via API

The Admin Console is the usual surface for connecting providers and enabling models, but automation needs the same outcome without clicking through forms. The API is that path: upsert a provider, store its credential, upsert a model with pricing and capabilities, grant the project access (the model always, and the provider too where the project restricts providers), then verify with a read-back and an inference call. For the dashboard equivalent, see Provision models and providers.

Two API surfaces

This guide uses the Management API to provision configuration: the Catalog service for providers and models, and the AdminService for project provider grants. Live prompts use the Gateway APIs on the data plane (/v1/chat/completions, /v1/models, and related paths). The final verification step switches to that gateway surface; the provisioning steps do not.

Persona: Platform operator or platform engineer automating catalog provisioning against the management API.

Estimated time: 15 to 25 minutes once an admin API key, a provider credential, and the customer and project identifiers for assignment are in hand.

When this guide applies

Situation	Why this guide helps
A script or pipeline must provision providers and models without the Admin Console	The Catalog write RPCs are the programmatic surface for the same configuration
An internal source of truth syncs the model catalog into Agent Router	Upsert and assign map cleanly onto a repeatable reconciliation loop
Pricing and capability fields must be set at create time, not only toggled later in the UI	UpsertModel accepts pricing and capabilities in one request
The OpenAPI or SDK reference is available but there is no ordered how-to	This guide sequences the calls and shows how to verify the result

For the Admin Console equivalent, use Provision models and providers instead. For managing the broader configuration baseline as code, see Manage configuration as code.

Outcomes

By the end of this guide:

A provider record exists with a stored credential.
A model record exists under that provider, with pricing and capabilities set.
Where the project restricts providers, the provider is on the project's provider list.
The model is allow-listed for the project, so the project gateway can route to it.
The configuration is confirmed with Catalog read-backs and a gateway inference call.

Prerequisites

An API credential with administrative scope for Catalog writes, issued from the Admin Console or an equivalent control-plane path. Bearer auth on every request below.
The management API base URL for the deployment (the host that serves /v1/catalog/...). Replace https://management.example.com in the examples with that host.
Upstream provider credentials (API key, bearer token, or whatever the provider expects) and the provider's API base URL.
The customer and project identifiers used when assigning a model to a project.
For the final inference check: a client API key minted for that project (CreateClientWithKey), not a CreateApiKey user token. See Which API key for which surface.

The tare api catalog CLI exposes the same operations as flags. This guide uses HTTP so the request bodies are explicit; either surface is valid.

Step 1: upsert the provider

Create or fully replace the provider record with UpsertProvider. The id is a canonical slug: lowercase alphanumeric only ([a-z0-9]+), no hyphens.

curl -sS -X POST "https://management.example.com/v1/catalog/providers" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "acmeopenai",
    "displayName": "Acme OpenAI",
    "baseUrl": "https://api.openai.com/v1",
    "supportedAuthSchemes": ["bearer"]
  }'

Required fields are id, displayName, and baseUrl. supportedAuthSchemes is optional (for example ["bearer"]).

Step 2: set the provider credential

Store or rotate the upstream credential with SetProviderCredential. The plaintext is never returned; the provider's credential_suffix reflects the last four characters after a successful write.

curl -sS -X POST "https://management.example.com/v1/catalog/providers/acmeopenai/credential" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": "'"${PROVIDER_API_KEY}"'"
  }'

Credential rotation uses the same call with the new value. In-flight requests that already held the old credential complete with it; subsequent requests use the new one.

Step 3: upsert the model (pricing and capabilities)

Create or fully replace the model with UpsertModel. Pricing fields are decimal USD strings. Capabilities declare what the model supports (for example chat or embeddings); that is the API counterpart of choosing a model mode in the UI.

curl -sS -X POST "https://management.example.com/v1/catalog/models" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "acmeopenai",
    "name": "gpt-4o",
    "upstreamModel": "gpt-4o",
    "inputPerMillion": "2.50",
    "outputPerMillion": "10.00",
    "cacheReadPerMillion": "1.25",
    "maxCostPerRequest": "",
    "maxContextTokens": 128000,
    "capabilities": ["chat"]
  }'

Required fields are providerId and name. upstreamModel defaults to name when empty. Capture the model id returned in the response; it is required for the model assignment in Step 5.

For an embedding model, set capabilities to include embeddings and verify with the embeddings endpoint instead of chat completions.

Step 4: check the project's provider list

Providers restrict, models allow-list

The two project grants are not symmetrical. Models are allow-listed: a model the project has not been granted is refused at request time (Step 5). Providers are a restriction: a project with an empty provider list may use any provider the organization catalog has enabled, and a non-empty list confines the project to those providers only. The Admin Console workflow for both grants is Add providers and models to a project.

Project provider grants live on the AdminService, under /admin/v1/..., not on the Catalog paths used so far. List the project's providers with ListProjectProviders:

curl -sS \
  "https://management.example.com/admin/v1/customers/${CUSTOMER_ID}/projects/${PROJECT_ID}/providers" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}"

An empty list is the absence of a restriction, and this step is then complete: the project may use any provider the organization catalog has enabled, and it keeps following the catalog as the catalog changes. Adding a provider to an empty list changes the rule from "any enabled provider" to "these providers only", so a list is only introduced when the intent is to confine the project.

Where the list is already non-empty, the project is confined to the providers it names, and a model from any other provider is not routable however it is assigned. Add the provider from Step 1 with AddProjectProvider:

curl -sS -X POST \
  "https://management.example.com/admin/v1/customers/${CUSTOMER_ID}/projects/${PROJECT_ID}/providers" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"providerName": "acmeopenai"}'

providerName is the provider id slug from Step 1. RemoveProjectProvider (DELETE .../providers/{provider_name}) lifts a grant again, and removing the last entry returns the project to the unrestricted rule.

Skipping this step on a restricted project fails silently: the model assignment in Step 5 still returns 200, and inference then fails with 404 No matching route found.

Step 5: assign the model to the project

Projects are the isolation boundary

A project owns the models, API keys, and gateway URL an application calls. Catalog enablement makes a model available to grant, not callable: the project gateway refuses a model that has not been assigned. A default project is created during onboarding and is enough for a first verification; creating additional projects and granting models in the Admin Console is covered in Create a project and grant models. For the full concept, see Key concepts → Projects.

Allow-list the model for the project's gateway with AssignModelToProject. The call is idempotent: re-assigning the same model is a no-op.

curl -sS -X POST \
  "https://management.example.com/v1/customers/${CUSTOMER_ID}/projects/${PROJECT_ID}/models" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "'"${MODEL_ID}"'"
  }'

modelId is the catalog model id from the UpsertModel response. Without this assignment, the project gateway refuses the model even though the catalog record exists. In the Admin Console, enablement and project scoping are the UI counterparts of the upsert-plus-assign sequence.

Step 6: verify

Confirm configuration first, then traffic.

Read-back

Fetch the provider: GET /v1/catalog/providers/{id} (GetProvider). Confirm baseUrl and that credential_suffix is set.
Fetch the model: GET /v1/catalog/models/{id} (GetModel). Confirm pricing, maxContextTokens, and capabilities.
List project models: GET /v1/customers/{customer_id}/projects/{project_id}/models (ListProjectModels). Confirm the new model appears.
On a project with a non-empty provider list: GET /admin/v1/customers/{customer_id}/projects/{project_id}/providers (ListProjectProviders). Confirm the model's provider is listed, per Step 4.

curl -sS "https://management.example.com/v1/catalog/providers/acmeopenai" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}"

curl -sS "https://management.example.com/v1/catalog/models/${MODEL_ID}" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}"

curl -sS \
  "https://management.example.com/v1/customers/${CUSTOMER_ID}/projects/${PROJECT_ID}/models" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}"

Inference

The steps above used the management (Catalog) API. End-to-end verification switches to the gateway inference surface: a different host and a project client key (CreateClientWithKey), not the admin credential used for Catalog writes. Gateway paths, formats, and auth are documented in Gateway APIs.

Use the gateway base URL for the deployment (for Fully Managed, often https://api.router.tetrate.ai/v1). First list the models routable for that client key with GET /v1/models. Each returned id can be passed as model on an inference call. Confirm that the newly provisioned and assigned model appears in the list.

curl -sS "https://api.router.tetrate.ai/v1/models" \
  -H "Authorization: Bearer ${CLIENT_API_KEY}"

Then send a Chat Completions request (POST /v1/chat/completions) using one of those id values:

curl -sS -X POST "https://api.router.tetrate.ai/v1/chat/completions" \
  -H "Authorization: Bearer ${CLIENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "ping"}]
  }'

A successful response confirms credentials, catalog configuration, and project grants end to end. If the model is missing from GET /v1/models, or the completion call returns 404 No matching route found, the usual causes are a missed upsert, a missed model assignment (Step 5), or, on a project with a non-empty provider list, the model's provider missing from that list (Step 4). An upstream authentication error on the completion call usually points at the provider credential. For more gateway call shapes, see Make an API call.

Where to go next

Use the dashboard for the same catalog and grant work, or stay on the API and IaC path below. Catalog method detail is in CatalogService.

Provision models and providers

The Admin Console workflow for providers and model enablement.

Add providers and models to a project

The Admin Console workflow for both project grants, with the restriction and allow-list semantics.

Create a project and grant models

Grant catalog models to a project, then provision its gateway and keys.

Manage configuration as code

How the admin API fits UI and IaC ownership of the catalog.

When this guide applies​

Outcomes​

Prerequisites​

Step 1: upsert the provider​

Step 2: set the provider credential​

Step 3: upsert the model (pricing and capabilities)​

Step 4: check the project's provider list​

Step 5: assign the model to the project​

Step 6: verify​

Read-back​

Inference​