Update policy
PATCH
/orgs/{org_name}/governance/policies/{policy_id} Partially updates a policy's metadata. Only fields present in the
request body are updated; absent fields are left unchanged. The scope
object is patched per sub-field: sending teams replaces that list,
while an omitted sub-field is left untouched and an empty list clears
it (org-wide).
The rule set is not modified here. Use the rule endpoints for that. At least one field must be present. Returns the policy in both its old and new states. Changes may take up to five minutes to reach developer machines.
Connection and access
API connection and authentication guidance
https://hub.docker.com/v2
Use one of these alternatives. Requirements within an alternative apply together.
bearerAuth
Parameters
org_name
path
Required
Docker Hub organization name.
Type:
string
All schema constraints and annotations
{
"type": "string"
}policy_id
path
Required
Unique policy identifier.
Type:
string
All schema constraints and annotations
{
"type": "string"
}Request and responses
Request
Fields to update. Absent fields are left unchanged.
application/json
Schema:
UpdatePolicyRequest
rename
{
"name": "Security Research"
}scope
{
"scope": {
"teams": [
"d290f1ee-6c54-4b01-90e6-d701748f0851"
]
}
}Response
200
Policy updated, returns old and new states.
application/json
Schema:
UpdatePolicyResponse
default
{
"new": {
"allowlist_v0": {
"domain": "network",
"rules": [
{
"actions": [
"connect:tcp",
"connect:udp"
],
"decision": "allow",
"id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna",
"name": "allow research mirrors",
"resources": [
"research.mitre.org",
"cve.mitre.org"
]
}
]
},
"created_at": "2026-04-22T00:00:00Z",
"id": "pol_06evsmp24r1pg71cm8500546pkbn",
"name": "Security Research",
"org": "my-org",
"scope": {
"teams": [
"d290f1ee-6c54-4b01-90e6-d701748f0851"
]
},
"updated_at": "2026-04-22T10:00:00Z"
},
"old": {
"allowlist_v0": {
"domain": "network",
"rules": [
{
"actions": [
"connect:tcp",
"connect:udp"
],
"decision": "allow",
"id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna",
"name": "allow research mirrors",
"resources": [
"research.mitre.org",
"cve.mitre.org"
]
}
]
},
"created_at": "2026-04-22T00:00:00Z",
"id": "pol_06evsmp24r1pg71cm8500546pkbn",
"name": "Security Research — hardened",
"org": "my-org",
"scope": {
"teams": [
"d290f1ee-6c54-4b01-90e6-d701748f0851"
]
},
"updated_at": "2026-04-22T00:00:00Z"
}
}Response
400
Bad request
application/json
Schema:
Error
default
{
"error": {
"code": "invalid_argument",
"message": "name is required"
}
}Response
401
Missing or invalid credentials
application/json
Schema:
Error
default
{
"error": {
"code": "unauthenticated",
"message": "unauthenticated"
}
}Response
403
Caller lacks the required permission for this org, the org is not entitled to use governance (
permission_denied), or a creation limit has been reached (limit_exceeded): the org already has the maximum number of policies, or the policy already has the maximum number of rules.application/json
Schema:
Error
limit_exceeded
{
"error": {
"code": "limit_exceeded",
"message": "organization has reached the maximum of 100 policies"
}
}permission_denied
{
"error": {
"code": "permission_denied",
"message": "permission denied"
}
}Response
404
Not found
application/json
Schema:
Error
default
{
"error": {
"code": "not_found",
"message": "policy not found"
}
}Response
409
Conflict
application/json
Schema:
Error
default
{
"error": {
"code": "conflict",
"message": "policy name already in use"
}
}Response
500
Internal server error
application/json
Schema:
Error
default
{
"error": {
"code": "internal",
"message": "internal error"
}
}Referenced schemas
#/components/schemas/UpdatePolicyRequest
#/components/schemas/UpdatePolicyResponse
Complete operation contract
{
"description": "Partially updates a policy's metadata. Only fields present in the\nrequest body are updated; absent fields are left unchanged. The `scope`\nobject is patched per sub-field: sending `teams` replaces that list,\nwhile an omitted sub-field is left untouched and an empty list clears\nit (org-wide).\n\nThe rule set is not modified here. Use the rule endpoints for that.\nAt least one field must be present. Returns the policy in both its old\nand new states. Changes may take up to five minutes to reach developer\nmachines.\n",
"operationId": "updatePolicy",
"requestBody": {
"content": {
"application/json": {
"examples": {
"rename": {
"summary": "Rename the policy",
"value": {
"name": "Security Research"
}
},
"scope": {
"summary": "Restrict to a team",
"value": {
"scope": {
"teams": [
"d290f1ee-6c54-4b01-90e6-d701748f0851"
]
}
}
}
},
"schema": {
"$ref": "#/components/schemas/UpdatePolicyRequest"
}
}
},
"description": "Fields to update. Absent fields are left unchanged.",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"new": {
"allowlist_v0": {
"domain": "network",
"rules": [
{
"actions": [
"connect:tcp",
"connect:udp"
],
"decision": "allow",
"id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna",
"name": "allow research mirrors",
"resources": [
"research.mitre.org",
"cve.mitre.org"
]
}
]
},
"created_at": "2026-04-22T00:00:00Z",
"id": "pol_06evsmp24r1pg71cm8500546pkbn",
"name": "Security Research",
"org": "my-org",
"scope": {
"teams": [
"d290f1ee-6c54-4b01-90e6-d701748f0851"
]
},
"updated_at": "2026-04-22T10:00:00Z"
},
"old": {
"allowlist_v0": {
"domain": "network",
"rules": [
{
"actions": [
"connect:tcp",
"connect:udp"
],
"decision": "allow",
"id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna",
"name": "allow research mirrors",
"resources": [
"research.mitre.org",
"cve.mitre.org"
]
}
]
},
"created_at": "2026-04-22T00:00:00Z",
"id": "pol_06evsmp24r1pg71cm8500546pkbn",
"name": "Security Research — hardened",
"org": "my-org",
"scope": {
"teams": [
"d290f1ee-6c54-4b01-90e6-d701748f0851"
]
},
"updated_at": "2026-04-22T00:00:00Z"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/UpdatePolicyResponse"
}
}
},
"description": "Policy updated, returns old and new states."
},
"400": {
"$ref": "#/components/responses/InvalidArgument"
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
},
"summary": "Update policy",
"tags": [
"policies"
]
}