---
title: "PATCH /policy-engines/{policyEngineId}/policies/{policyId}"
method: PATCH
path: "/policy-engines/{policyEngineId}/policies/{policyId}"
---

# PATCH /policy-engines/{policyEngineId}/policies/{policyId}

`PATCH /policy-engines/{policyEngineId}/policies/{policyId}`

Updates an existing policy within the AgentCore Policy system. This operation allows modification of the policy description and definition while maintaining the policy's identity. The updated policy is validated against the Cedar schema before being applied. This is an asynchronous operation. Use the <code>GetPolicy</code> operation to poll the <code>status</code> field to track completion.

## Path parameters

- `policyEngineId` string, required
- `policyId` string, required

## Request body

- object
  - `description` object — Wrapper for updating an optional Description field with PATCH semantics. When present in an update request, the description is replaced with optionalValue. When absent, the description is left unchanged. To unset the description, include the wrapper with optionalValue not specified.
    - `optionalValue` string, password — Represents an optional value that is used to update the human-readable description of the resource. If not specified, it will clear the current description of the resource.
  - `definition` object — Represents the definition structure for policies within the AgentCore Policy system. This structure encapsulates different policy formats and languages that can be used to define access control rules.
    - `cedar` object — The Cedar policy definition within the policy definition structure. This contains the Cedar policy statement that defines the authorization logic using Cedar's human-readable, analyzable policy language. Cedar policies specify principals (who can access), actions (what operations are allowed), resources (what can be accessed), and optional conditions for fine-grained control. Cedar provides a formal policy language designed for authorization with deterministic evaluation, making policies testable, reviewable, and auditable. All Cedar policies follow a default-deny model where actions are denied unless explicitly permitted, and forbid policies always override permit policies.
      - `statement` string, required — The Cedar policy statement that defines the authorization logic. This statement follows Cedar syntax and specifies principals, actions, resources, and conditions that determine when access should be allowed or denied.
    - `policyGeneration` object — The generated policy asset information within the policy definition structure. This contains information identifying a generated policy asset from the AI-powered policy generation process within the AgentCore Policy system. Each asset contains a Cedar policy statement generated from natural language input, along with associated metadata and analysis findings to help users evaluate and select the most appropriate policy option.
      - `policyGenerationId` string, required — The unique identifier for this policy generation request.
      - `policyGenerationAssetId` string, required — The unique identifier for this generated policy asset within the policy generation request.
    - `policy` object — An AgentCore policy statement that defines the access control rules. The statement can be a Cedar policy or a guardrails definition.
      - `statement` string, required — The body of the AgentCore policy statement. Contains the policy logic, which can be a Cedar policy or a guardrails definition.
  - `validationMode` 'FAIL_ON_ANY_FINDINGS' | 'IGNORE_ALL_FINDINGS' — The validation mode for the policy update. Determines how Cedar analyzer validation results are handled during policy updates. FAIL_ON_ANY_FINDINGS runs the Cedar analyzer and fails the update if validation issues are detected, ensuring the policy conforms to the Cedar schema and tool context. IGNORE_ALL_FINDINGS runs the Cedar analyzer but allows updates despite validation warnings. Use FAIL_ON_ANY_FINDINGS to ensure policy correctness during updates, especially when modifying policy logic or conditions.
  - `enforcementMode` 'ACTIVE' | 'LOG_ONLY' — The enforcement mode for a policy. Run this policy in <code>LOG_ONLY</code> mode to collect data on how it affects your application. Once you are satisfied with the data gathered, switch the policy to <code>ACTIVE</code>.

## Response `202`

Success

- UpdatePolicyResponse
  - `policyId` string, required — The unique identifier of the updated policy.
  - `name` string, required — The name of the updated policy.
  - `policyEngineId` string, required — The identifier of the policy engine managing the updated policy.
  - `createdAt` string, date-time, required — The original creation timestamp of the policy.
  - `updatedAt` string, date-time, required — The timestamp when the policy was last updated.
  - `policyArn` string, required — The ARN of the updated policy.
  - `status` 'CREATING' | 'ACTIVE' | 'UPDATING' | 'DELETING' | 'CREATE_FAILED' | 'UPDATE_FAILED' | 'DELETE_FAILED', required — The current status of the updated policy.
  - `enforcementMode` 'ACTIVE' | 'LOG_ONLY' — The current enforcement mode of the updated policy.
  - `definition` object, required — The updated Cedar policy statement.
    - `cedar` object — The Cedar policy definition within the policy definition structure. This contains the Cedar policy statement that defines the authorization logic using Cedar's human-readable, analyzable policy language. Cedar policies specify principals (who can access), actions (what operations are allowed), resources (what can be accessed), and optional conditions for fine-grained control. Cedar provides a formal policy language designed for authorization with deterministic evaluation, making policies testable, reviewable, and auditable. All Cedar policies follow a default-deny model where actions are denied unless explicitly permitted, and forbid policies always override permit policies.
      - `statement` string, required — The Cedar policy statement that defines the authorization logic. This statement follows Cedar syntax and specifies principals, actions, resources, and conditions that determine when access should be allowed or denied.
    - `policyGeneration` object — The generated policy asset information within the policy definition structure. This contains information identifying a generated policy asset from the AI-powered policy generation process within the AgentCore Policy system. Each asset contains a Cedar policy statement generated from natural language input, along with associated metadata and analysis findings to help users evaluate and select the most appropriate policy option.
      - `policyGenerationId` string, required — The unique identifier for this policy generation request.
      - `policyGenerationAssetId` string, required — The unique identifier for this generated policy asset within the policy generation request.
    - `policy` object — An AgentCore policy statement that defines the access control rules. The statement can be a Cedar policy or a guardrails definition.
      - `statement` string, required — The body of the AgentCore policy statement. Contains the policy logic, which can be a Cedar policy or a guardrails definition.
  - `description` string, password — The updated description of the policy.
  - `statusReasons` String[], required — Additional information about the update status.

## Other responses

- `480` — AccessDeniedException
- `481` — ValidationException
- `482` — ConflictException
- `483` — ThrottlingException
- `484` — ResourceNotFoundException
- `485` — InternalServerException

---

[API](https://skmtc.net/aws/apis/bedrock-agentcore-control.md) · [All operations](https://skmtc.net/aws/apis/bedrock-agentcore-control/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/bedrock-agentcore-control/versions/0ebde766792b/schema)