---
title: "Update Policy"
method: PUT
path: "/policies/{policy_id}"
---

# Update Policy

`PUT /policies/{policy_id}`

## Request

- Base URL: `https://api.grayswan.ai`
- URL: `https://api.grayswan.ai/policies/{policy_id}`
- Auth: none declared
- TypeScript: <https://skmtc.dev/grayswan/apis/gray-swan-ai-api/docs/policies/:policy_id/put.ts> (a function with typed inputs; its response is checked against the schema)

Update an existing policy.

Only provided fields will be updated. Omit fields to leave them unchanged.
Preset policies cannot be modified.
Requires admin role.

Docs: [Guide](https://docs.grayswan.ai/policy-management/policies) |
[API Reference](https://docs.grayswan.ai/api-reference/policies/update-policy)

Raises:
    ResourceNotFoundError: If the policy does not exist.
    PresetPolicyModificationError: If attempting to modify a preset policy.
    AdminRequiredError: If user is not an admin.

## Path parameters

- `policy_id` string, required

## Request body

- PolicyUpdateRequest: Request body for updating an existing policy (all fields optional).
  - `name` string, nullable
  - `description` string, nullable
  - `categories` object, nullable
  - `rule_modes` object, nullable
  - `rule_block_messages` object, nullable
  - `mode` string, nullable
  - `pre_violation_threshold` number, nullable
  - `pre_jb_threshold` number, nullable
  - `post_violation_threshold` number, nullable
  - `post_violation_jb_threshold` number, nullable
  - `scanners_config` object, nullable
  - `block_message` string, nullable

## Response `200`

Successful Response

- PolicyDetailResponse: Full policy response with all fields.
  - `id` string, required
  - `name` string, required
  - `description` string, nullable
  - `rules` object, required
  - `rule_modes` object
  - `rule_block_messages` object
  - `mode` string, nullable
  - `pre_violation_threshold` number, nullable
  - `pre_jb_threshold` number, nullable
  - `post_violation_threshold` number, nullable
  - `post_violation_jb_threshold` number, nullable
  - `scanners_config` object, nullable
  - `block_message` string, nullable
  - `is_preset` boolean
  - `created_at` string, date-time, nullable
  - `updated_at` string, date-time, nullable

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Content
- `500`: Internal Server Error

## Changes

- **2026-10-22** `ed4b27064dfa`: 1 breaking, 12 info
  - the `detail` response's property type changed from `array` to `string` for status `422`
  - added the new optional request property `rule_block_messages`
  - added the non-success response with the status `400`
  - added the non-success response with the status `401`
  - …9 more

[Operation history](https://skmtc.dev/grayswan/apis/gray-swan-ai-api/changes/policies/:policy_id/put.md)

---

[API](https://skmtc.dev/grayswan/apis/gray-swan-ai-api.md) - [All operations](https://skmtc.dev/grayswan/apis/gray-swan-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/grayswan/apis/gray-swan-ai-api/revisions/ed4b27064dfa?raw)