# Create rule [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 `POST /orgs/{org_name}/governance/policies/{policy_id}/rules` Adds a rule to the policy's rule set. All rules in a policy must share the same domain (network or filesystem); mixing domains is rejected. **Network** actions: `connect:tcp`, `connect:udp`. Resources are hostnames (for example, `example.com`), wildcard subdomains (`*.example.com` for one level, `**.example.com` for any depth), hostnames with an optional port (for example, `example.com:443`), or CIDRs in IPv4 or IPv6 notation (for example, `10.0.0.0/8` or `2001:db8::/32`). **Filesystem** actions: `read`, `write`. Resources are paths (for example, `/data`). Use `*` to match within a single path segment and `**` to match recursively across segments (for example, `/data/**`). 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 POST \ --header "Authorization: Bearer ${TOKEN}" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "actions": [ "read", "write" ], "decision": "allow", "name": "allow data directory", "resources": [ "/data" ] }' \ 'https://hub.docker.com/v2/orgs//governance/policies//rules' ``` ## 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}~1rules/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}~1rules/parameters/1", "required": true, "schema": { "type": "string" } } ``` ## Request and responses ### Request application/json Rule definition including actions, resources, and decision. Schema: ```json { "$ref": "#/components/schemas/CreateRuleRequest" } ``` filesystem: ```json { "actions": [ "read", "write" ], "decision": "allow", "name": "allow data directory", "resources": [ "/data" ] } ``` network: ```json { "actions": [ "connect:tcp", "connect:udp" ], "decision": "allow", "name": "allow research mirrors", "resources": [ "research.mitre.org", "cve.mitre.org" ] } ``` ### Response 201 application/json Rule created and added to the policy's rule set. Schema: ```json { "$ref": "#/components/schemas/Rule" } ``` filesystem: ```json { "actions": [ "read", "write" ], "decision": "allow", "id": "rule_07fwtnr0kn2qetl1b9olfbyz8kob", "name": "allow data directory", "resources": [ "/data" ] } ``` network: ```json { "actions": [ "connect:tcp", "connect:udp" ], "decision": "allow", "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", "name": "allow research mirrors", "resources": [ "research.mitre.org", "cve.mitre.org" ] } ``` ### 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": "Adds a rule to the policy's rule set. All rules in a policy must share\nthe same domain (network or filesystem); mixing domains is rejected.\n\n**Network** actions: `connect:tcp`, `connect:udp`. Resources are\nhostnames (for example, `example.com`), wildcard subdomains (`*.example.com`\nfor one level, `**.example.com` for any depth), hostnames with an optional\nport (for example, `example.com:443`), or CIDRs in IPv4 or IPv6 notation\n(for example, `10.0.0.0/8` or `2001:db8::/32`).\n\n**Filesystem** actions: `read`, `write`. Resources are paths (for example,\n`/data`). Use `*` to match within a single path segment and `**` to match\nrecursively across segments (for example, `/data/**`).\n\nChanges may take up to five minutes to reach developer machines.\n", "operationId": "createRule", "requestBody": { "content": { "application/json": { "examples": { "filesystem": { "summary": "Filesystem rule", "value": { "actions": [ "read", "write" ], "decision": "allow", "name": "allow data directory", "resources": [ "/data" ] } }, "network": { "summary": "Network rule", "value": { "actions": [ "connect:tcp", "connect:udp" ], "decision": "allow", "name": "allow research mirrors", "resources": [ "research.mitre.org", "cve.mitre.org" ] } } }, "schema": { "$ref": "#/components/schemas/CreateRuleRequest" } } }, "description": "Rule definition including actions, resources, and decision.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "filesystem": { "summary": "Filesystem rule", "value": { "actions": [ "read", "write" ], "decision": "allow", "id": "rule_07fwtnr0kn2qetl1b9olfbyz8kob", "name": "allow data directory", "resources": [ "/data" ] } }, "network": { "summary": "Network rule", "value": { "actions": [ "connect:tcp", "connect:udp" ], "decision": "allow", "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna", "name": "allow research mirrors", "resources": [ "research.mitre.org", "cve.mitre.org" ] } } }, "schema": { "$ref": "#/components/schemas/Rule" } } }, "description": "Rule created and added to the policy's rule set." }, "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": "Create rule", "tags": [ "rules" ] } ``` ## Referenced schemas - `#/components/responses/Conflict` - `#/components/responses/Forbidden` - `#/components/responses/InternalError` - `#/components/responses/InvalidArgument` - `#/components/responses/NotFound` - `#/components/responses/Unauthenticated` - [#/components/schemas/CreateRuleRequest](/reference/api/ai-governance/latest/schemas/CreateRuleRequest/) - [#/components/schemas/Rule](/reference/api/ai-governance/latest/schemas/Rule/)