---
title: "Copy a policy."
method: POST
path: "/api/policies/{policyName}/copy"
tags: ["Policies"]
---

# Copy a policy.

`POST /api/policies/{policyName}/copy`

## Request

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

Creates a new policy named by name from one of the caller's policies or, for a name starting with managed_, from a built-in managed policy. The copy has the source's policy and description; a copy of a managed policy notes which one it came from, and a copy of the caller's own policy keeps its notes. The copy starts its own version history and is active at once. Admins may copy within another user's account by passing that user's username as owner. Requires the `policies:write` scope.

## Path parameters

- `policyName` string, required

## Query parameters

- `name` string, required
- `owner` string

## Headers

- `Authorization` string, required

## Response `201`

The copy's details. The ETag header identifies the copy.

- 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 new name is missing or invalid.
- `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 to copy, or the owner does not exist or the caller may not reach it.
- `406`: No representation matches Accept.
- `409`: A policy with the new name already exists; reason is policy_exists.
- `413`: Content Too Large
- `415`: Unsupported Media Type
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-11** `adb70fdccccb`: 1 info
  - added the optional property `etag` to the response with the `201` 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** `de4eef465c2d`: 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/copy/post.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)