API reference · API 1.0.0

AI gateway

AI gateway virtual keys and serving tiers.

get /api/v1/ai/gateway

The AI gateway

Operation ai_gateway_get · bearer token

The OpenAI-compatible base URL and the serving-tier names. The base URL comes from the gateway credential the keys are minted against, so it always names the gateway that issued them.

Responses

  • 200

    The AI gateway.

    application/json → AiGateway
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The gateway is not configured on this platform (gateway_not_configured) or cannot be reached (gateway_unreachable). Also: the platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
get /api/v1/ai/gateway/keys

List virtual keys

Operation ai_gateway_keys_list · bearer token

Registry data only (live is not_read): the list does not call the gateway and works when it is down. Read one key for its live allowlist, limits and spend.

Parameters

NameInTypeDescription
organization_id query string | null

Only this tenant's keys.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
env query string | null
one of dev, uat, prod
app query string | null

Exact app.
origin query string | null
one of api, adopted
key_alias query string | null

Exact alias: at most one live key. Finds the id to import a key by its name.

max length 200
limit query integer

Page size.

min 1 · max 200 · default 50
cursor query string | null

next_cursor from the previous page; omit it for the first page. A cursor this list did not issue is a 400 invalid_cursor.

Responses

  • 200

    One page of virtual keys.

    application/json → GatewayKeyPage
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
post /api/v1/ai/gateway/keys

Create a virtual key

Operation ai_gateway_keys_create · bearer token

Mints a key named <tenant-slug>-<env>-<app>[-<feature>] and stores its value in the secrets store at secret_path (always). The value is in this response only when expose_secret is true; an idempotent replay never carries it. Budgets are soft: the gateway alerts and never blocks. The answer shows what was written (live is not_read, spend_usd null): GET the key for its live values. Send an Idempotency-Key to make a retry safe: a retry with the same key and request gets the first answer and changes nothing.

Parameters

NameInTypeDescription
Idempotency-Key header string

Makes a retry safe: for 24 hours, the same key with the same request (method, path, query and body) answers with the stored response (Idempotent-Replayed: true) instead of doing the work again. The same key with a different request is a 409 idempotency_key_reused; while the first request is still running it is a 429 idempotency_request_in_progress with Retry-After. 1-255 printable characters without spaces (400 invalid_idempotency_key otherwise); a UUID is a good key. Keys are scoped to the calling account.

min length 1 · max length 255 · pattern ^[!-~]+$

Request bodyrequired

application/json

Schema GatewayKeyCreate

A new virtual key, made on the gateway and stored in the secrets store. Its alias is <organisation-slug>-<env>-<app>[-<feature>].

NameTypeDescription
apprequired string

The application the key is for: lowercase words joined by single hyphens, 1-40 characters. Part of key_alias. Frozen.

min length 1 · max length 40 · pattern ^[a-z0-9]+(-[a-z0-9]+)*$
budget_duration string | null

The soft budget's period: a number and s, m, h, d or mo, e.g. 30d; the spend counted against soft_budget_usd restarts after each period.

pattern ^[1-9][0-9]{0,3}(s|m|h|d|mo)$
envrequired string

The environment the key is for: dev, uat or prod. Frozen.

one of dev, uat, prod
expose_secret boolean

Return the key's value in THIS response (secret). It is stored in the secrets store either way and never returned again.

default false
feature string | null

Optional: the application's feature the key is for, same rule as app. Part of key_alias. Frozen.

min length 1 · max length 40 · pattern ^[a-z0-9]+(-[a-z0-9]+)*$
modelsrequired array of string

A SET of tier names from the serving-tier catalogue: order carries no meaning and a name given twice counts once. Written de-duplicated and sorted (to the registry and to the gateway) and always returned sorted, so the same set always reads back the same. A tier that exists but serves nothing right now is accepted with a tier_not_serving warning.

min items 1 · max items 50
organization_idrequired string

The owning tenant.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
project_id string | null

Optional: a project of that tenant the key serves.

pattern ^[1-9][0-9]{0,8}$
rpm_limit integer | null

Requests per minute the gateway allows the key; null for no limit.

min 1 · max 1000000000
soft_budget_usd number (double) | null

SOFT budget in US dollars: the gateway alerts when it is reached and NEVER blocks. There is no hard limit in v1.

greater than 0 · max 1000000000
tpm_limit integer | null

Tokens per minute the gateway allows the key; null for no limit.

min 1 · max 2000000000

Responses

  • 201

    The key, as written.

    application/json → GatewayKey
    Headers: Idempotent-Replayed, X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 409

    A live key has the alias (key_alias_taken), or the gateway already has a key with it that is not registered (key_alias_on_gateway: adopt it instead).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 422

    No such tenant (organization_not_found) or project (project_not_found, project_not_in_organization), a tier the catalogue does not have (unknown_tier), or the body is invalid.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 502

    The gateway refused the call (gateway_refused).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 503

    The gateway is not configured on this platform (gateway_not_configured) or cannot be reached (gateway_unreachable). Checked BEFORE the tenant, project and tiers the body names, so a platform without a gateway answers 503 whatever the body says. Or the secrets store did not keep the value (secret_store_write_failed); the key was then removed from the gateway again (key_removed_from_gateway). Also: the platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
get /api/v1/ai/gateway/keys/{key_id}

One virtual key

Operation ai_gateway_keys_get · bearer token

The registry row with the key's LIVE allowlist, limits and spend from the gateway. live is missing when the gateway no longer has the key. Never the key's value.

Parameters

NameInTypeDescription
key_idrequired path string

Responses

  • 200

    The key, with its live values.

    application/json → GatewayKey
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such key (key_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The gateway is not configured on this platform (gateway_not_configured) or cannot be reached (gateway_unreachable). Also: the platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
patch /api/v1/ai/gateway/keys/{key_id}

Change a virtual key

Operation ai_gateway_keys_update · bearer token

Changes the allowlist, the limits and the soft budget on the gateway without changing the key's value (that is a rotation). organization_id, env, app and feature are frozen: sending the current value is accepted, a different one is a 422. Changing only project_id does not call the gateway. The answer shows what was written (live is not_read, spend_usd null): GET the key for its live values.

The body is a JSON Merge Patch (RFC 7396), sent as application/merge-patch+json or application/json: a member that is omitted is left unchanged, and a member set to null clears that field where clearing is allowed (the schema marks those fields nullable; null for any other field is a 422).

Parameters

NameInTypeDescription
key_idrequired path string

Request bodyrequired

application/jsonapplication/merge-patch+json

Schema GatewayKeyPatch

JSON Merge Patch (RFC 7396): a member that is omitted keeps its current value; a member sent as null clears the field when the field is nullable (the schema marks it so), and null for any other field is a 422. A "" is a value (an empty string), not a clear. Here null clears a limit, the soft budget, its duration or the project; models cannot be null. The key's value is never changed here (that is a rotation).

NameTypeDescription
app string | null

Frozen.
budget_duration string | null

null clears it.

pattern ^[1-9][0-9]{0,3}(s|m|h|d|mo)$
env string | null

Frozen.

one of dev, uat, prod
feature string | null

Frozen.
models array of string | null

A SET of tier names from the serving-tier catalogue: order carries no meaning and a name given twice counts once. Written de-duplicated and sorted (to the registry and to the gateway) and always returned sorted, so the same set always reads back the same.

min items 1 · max items 50
organization_id string | null

Frozen.
project_id string | null

null clears it.

pattern ^[1-9][0-9]{0,8}$
rpm_limit integer | null

null clears it.

min 1 · max 1000000000
soft_budget_usd number (double) | null

SOFT budget in US dollars: the gateway alerts when it is reached and NEVER blocks. There is no hard limit in v1. null clears it.

greater than 0 · max 1000000000
tpm_limit integer | null

null clears it.

min 1 · max 2000000000

Responses

  • 200

    The key after the change.

    application/json → GatewayKey
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such key (key_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 409

    The gateway no longer has the key (key_missing_on_gateway).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 422

    A frozen key was changed (immutable_field), an unknown tier (unknown_tier), no such project (project_not_found, project_not_in_organization), or the body is invalid.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 502

    The gateway refused the call (gateway_refused).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 503

    The gateway is not configured on this platform (gateway_not_configured) or cannot be reached (gateway_unreachable). Also: the platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
delete /api/v1/ai/gateway/keys/{key_id}

Delete a virtual key

Operation ai_gateway_keys_delete · bearer token

Deletes the key in the gateway — IRREVERSIBLY: every client using it fails at once — then the secrets store entry and pointer the portal wrote for it (an adopted key's secrets store entry belongs to its consumer and is left alone), and marks the registry row deleted. Needs the admin permission; NOT destroy-gated (a token without allow_destroy may delete keys). A key the gateway had already lost is deleted from the registry the same way.

Parameters

NameInTypeDescription
key_idrequired path string

Responses

  • 204

    The key was deleted.

    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such key (key_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 502

    The gateway refused the call (gateway_refused).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 503

    The gateway is not configured on this platform (gateway_not_configured) or cannot be reached (gateway_unreachable). Also: the platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
post /api/v1/ai/gateway/keys/{key_id}/rotations

Rotate a virtual key

Operation ai_gateway_keys_rotate · bearer token

A new value under the same alias, with the key's current allowlist, limits and soft budget. The new value is stored in the secrets store at secret_path and is in this response only when expose_secret is true. The old value stops working at once. The answer shows registry values (live is not_read, spend_usd null): GET the key for its live values. Send an Idempotency-Key to make a retry safe: a retry with the same key and request gets the first answer and changes nothing.

Parameters

NameInTypeDescription
key_idrequired path string
Idempotency-Key header string

Makes a retry safe: for 24 hours, the same key with the same request (method, path, query and body) answers with the stored response (Idempotent-Replayed: true) instead of doing the work again. The same key with a different request is a 409 idempotency_key_reused; while the first request is still running it is a 429 idempotency_request_in_progress with Retry-After. 1-255 printable characters without spaces (400 invalid_idempotency_key otherwise); a UUID is a good key. Keys are scoped to the calling account.

min length 1 · max length 255 · pattern ^[!-~]+$

Request body

application/json

Schema GatewayKeyRotation

A rotation: the key gets a new value, the old one stops working, and everything else about the key stays. The body may be empty.

NameTypeDescription
expose_secret boolean

Return the NEW value in this response (secret). It is stored in the secrets store either way.

default false

Responses

  • 200

    The key with its new value.

    application/json → GatewayKey
    Headers: Idempotent-Replayed, X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such key (key_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 409

    The key was adopted (key_adopted: its value lives in a consumer's own secrets store entry, so a new value would break that consumer), or the gateway no longer has it (key_missing_on_gateway).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 502

    The gateway refused the call (gateway_refused).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 503

    The gateway is not configured on this platform (gateway_not_configured) or cannot be reached (gateway_unreachable). Or the secrets store did not keep the new value (secret_store_write_failed); the key then keeps its old value. Also: the platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
get /api/v1/ai/gateway/tiers

List serving tiers

Operation ai_gateway_tiers_list · bearer token

The serving tiers of the AI gateway, in key order, each with what serves it right now (resolved_model, source) and the models it could be pinned to (candidate_models). Tiers exist only as the platform defines them: this API pins and enables a tier (PUT), it never creates or deletes one.

Parameters

NameInTypeDescription
limit query integer

Page size.

min 1 · max 200 · default 50
cursor query string | null

next_cursor from the previous page; omit it for the first page. A cursor this list did not issue is a 400 invalid_cursor.

Responses

  • 200

    One page of serving tiers.

    application/json → ServingTierPage
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
get /api/v1/ai/gateway/tiers/{key}

One serving tier

Operation ai_gateway_tiers_get · bearer token

One serving tier by key, with what serves it right now and the models it could be pinned to.

Parameters

NameInTypeDescription
keyrequired path string

The tier's name, e.g. code-max.

Responses

  • 200

    The serving tier.

    application/json → ServingTier
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such tier (tier_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
put /api/v1/ai/gateway/tiers/{key}

Pin or enable a serving tier

Operation ai_gateway_tiers_put · bearer token

Sets pinned_model and/or enabled on an existing tier; an omitted member is left unchanged, pinned_model: null returns the tier to auto-assign. The gateway is then reconciled at once (a reconcile_not_applied warning says when it could not be reached; the periodic reconcile applies the change later). A pin changes what EVERY client of the tier gets. Destroying a tier in Terraform only forgets it: there is no delete.

Parameters

NameInTypeDescription
keyrequired path string

The tier's name, e.g. code-max.

Request bodyrequired

application/json

Schema ServingTierPut

Set the pin and/or the enabled flag of an EXISTING tier (tiers exist only by migration). An omitted member is left unchanged.

NameTypeDescription
allow_unloaded_pin boolean

Accept a pinned_model that is not loaded. The tier then serves nothing, and the gateway drops it, until that model is loaded.

default false
enabled boolean | null

false hides the tier from every client.
pinned_model string | null

A served model name, or null to return the tier to auto-assign. A name that is not in candidate_models is refused (model_not_loaded) unless allow_unloaded_pin is true; sending the tier's CURRENT pin is always accepted.

pattern ^[A-Za-z0-9._:/@+-]{1,200}$

Responses

  • 200

    The serving tier after the change.

    application/json → ServingTier
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such tier (tier_not_found). Tiers exist only by migration: there is no create or delete.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 422

    pinned_model is not loaded on the fleet (model_not_loaded; candidates lists what is) and allow_unloaded_pin was not set, or the body is invalid.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID

Rendered from openapi-v1.json, platform release 1.0.187. Your installation serves the contract of its own version at /api/v1/openapi.json.