How model routing works

A completed live run on a catalog model records three facts about the model that answered your run (one task you send; the API calls it an execution):

Model: the model you asked for.
Provider: the company, cloud, or gateway that served it.
Connection: the saved link to the provider account used for the request. The recorded billing owner shows who bills the model usage.

The same model can be served by more than one provider. The provider may report a more specific model name than the one you asked for. Millwork keeps both names. Every live run also has a platform fee, charged when Millwork accepts the run; model usage is separate. Read Model access and billing. Read all three facts from a completed run:

curl --fail-with-body \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  "$MILLWORK_API_URL/executions/$EXECUTION_ID/result" |
jq '{
  requested: .model_provenance.requested.upstream_ref,
  provider_reported: .model_provenance.resolved.upstream_ref,
  provider: .model_provenance.source.source_id,
  connection: .model_provenance.source.connection_id,
  billed_by: .model_provenance.source.commercial_owner
}'

billed_by is customer when your provider account was used and millwork when Millwork provided the model.

Requested and provider-reported models

You ask for a model by its catalog name. A cloud or gateway may answer with a dated version of it. Millwork keeps both names in the result and the receipt. The requested value is the model Millwork asked for. The provider-reported value is the model the provider or gateway says it ran; the API field is resolved. A dated or more specific name does not by itself mean Millwork fell back to another model. This diagram shows how one requested name becomes two names in your records. When your administrator saved a model directly with a provider model ID, rather than from your catalog, a run on it records the saved model and its usage but no provider-reported model: the run’s model_provenance is null. The receipt identifies the saved model and records its usage. Ask the administrator who saved it which provider account pays for that usage; the receipt does not identify that account. OpenRouter is a gateway. It forwards your request to one of several providers, so the provider and model it reports can be more specific than the route you asked for.

Which models can your organization run now

Use GET /v1/model-catalog for the models your organization can save. Use GET /v1/model-source-profiles for the providers your organization can connect. A provider named in these docs is not an availability promise. The current list of interfaces and their status is in What you can use today.

What models can do today

Today a run takes text in and returns text out. Do not assume support for streaming, tools, images, audio, embeddings, fine-tuning, or provider-specific request options unless the catalog and API reference add them. Do not choose a model from a static list. Your organization’s catalog is the current answer.

From provider route to customer use

A model provider is the organization supplying an inference API. Its Provider application is separate from a customer connecting a provider account to access and pay for that API. A provider model route identifies the exact model release and endpoint submitted for review. A saved model is the option a customer adds from its catalog; the API calls it an arm. The handoff has several decisions. Finishing one does not finish the next.

Decision	What it establishes	Who acts next
Organization approved	The provider organization passed its review.	Provider submits exact model routes.
Route tested and approved	Millwork reviewed the specific model, endpoint, data rules, price, and evidence.	Millwork prepares and activates that approved route.
Route ready to serve	The approved route is prepared to answer requests. It may still be unavailable to customers.	Millwork enables access for the intended customer organizations.
Route available to an organization	Access is enabled for that organization and the model meets its catalog requirements, including current connection tests when its own provider account is used.	Customer chooses and saves the catalog model.
Live run accepted	Millwork accepted the customer’s task and limits; the platform fee is charged.	Follow the run to a final status, then read its records.

New providers may be limited to specifically enabled organizations and model routes. Appearing in the catalog and being able to run a task have separate access checks. A provider’s key or route is not automatically shared with every customer. Read your organization’s current catalog rather than inferring access from a provider’s approval or public model list.

Follow one available OpenRouter model

This example follows the customer side of an existing gateway integration. It does not establish that a new Provider application has reached customer use. Use an OpenRouter route actually returned to your organization; if it is absent, resolve access before continuing. If you need to connect OpenRouter first, CLI setup is a complete alternative: follow it through its saved model, approved paid run, answer and receipt. That finishes your first-run journey; do not return to the API steps below to save and run the same task again.

Use an existing tested connection. Read your organization’s saved connections with GET /v1/source-connections, or use millwork provider list --json. These reads do not save a model or start a run. Choose the intended OpenRouter account: its connection should be active, its test_state should be passed, and tested_binding_revision should match binding_revision. Keep its connection_id as CONNECTION_ID in the terminal. Your provider bills model usage. A model Millwork provides is a separate access choice and does not require you to connect your own provider account.
Find the exact route. In the customer dashboard, open Arms > Model catalog. Compare the model release, provider, access, region and data rules. Through the API, GET /v1/model-catalog?source_id=openrouter&access_lane=byok reads models reached through your own OpenRouter account. The API value byok means your provider account is used. Keep the intended row’s model_deployment_id and connection ID. Do not save the model yet.
Continue to the run guide before saving. Open Run a model and complete Before you begin. Keep the same CONNECTION_ID. At Choose a model from your catalog, match .deployment.model_deployment_id and .connection.connection_id in catalog.json to the values you retained. Set MODEL_INDEX to that row’s number; use 0 only if row 0 is the match. If the row is missing, resolve access before continuing.
Save once and submit one approved task. Continue from Save the model to your organization in that guide. It saves the returned template and pins the task with routing.required_arm_id, then shows status, result and receipt requests. Do not substitute a model name from the provider’s general list. Review current charges and any required price approval before submission. An assistant needs your approval for a paid run.
Read both records. After completed, fetch GET /v1/executions/{id}/result for the answer and GET /v1/receipts/{id} for the selected model, route, usage and evaluation evidence. Compare the selected arm with the one you chose. Provider-reported model details may be absent; do not fill them in from the requested name.

The provider continues to run its API on its own infrastructure. Loading model files onto Millwork-managed compute would be a different hosting path.

Use the same route from your application or agent

These are alternative interfaces for the same catalog and save steps. If you already saved the model through one interface, keep its arm_id for the run; do not register it again through another.

Entry point	Discovery and saving	Run and records
Dashboard	Arms > Model catalog, then Add arm for the intended row.	In Run a model, complete Before you begin and set `ARM_ID` to the already saved `arm_id`. Continue at Submit the run, skipping model selection and saving.
REST API	`GET /v1/model-catalog`, then the returned template with `POST /v1/arms`.	`POST /v1/executions`, status, result, and receipt endpoints in Run a model.
TypeScript SDK	`modelCatalog.get()` and `arms.create()` with the returned template.	`executions.create()`, `.get()`, `.result()`, and `receipts.get()`.
Execution MCP	`solver_list_model_catalog`, then `solver_enable_model_arm` using the chosen row.	`solver_submit`, `solver_status`, `solver_result`, and `solver_receipt`; the host confirms writes.

Use the linked interface page for its current version and setup. The documentation MCP helps an agent read these instructions; it does not connect a provider or start a run.

Continue after an event

Your app can submit a task manually or in response to an event or schedule it already manages. That does not create a native Millwork scheduler. Existing customer webhooks include execution.completed, execution.failed, and execution.needs_review. A webhook can notify your application to inspect the current status and records before its next step. The receipt is evidence of the run, not an executor for that next step.

Check the output

If you do not name an output check, the basic check confirms only that output is present. To judge your product’s requirements, connect a customer output check and read its recorded verdict. A failed check or missing verdict must not be treated as verified work.

When the handoff stops

Problem	Next responsible action
Provider or model absent from the catalog	Customer checks connection, entitlement and filters; support checks route and customer-access enablement. Do not register an unrelated route to bypass the absence.
Provider connection revoked or its test no longer current	Customer restores the intended connection using provider connection help.
Route suspended, withdrawn, or evidence no longer current	Provider follows its workspace reason; Millwork handles an operator suspension or review decision.
A pinned saved model cannot serve the task	Inspect the refusal or run events. This exact-model path does not silently choose another model.
Output check rejects or is unavailable	Customer reviews the reasons or restores the check before authorizing dependent work.

If you are supplying the API, start with Provider onboarding. If you are ready to use a catalog model, continue with Run a model.

Start here

Understand Solver

Principles and scope

How model routing works

Requested and provider-reported models

Which models can your organization run now

What models can do today

From provider route to customer use

Follow one available OpenRouter model

Use the same route from your application or agent

Continue after an event

Check the output

When the handoff stops

​Requested and provider-reported models

​Which models can your organization run now

​What models can do today

​From provider route to customer use

​Follow one available OpenRouter model

​Use the same route from your application or agent

​Continue after an event

​Check the output

​When the handoff stops

Requested and provider-reported models

Which models can your organization run now

What models can do today

From provider route to customer use

Follow one available OpenRouter model

Use the same route from your application or agent

Continue after an event

Check the output

When the handoff stops