Model references and resolution

Most LLM gateways take a bare model name (gpt-4o) and route it. Ringside does not. The model field you send is a typed reference whose prefix declares its resolution strategy, and Ringside rejects a bare name with 400 invalid_model_ref rather than guess what you meant. The point of the prefix is to make late binding explicit: a request can pin one exact build, or it can hand the choice to Ringside and let the resolved model change over time (a family rolling to a newer version, an alias you repoint, a per-request decision) without you touching the call site.

Resolution runs server-side on every metered call (chat, runs, assistants, conversations). A dyn: ref is expanded first, then the result flows through the same router that handles fc:, match: and slot:. Whatever the input ref, resolution always lands on a concrete fc:<provider>/<model> id before a provider is called, and that concrete id (not your selector) is what gets metered, cached and capability-checked. The headers documented below report what the string actually resolved to so you are never guessing.

The four ref kinds

fc: (pinned)

A fc: ref is the literal model. The string after fc: is passed through to the upstream catalog unchanged, so fc:openai/gpt-4o-mini is OpenAI gpt-4o-mini and nothing else. Pin with fc: when you have qualified a specific build and want byte-for-byte stable behaviour across a deploy, an eval suite or a regression baseline. An empty ref (fc: with nothing after it) is 400 invalid_model_ref.

{ "model": "fc:openai/gpt-4o-mini", "messages": [ ... ] }

match: (newest in a family)

A match: ref names a provider and a family and resolves to the newest catalog model in that family, with an optional version floor or pin. The grammar is match:<provider>/<family> for the bare newest, match:<provider>/<family>>=N for the newest at major version N or above (this is the one that rolls forward as new majors ship) and match:<provider>/<family>=N to stay within the v{N}.x line. The resolver sorts family members newest-first by major then minor and returns the top candidate that satisfies your constraint.

Family selection is the right default when you want the best current model in a line and you trust Ringside to carry you onto its successor. match:anthropic/sonnet>=4 keeps serving the newest Sonnet at v4 or later: when Sonnet 4.5 lands it picks that, when a v5 ships it rolls to v5, and you change nothing. The bare match:anthropic/sonnet never errors because it always rolls forward to whatever exists. A constraint can age out: if no catalog model satisfies your floor or pin the call returns 400 model_family_eol and the message names the newest model that does exist, so you can update the ref.

slot: (an alias you repoint)

A slot: ref is a named pointer you define on the platform side that resolves to a fc: ref. The alias is indirection you control out of band: change what slot:default-chat maps to in platform settings and every caller using that slot picks up the new target on the next request, with zero code changes and no redeploy. Slots can chain (a slot pointing at another slot) and the resolver walks them to a maximum depth of 8 before bailing with slot_cycle to stop an alias loop. An unknown alias is unknown_slot; an empty alias (slot: with nothing after it) is invalid_model_ref.

dyn: (a profile picked at request time)

A dyn: ref names a dynamic profile you have saved on your developer account. The other three kinds map to one fixed target. A dyn: ref does not. The profile holds a pool of concrete refs arranged as a ladder (a floor, a ceiling and a starting rung) and Ringside picks a rung per request from the request shape. The router reads the live turn (token count, whether tools or vision or a json_schema are in play and a difficulty estimate from the prompt) and chooses a model from the pool. Profiles in dispatcher mode also let a cheap model classify the demand first. That classify call is timeout-bounded and never throws, so a slow or failed classification falls back to the heuristic instead of erroring the request.

Because the choice is per request, two identical-looking calls to the same dyn: ref can resolve to different models. Read the X-Ringside-Dynamic-Profile and X-Ringside-Dynamic-Reason headers to see which profile ran and the one-line reason it picked the rung it did. A dyn: ref whose profile does not exist on your account, or whose stored profile is misconfigured (empty pool, floor above ceiling, a starting rung outside the ladder), is rejected as 400 invalid_model_ref with a message describing the fault.

Why bare names are rejected

A bare name like gpt-4o carries no resolution strategy. It could mean a pinned build, the newest in a family or an alias you control, and Ringside will not guess between them, so it returns 400 invalid_model_ref instead. The message names the three routable prefixes (the ref must start with fc:, slot: or match:). A dyn: ref is valid too but is expanded one layer earlier, so it never reaches this router branch. This is the most common error when migrating an existing OpenAI integration. Point the SDK at the Ringside base URL and the only required code change is prefixing your model strings with fc: (or one of the other kinds).

One more rejected shape worth calling out: user: refs (bring-your-own-key models from the Knockout surface) are not accepted by the Ringside API and return 400 byok_not_supported. Use fc: or slot: instead.

// 400 invalid_request_error / invalid_model_ref
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_model_ref",
    "message": "Model ref must start with 'fc:', 'slot:', or 'match:'. Got: gpt-4o",
    "param": "model"
  }
}

Data residency: the @region suffix

You pin a call to a cloud and region by appending an @<region> suffix to the model id. The suffix attaches to fc: refs only. It is opt-in and never changes traffic that omits it (refs without a suffix route normally through the platform path with no residency guarantee). The canonical model id stays the billing model, so residency changes where the call runs, not what it costs.

The suffix is split off the last @ in the id (canonical catalog ids never contain @, so a present @ is always a region tag). An unknown suffix like @apac returns 400 invalid_model_ref and the message lists the supported suffixes. A mismatch returns 400 unsupported_provider: an OpenAI suffix (@eu / @us) on a non-OpenAI base is rejected and the message points you at @eu-bedrock/@eu-vertex for Claude, and a Claude bedrock/vertex suffix on a model that is not region-routable is rejected with the list of models that are.

curl https://api.fightclub.pro/v1/chat/completions \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fc:anthropic/claude-opus-4.6@eu-bedrock",
    "messages": [{"role":"user","content":"Summarise this contract clause."}]
  }'

Resolution response headers

Every chat response carries headers that report how your ref resolved. You do not have to parse the model out of the body. Read these to confirm the concrete model, to detect when a newer model exists behind your match: constraint and to see why a dyn: profile chose what it chose.

Worked example: a match: ref rolling forward

Send a family ref with a version floor and let Ringside pick the newest qualifying Sonnet. The body stays the same call you would make with any model.

1. 1
   Send the match: ref

   Ask for the newest Sonnet at major 4 or above, attributed to a customer.

   curl

   Copy

   curl -i https://api.fightclub.pro/v1/chat/completions \
     -H "Authorization: Bearer $FC_API_KEY" \
     -H "FC-Customer: cus_42" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "match:anthropic/sonnet>=4",
       "messages": [{"role":"user","content":"Draft a release note."}]
     }'

2. 2
   Read the resolution headers

   The response tells you the concrete model that ran. Here the catalog's newest Sonnet at the time was 4.6.

   http

   Copy

   HTTP/1.1 200 OK
   X-Request-Id: req_8sKQ2v...
   X-Ringside-Model-Resolved: anthropic/claude-sonnet-4-6
   X-Ringside-Wallet-Deducted: 0.000412
   X-RateLimit-Remaining: 59

3. 3
   Ship a newer model, change nothing

   When Sonnet 4.7 (or a v5) enters the catalog, the same ref resolves to it on the next request and X-Ringside-Model-Resolved updates accordingly. Your call site is untouched.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.fightclub.pro/v1",
    api_key=os.environ["FC_API_KEY"],
)

resp = client.chat.completions.create(
    model="match:anthropic/sonnet>=4",
    messages=[{"role": "user", "content": "Draft a release note."}],
    extra_headers={"FC-Customer": "cus_42"},
)

# the resolved concrete model is on the raw response headers
resolved = resp.response.headers.get("x-ringside-model-resolved")
newer = resp.response.headers.get("x-ringside-model-newer-available")
print(resolved, newer)

Worked example: a dyn: profile

A dyn: ref hands the model choice to a profile. A short, simple prompt may land on a budget rung; a long prompt with tools and a strict json_schema pushes the router up the ladder. The reason header tells you which signal moved it.

POST /v1/chat/completions
{ "model": "dyn:cost-aware", "messages": [ ...short prompt... ] }

HTTP/1.1 200 OK
X-Ringside-Dynamic-Profile: cost-aware
X-Ringside-Dynamic-Reason: low difficulty, no tools, budget rung
X-Request-Id: req_8sKQ2v...

Errors and edge cases

Two operational edges to plan for. First, match: and slot: depend on a warm catalog: if the platform catalog has not been synced the resolver returns model_family_unknown rather than a stale guess. Second, resolution interacts with the cost cascade. When model is an array (a fallback chain), Ringside resolves each entry, walks the chain on a 5xx or a schema-validation failure and reports the winner via X-Ringside-Model-Used. A cascade cannot combine with stream:true (400 fallback_with_stream_unsupported) or with an idempotency-key (400 fallback_with_idempotency_unsupported).