> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tied.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model settings

> Current routing profile and plan-filtered Tied-hosted catalogue.

Every operation requires an authenticated administrator of the URL account and
its `model_settings` feature. Missing authentication or account membership returns
401; a suspended member also receives 401. An authenticated member receives the ordinary 404 when the flag is disabled;
with the flag enabled a non-administrator receives 403. The current account scopes
all settings. Writes on an expired, locked trial return 402 before feature/role checks.

| Operation | Inputs | Result |
| - | - | - |
| `GET /api/v1/accounts/{account_id}/model_settings` | None | Effective profile, plan tier, lock version, profile catalogue, override role names |
| `PATCH /api/v1/accounts/{account_id}/model_settings` | Top-level `profile` and `lock_version` | Same response after the change, or a validation/lock refusal |
| `GET /api/v1/accounts/{account_id}/model_settings/tied_hosted_models` | None | `scope: tied_hosted`, plan tier, models and `byok_tier_limited: false` |

Parameter wrapping is disabled. Send `{"profile":"balanced","lock_version":0}`,
not a nested `model_setting` object. Profile must be a string. Lock version must
be a nonnegative integer or decimal integer string (1–10 digits), at most
2,147,483,647. Missing, null, negative, fractional, array or object values return
422 `{"error":"invalid_params"}`. Unknown fields are ignored. This controller
accepts no provider credential, per-job model or routing-option fields.

GET writes nothing. With no policy row the effective profile is Balanced,
source `default`, lock version 0. A stale version returns 409
`{"error":"stale"}` before validating the profile. A matching version and unchanged
profile is a no-op. A changed profile is validated and persisted atomically with
an account model-routing audit event. A first policy starts at version 1;
subsequent changes increment the version. Customers cannot leave a staff-pinned
profile. Re-read settings before retrying a stale update.

Profile refusals return 422 with `error: refused`, `code` and a localized `message`:

| Code | Meaning |
| - | - |
| `unknown_profile` | Unknown profile key |
| `staff_only_profile` | Customer cannot choose pinned or change a pinned policy |
| `plan_not_eligible` | Non-Balanced profile needs advanced or enterprise tier |
| `not_in_tier_allowlist` | Profile lacks a tier allowance |
| `golden_gate_unavailable` | Golden-set gate does not permit the profile |

Balanced passes profile eligibility validation. The profile catalogue lists key,
label, description, availability and nullable refusal code; pinned appears only
when current. Override rows expose role, nullable job group and `set_by: tied`.
They exclude private provider/model selections. `profile.source` is `default`,
`account` or `staff_pinned`. Empty overrides are `[]`.

The hosted catalogue returns allowed pairs ordered by provider and model, each
with `provider`, `model`, `display_name` (currently the model identifier). An empty
allowance returns `models: []`. No capabilities or availability fields are returned.
Neither settings response exposes provider keys, key references, last-four values
or digests. These operations do not validate provider keys or individual models.
Separate provider-key and routing API ownership remains with
[ENG-4915](https://linear.app/tied/issue/ENG-4915) and
[ENG-5860](https://linear.app/tied/issue/ENG-5860); reconciliation with I-30 is
[ENG-5876](https://linear.app/tied/issue/ENG-5876).

The OpenAPI operations describe the complete current response. Proposal judgments
in `docs/platform-api/proposals/ENG-5418.json` remain unapproved, MCP-hidden and
SDK-excluded pending per-operation and P9 external-AI data-flow review; they do not
activate an operational register or baseline.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.