Create a gateway policy
Creates a gateway policy for the calling organization.
policy_type is one of spend_cap, default_spend_cap,
guard, route_config, model_fallback, rate_limit, or default_rate_limit.
The shape of config depends on policy_type:
spend_cap/default_spend_cap, one limit:{"window": "hourly"|"daily"|"weekly"|"monthly", "limit_usd": <number>}spend_cap/default_spend_cap, a limit per window:{"version": 2, "limits": [{"window": "hourly"|"daily"|"weekly"|"monthly", "limit_usd": <number>}]}guard:{"version": 1, "detect": {"pii": <bool>, "secrets": <bool>, "custom": [{"pattern": "<regex>"}]}, "timeout_seconds": <number>, "timeout_action": "allow"|"block"}timeout_seconds(optional, 0.1–30) caps guard pipeline execution time; defaults to 2s.timeout_actiondefaults toallow.detect.custom(optional) holds at most one Go regexp (RE2 syntax) of up to 512 bytes; matching text is redacted. Avoid capture groups: if present, only the first group is redacted, wherever that text appears.route_config:{"strategy": "priority_fallback", "triggers": {"status_codes": [<int>]}, "fallbacks": [{"model_configs": [{"model_config_id": "<playground-settings-uuid>"}]}]}triggersis required, with no default:status_codesmust be a non-empty list (include 502 and 504 for upstream transport failures).fallbackscontains an entry whosemodel_configsare tried in priority order (1–5).subject_matchersmust be a singleworkspace_identry.model_fallback:{"strategy": "priority_fallback", "triggers": {"status_codes": [429, 502, 503, 504]}, "chain": {"selector": {"type": "provider_model", "provider": "openai", "model": "gpt-4o"}, "candidates": [{"type": "provider_model", "provider": "openai", "model": "gpt-4o-mini"}, {"type": "model_config", "model_config_id": "<playground-settings-uuid>"}]}}Optionalejection: {"failure_threshold": <1-1000>, "cooldown_seconds": <1-300>}skips a candidate forcooldown_secondsafter it fails the chain’s triggersfailure_thresholdtimes withincooldown_seconds. Failures are counted per policy and candidate, only provider failures count, and success does not reset the count. The last candidate is never skipped.chain.candidatesis an ordered list of 1–5 direct provider models or saved workspace model configurations. A non-emptyworkspace_idmatcher is required.provider_modelselectors are workspace-only;aliasselectors may be narrowed byuser_idorapi_key_id. User Group-scoped model fallbacks are not supported. Provider/model selectors are unique within a workspace, while alias names are reserved across the organization and may intentionally shadow a model name. With"strategy": "weighted", each request tries the distinctchain.candidatesin a random order favoring higherweight(required, 1–1000), and trigger failures fall through that order.chain.candidatesmust include the selector’s model: the sameprovider_model, or for aproviders/<name>selector, that saved model configuration. Weighted chains don’t support alias selectors.priority_fallbackrejectsweight.rate_limit/default_rate_limit:{"version": 1, "limits": [{"metric": "requests"|"tokens", "window": "minute"|"hour", "value": <integer>}]}limitsmust be non-empty; eachmetric/windowpair may appear at most once.valueis 1..1000000000000000.
subject_matchers is a list of {key, value} pairs. Built-in
keys are organization_id, user_group_id, workspace_id, agent_uuid,
agent_environment, user_id, api_key_id, and run_rule_id.
Values under the same key are ORed; distinct keys are ANDed.
user_group_id must be an organization-level User Group UUID, not a workspace child User Group UUID.
Membership in a workspace child User Group matches its organization parent User Group ID. User Group IDs are not checked for existence.
agent_uuid and agent_environment target requests from Agent
deployments: agent_uuid alone targets those Agents, agent_environment
(LOCAL, DEVELOPMENT, STAGING, or PRODUCTION) alone targets
every Agent in those environments, and both together target those
Agents in those environments. agent_uuid can’t be combined with
workspace_id; agent_environment alone may add one workspace_id.
Agent keys are
not supported in default policies. A default policy uses an empty built-in matcher value so
the runtime materializes a child for each subject it sees. A
default_spend_cap and default_rate_limit may add one empty custom
metadata key to bucket each subject by the corresponding
X-Gateway-* request header; the materialized child stores both values.
With a custom header, the built-in value may name one subject (e.g. one
api_key_id) to bucket only that subject’s requests. It replaces the
organization-wide default of the same kind split by the same header.
action is currently always block. Spend caps reject the
request with 402 when the limit is hit; rate limits reject with
429 (with a Retry-After hint) when a limit is exceeded; guard
policies redact matched content in-place before forwarding upstream.
Upsert by matchers: for spend_cap, default_spend_cap,
rate_limit, default_rate_limit, and guard, if a policy with
the same subject_matchers already exists in this organization,
the existing policy is updated in place instead of a duplicate
being created. id is preserved. route_config and model_fallback do not upsert
by matchers — name must be unique per organization (409 on
conflict). Returns 201 either way.
Body
Response
Created

