Update a policy

Updates an existing policy. mcp_scope is tri-state: omitted keeps the stored scope, null clears it and an object replaces it. An update that moves the policy onto a level another policy of the same plugin already holds is refused with 409, and so is turning enabled back on when that is what takes the level. An update racing a promotion or demotion of the same policy is refused with 409: reload it and retry. Changing the slug of an MCP-wide policy to a plugin without MCP support is refused with 422. The response may carry non-blocking warnings.

PUT /v1/gateways/{gateway_id}/policies/{id}

Error

A valid request URL is required to generate request examples

200

{
  "consumer_ids": [
    "<string>"
  ],
  "created_at": "<string>",
  "description": "<string>",
  "enabled": true,
  "gateway_id": "<string>",
  "global": true,
  "id": "<string>",
  "mcp_scope": {
    "except_groups": [
      "<string>"
    ],
    "groups": [
      "<string>"
    ],
    "registry_ids": [
      "<string>"
    ],
    "tools": [
      {
        "registry_id": "<string>",
        "tool": "<string>"
      }
    ]
  },
  "mcp_wide": true,
  "mode": "<string>",
  "name": "<string>",
  "parallel": true,
  "priority": 123,
  "settings": {},
  "slug": "<string>",
  "stages": [
    "<string>"
  ],
  "status": "active",
  "status_message": "<string>",
  "updated_at": "<string>",
  "warnings": [
    "<string>"
  ]
}

Authorizations

Authorization · string · header · required

Path Parameters

gateway_id · string<uuid> · required

Gateway id

id · string<uuid> · required

Policy id

Body

application/json

Policy fields to update

description · string

enabled · boolean

mcp_scope · object

MCPScope is tri-state: omitted leaves the stored scope untouched, null clears it and an object replaces it. A pointer field could not tell omitted from null, so the raw JSON is kept until ToMCPScope reads it.

mode · string

name · string

parallel · boolean

priority · integer

settings · object

Show child attributes

slug · string

stages · string[]

Response

200

application/json

OK

consumer_ids · string[]

created_at · string

description · string

enabled · boolean

gateway_id · string

global · boolean

id · string

mcp_scope · object

MCPScope is echoed as stored: absent when the policy is consumer-wide, {} when a registry delete pruned every destination.

Show child attributes

mcp_wide · boolean

MCPWide marks a policy that runs on every MCP consumer of the gateway and on the MCP Store, narrowed by its mcp_scope. It is never true together with Global, and an MCP-wide policy has no consumer_ids.

mode · string

name · string

parallel · boolean

priority · integer

settings · object

Show child attributes

slug · string

stages · string[]

status · enum<string>

Status is "active" (enabled and running), "paused" (disabled) or "error" (enabled but the gateway cannot run it; see status_message).

Available options: active, paused, error

status_message · string

StatusMessage is the reason the gateway cannot run the policy. It is present only when status is "error".

updated_at · string

warnings · string[]

Warnings are non-blocking notes about the write that just succeeded, such as a consumer that already runs the same plugin without scope.