Class AIGatewayApi

Requires ai_gateway_config_write and provider Edit. Models and pricing inherit provider access. Add multiple manually managed model catalog entries to a provider in a single request. Manually managed entries are not modified by automatic catalog synchronization.

Create a spend budget. Scope tags may include provider, model, and custom dimensions. Reserved metadata keys are rejected.

Create a scoped override with a client-generated UUID and the current configuration_revision. If the override can enable full capture for more traffic, set confirm_full_capture to true. Returns HTTP 409 when configuration_revision is stale, the UUID already exists, or the organization has 100 overrides. Missing configuration_revision or required full-capture confirmation returns HTTP 400. Retrying an accepted create with the same UUID returns HTTP 409. To undo a create, read the current configuration revision and delete the override using its returned override revision.

Requires ai_gateway_config_write and provider Edit. Models and pricing inherit provider access. Add a manually managed model catalog entry to a provider. Manually managed entries are not modified by automatic catalog synchronization.

Create an AI Gateway model group from a name and any combination of model catalog entries and routing rules, with optional fast-mode and reasoning limits and initial access bindings.

Creating a provider requires ai_gateway_config_write. No provider View check applies before creation. Create a provider and its initial model catalog. All discovered models are enabled; optional models are added as manually managed entries. The slug is the immutable routing identifier. Provider and initial catalog rows are saved in one transaction. Initial sharing is unavailable: supplying initial_bindings returns 503 with stage initial_permissions and outcome not_saved. A failed database commit can return 503 with stage database_commit and outcome unknown; check the provider list before retrying. Creation without initial_bindings keeps normal unrestricted defaults.

Create a rate limit. All requests matching its scope share one allowance, and every matching rate limit applies. Returns 409 when another active rate limit has the same user, Team, and tags, or when the organization already has the maximum number of rate limits.

Create an organization-owned routing rule. Data capture overrides are managed independently. Each tier has an ordering, which defaults to configured. A weighted_affinity tier distributes first-choice assignments by relative target weights (1 to 10000, default 1) and accepts only distinct model targets with an explicit provider. Weights need not total 100. Configured tiers must omit weights or set them to null.

Archive a spend budget by ID while retaining its accounting history.

Delete an override using its revision and the current configuration_revision. If deleting the override can enable full capture for affected traffic, set confirm_full_capture to true. Returns HTTP 409 when configuration_revision or the override revision is stale, including a concurrent change during deletion. Missing revisions or required full-capture confirmation returns HTTP 400.

Requires ai_gateway_config_write and provider Edit. Models and pricing inherit provider access. Delete a manually managed model catalog entry by its canonical model ID. Discovered entries are read-only.

Delete a named model group. The organization-wide policy cannot be deleted. Requires configuration write permission and edit access to the group.

Clear a custom provider model's pricing override. Requires ai_gateway_config_write and provider Edit. Models and pricing inherit provider access.

Delete the routing policy document for a specific inbound pattern.

Requires ai_gateway_config_write and provider Edit. Models and pricing inherit provider access. This also applies when force=true. Existing cascades remain and can affect policies the caller cannot edit. Delete a provider by ID. Providers used by routing rules return provider_in_use with HTTP 409 and the affected rules in error metadata. Retry with force=true to remove provider targets and delete rules left without targets. Surviving tiers keep their ordering and weights. A deletion that would rewrite a surviving tier with an unknown ordering_issue fails with HTTP 409 and code routing_rule_unknown_ordering until that rule is replaced or deleted.

Archive a rate limit by ID. An archived rate limit no longer appears in lists or lookups, and its alert monitor is deleted.

Delete a routing rule. Referenced rules require force=true. Surviving tiers keep their ordering and weights. A deletion that would rewrite a surviving tier with an unknown ordering_issue fails with HTTP 409 and code routing_rule_unknown_ordering until that rule is replaced or deleted.

Get a spend budget by ID, including its capacity, scope, reset window, warning threshold, and enforcement mode.

Get the active accounting window, enforced capacity, and current spend.

Aggregate counters for an accounting window, including total spend and the numbers of instances at or above the warning threshold and capacity. Use split_dim to aggregate only counters that match every given dimension value.

Get the organization default mode, scoped capture overrides, and configuration revision.

Get the organization-wide AI Gateway governance settings, which are the default data capture mode and whether requests must reach providers covered by a zero data retention agreement.

Get a named policy or the explicit organization-wide policy by id "default". Requires configuration read permission; named policies also require view access. Provider selections cover current and future models and are returned separately from individual model selections.

Get a custom provider model's pricing override and effective pricing source. Requires ai_gateway_config_read and provider View. Catalog and pricing metadata inherit provider access. Lists omit hidden entries; direct reads of hidden resources return 404.

Get the routing policy document for a specific inbound pattern.

Get a provider by ID, including its routing slug, integration account, and cost multiplier. Credentials stay in the integration account and are never returned. Requires ai_gateway_config_read and provider View. Catalog and pricing metadata inherit provider access. Lists omit hidden entries; direct reads of hidden resources return 404.

Get a rate limit by ID, including its scope, per-minute request and token limits, and whether it is enabled.

Get live usage for the organization's rate limits. Returns requests and tokens counted in the rolling one-minute window and requests limited in the last 15 minutes for each enabled rate limit, plus untracked (traffic no enforced rate limit covers) and total (all gateway traffic).

Get a routing rule by its organization-unique slug.

Search the values that a template budget's split dimensions take across its instance counters in an accounting window. Each dimension returns its top values by spend, with counter counts. Use query or value to narrow results and limit to cap them. The truncated field reports whether more values matched. Each dimension's values are counted under the other dimensions' split_dim filters, so a dimension's own filter does not hide its alternatives. Legacy fixed-scope budgets return an empty list.

List instance counters for an accounting window. Legacy fixed-scope budgets return one pooled row with an empty instance_key. Omit window to use the current window. Use split_dim to keep only counters that match every given dimension value.

List spend budgets for the organization, including active-window spend and effective capacity.

List model groups the user can view. The organization-wide policy has id "default" and explicit model, provider, and route selections. Missing or empty selections grant no organization-wide access. Its audience is fixed to the organization; it cannot be renamed or deleted. Named policies retain their access bindings. Requires configuration read permission; named policies also require view access.

List all model catalog entries for a provider. Requires ai_gateway_config_read and provider View. Catalog and pricing metadata inherit provider access. Lists omit hidden entries; direct reads of hidden resources return 404.

List all model catalog entries grouped by canonical model ID. Requires ai_gateway_config_read and provider View. Catalog and pricing metadata inherit provider access. Lists omit hidden entries; direct reads of hidden resources return 404.

List all routing policy documents for the organization. Pass user_id to filter by user scope.

List live models available to a provider integration account that supports model discovery.

List the model providers connected to the organization. Credentials stay in each provider's integration account and are never returned. Requires ai_gateway_config_read and provider View. Catalog and pricing metadata inherit provider access. Lists omit hidden entries; direct reads of hidden resources return 404.

List the organization's AI Gateway rate limits.

List all routing rules for the organization.

Override active-period capacity for one instance of a template budget, identified by its instance_key. Other instances and the budget's default capacity are unchanged. The override is retained in the budget adjustment audit history. Returns 404 when the instance has no counter in the active period. Not supported for legacy fixed-scope budgets.

Reset active-period spend for one instance of a template budget, identified by its instance_key. The reset is retained in the budget adjustment audit history. Returns 404 when the instance has no counter in the active period. Not supported for legacy fixed-scope budgets.

Update a budget's mutable definition. Capacity changes apply to future accounting periods unless apply_to_current_period is true.

Replace an override using its revision and the current configuration_revision. Changes to capture overrides don't affect routing rules. Returns HTTP 409 when configuration_revision or the override revision is stale, including a concurrent change during replacement. Missing revisions or required full-capture confirmation returns HTTP 400.

Replace the organization-wide AI Gateway governance settings, which are the default data capture mode and whether requests must reach providers covered by a zero data retention agreement.

Update a manually managed model catalog entry. Discovered entries are read-only. Requires ai_gateway_config_write and provider Edit. Models and pricing inherit provider access.

Update a model group. For id "default", save membership and request options atomically with expected_revision. Empty selections grant no organization-wide access. Applicable authorized named policies override organization-wide request options; a rejected named-policy request cannot fall back to organization-wide options. The organization-wide audience is fixed and grants resource use only. Requires configuration write permission; named policies also require edit access.

Set a custom provider model's pricing override. Requires ai_gateway_config_write and provider Edit. Models and pricing inherit provider access.

Update a provider's display name or cost multiplier. Provider type, integration settings, and slug are immutable. Requires ai_gateway_config_write and provider Edit. Models and pricing inherit provider access.

Update a rate limit. Only the attributes sent are changed. Scope stays editable, and changes never reset current usage. Returns 409 when the rule was changed concurrently or the new scope duplicates another rule.

Replace a routing rule's tiers. The slug is immutable; data capture is managed independently. This is a full replacement: omitted or null ordering resets the tier to configured, and omitted or null weights in a weighted_affinity tier reset to 1. Omitted or null reasoning_level clears a model destination's reasoning override. Replacing a rule repairs tiers reported with an ordering_issue.

Create or replace the routing policy document for an inbound pattern. Pass user_id to scope the policy to a user.