---
title: "Set a policy's description and notes."
method: PUT
path: "/api/policies/{policyName}/details"
tags: ["Policies"]
---

# Set a policy's description and notes.

`PUT /api/policies/{policyName}/details`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/policies/{policyName}/details`
- Auth: HTTP bearer

Sets the description (up to 200 characters) and notes (up to 1000). A field left out is left as it is; an empty value clears it. They are not part of the policy, so this does not create a new version, and the revision stays the same, but the entity tag changes. Send the ETag from your read in If-Match to make the write conditional: if the policy, its description, or its notes changed since, nothing is written and the response is 409 with reason policy_changed. Without If-Match the write is not checked against an earlier read. Managed policies cannot be changed. Admins may change another user's by passing that user's username as owner. Requires the `policies:write` scope.

## Path parameters

- `policyName` string, required

## Query parameters

- `owner` string

## Headers

- `Authorization` string, required
- `If-Match` string

## Request body

- PolicyDetailsRequest
  - `description` string
  - `notes` string

## Response `200`

The policy's details after the change. The ETag header identifies them.

- PolicyDetailsResponse
  - `description` string
  - `name` string
  - `created` string, date-time
  - `etag` string: Identifies the policy together with its description and notes, and changes when any of them does; the revision alone does not change when only the details do. The ETag header carries the same value, quoted. Send it in If-Match to make a replace, a details change, or a rollback conditional.
  - `lastUpdated` string, date-time
  - `managed` boolean
  - `notes` string
  - `revision` integer

## Other responses

- `400`: The description or notes are too long, or If-Match is not an entity tag this API returned.
- `401`: The Authorization header is absent or the API key is not recognized.
- `403`: Insufficient scope, disabled API, or access denied.
- `404`: There is no such policy, or the owner does not exist or the caller may not reach it.
- `406`: No representation matches Accept.
- `409`: Nothing was changed, and reason says why: policy_managed (a managed policy) or policy_changed (it changed since the read If-Match names, or concurrently; read it again and retry).
- `413`: Content Too Large
- `415`: Unsupported Media Type
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-11** `adb70fdccccb`: 2 info
  - added the new optional `header` request parameter `If-Match`
  - added the optional property `etag` to the response with the `200` status
- **2026-10-10** `c4f85daa9208`: 15 info
  - added the optional property `field` to the response with the `400` status
  - added the optional property `field` to the response with the `401` status
  - added the optional property `field` to the response with the `404` status
  - added the optional property `field` to the response with the `413` status
  - …11 more
- **2026-10-06** `f60e7c9acbca`: 2 info
  - added the optional property `message` to the response with the `409` status
  - added the optional property `reason` to the response with the `409` status
- **2026-10-05** `4082c17721d8`: 6 breaking, 6 info
  - removed the media type `*/*` for the response with the status `400`
  - removed the media type `*/*` for the response with the status `401`
  - removed the media type `*/*` for the response with the status `413`
  - removed the media type `*/*` for the response with the status `415`
  - …8 more
- **2026-10-05** `fde4cd72aeb0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/philterd/apis/philter-api/changes/api/policies/:policyName/details/put.md)

---

[API](https://skmtc.dev/philterd/apis/philter-api.md) - [All operations](https://skmtc.dev/philterd/apis/philter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/philterd/apis/philter-api/revisions/aa3d7ad1aab4?raw)