# Update policy [API catalog](/reference/api/) · [AI Governance overview](/reference/api/ai-governance/latest/) · [Product manual](https://docs.docker.com/ai/sandboxes/governance/) · [OpenAPI specification](/reference/api/ai-governance/api.yaml) API version: 1 `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](/reference/api/ai-governance/latest/#authentication) Server: `https://hub.docker.com/v2` Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement. ```json [ { "bearerAuth": [] } ] ``` ## Example request Replace placeholders and provide the required credentials or request body. ```console curl \ --request PATCH \ --header "Authorization: Bearer ${TOKEN}" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Security Research" }' \ 'https://hub.docker.com/v2/orgs//governance/policies/' ``` ## Parameters ### org_name Location: path. Required: yes. Docker Hub organization name. ```json { "description": "Docker Hub organization name.", "examples": { "default": { "value": "my-org" } }, "in": "path", "name": "org_name", "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/parameters/0", "required": true, "schema": { "type": "string" } } ``` ### policy_id Location: path. Required: yes. Unique policy identifier. ```json { "description": "Unique policy identifier.", "examples": { "default": { "value": "pol_06evsmp24r1pg71cm8500546pkbn" } }, "in": "path", "name": "policy_id", "pointer": "/paths/~1orgs~1{org_name}~1governance~1policies~1{policy_id}/parameters/1", "required": true, "schema": { "type": "string" } } ``` ## Request and responses ### Request application/json Fields to update. Absent fields are left unchanged. Schema: ```json { "$ref": "#/components/schemas/UpdatePolicyRequest" } ``` rename: ```json { "name": "Security Research" } ``` scope: ```json { "scope": { "teams": [ "d290f1ee-6c54-4b01-90e6-d701748f0851" ] } } ``` ### Response 200 application/json Policy updated, returns old and new states. Schema: ```json { "$ref": "#/components/schemas/UpdatePolicyResponse" } ``` default: ```json { "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 application/json Bad request Schema: ```json { "$ref": "#/components/schemas/Error" } ``` default: ```json { "error": { "code": "invalid_argument", "message": "name is required" } } ``` ### Response 401 application/json Missing or invalid credentials Schema: ```json { "$ref": "#/components/schemas/Error" } ``` default: ```json { "error": { "code": "unauthenticated", "message": "unauthenticated" } } ``` ### Response 403 application/json 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. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` limit_exceeded: ```json { "error": { "code": "limit_exceeded", "message": "organization has reached the maximum of 100 policies" } } ``` permission_denied: ```json { "error": { "code": "permission_denied", "message": "permission denied" } } ``` ### Response 404 application/json Not found Schema: ```json { "$ref": "#/components/schemas/Error" } ``` default: ```json { "error": { "code": "not_found", "message": "policy not found" } } ``` ### Response 409 application/json Conflict Schema: ```json { "$ref": "#/components/schemas/Error" } ``` default: ```json { "error": { "code": "conflict", "message": "policy name already in use" } } ``` ### Response 500 application/json Internal server error Schema: ```json { "$ref": "#/components/schemas/Error" } ``` default: ```json { "error": { "code": "internal", "message": "internal error" } } ``` ## Complete operation contract ```json { "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" ] } ``` ## Referenced schemas - `#/components/responses/Conflict` - `#/components/responses/Forbidden` - `#/components/responses/InternalError` - `#/components/responses/InvalidArgument` - `#/components/responses/NotFound` - `#/components/responses/Unauthenticated` - [#/components/schemas/UpdatePolicyRequest](/reference/api/ai-governance/latest/schemas/UpdatePolicyRequest/) - [#/components/schemas/UpdatePolicyResponse](/reference/api/ai-governance/latest/schemas/UpdatePolicyResponse/)