---
title: "Add a new policy"
method: POST
path: "/policies"
tags: ["Policies"]
---

# Add a new policy

`POST /policies`

Adds a new policy bundle to the system

## Headers

- `x-anchore-account` string

## Request body

- PolicyBundle — A bundle containing a set of policies, whitelists, and rules for mapping them to specific images
  - `id` string, required — Id of the bundle
  - `name` string — Human readable name for the bundle
  - `comment` string — Description of the bundle, human readable
  - `version` string, required — Version id for this bundle format
  - `whitelists` Whitelist[] — Whitelists which define which policy matches to disregard explicitly in the final policy decision
    - `id` string, required
    - `name` string
    - `version` string, required
    - `comment` string
    - `items` WhitelistItem[]
      - `id` string
      - `gate` string, required
      - `trigger_id` string, required
      - `expires_on` string, date-time
  - `policies` Policy[], required — Policies which define the go/stop/warn status of an image using rule matches on image properties
    - `id` string, required
    - `name` string
    - `comment` string
    - `version` string, required
    - `rules` PolicyRule[]
      - `id` string
      - `gate` string, required
      - `trigger` string, required
      - `action` 'GO' | 'STOP' | 'WARN', required
      - `params` PolicyRuleParamsInner[]
        - `name` string, required
        - `value` string, required
  - `mappings` MappingRule[], required — Mapping rules for defining which policy and whitelist(s) to apply to an image based on a match of the image tag or id. Evaluated in order.
    - `id` string
    - `name` string, required
    - `whitelist_ids` string[]
    - `policy_id` string — Optional single policy to evalute, if set will override any value in policy_ids, for backwards compatibility. Generally, policy_ids should be used even with a array of length 1.
    - `policy_ids` string[] — List of policyIds to evaluate in order, to completion
    - `registry` string, required
    - `repository` string, required
    - `image` ImageRef, required — A reference to an image
      - `type` 'tag' | 'digest' | 'id', required
      - `value` string, required
  - `whitelisted_images` ImageSelectionRule[] — List of mapping rules that define which images should always be passed (unless also on the blacklist), regardless of policy result.
    - `id` string
    - `name` string, required
    - `registry` string, required
    - `repository` string, required
    - `image` ImageRef, required — A reference to an image
      - `type` 'tag' | 'digest' | 'id', required
      - `value` string, required
  - `blacklisted_images` ImageSelectionRule[] — List of mapping rules that define which images should always result in a STOP/FAIL policy result regardless of policy content or presence in whitelisted_images
    - `id` string
    - `name` string, required
    - `registry` string, required
    - `repository` string, required
    - `image` ImageRef, required — A reference to an image
      - `type` 'tag' | 'digest' | 'id', required
      - `value` string, required

## Response `200`

Saved bundle

- PolicyBundleRecord — A policy bundle plus some metadata
  - `created_at` string, date-time
  - `last_updated` string, date-time
  - `policyId` string — The bundle's identifier
  - `active` boolean — True if the bundle is currently defined to be used automatically
  - `userId` string — UserId of the user that owns the bundle
  - `policy_source` string — Source location of where the policy bundle originated
  - `policybundle` PolicyBundle — A bundle containing a set of policies, whitelists, and rules for mapping them to specific images
    - `id` string, required — Id of the bundle
    - `name` string — Human readable name for the bundle
    - `comment` string — Description of the bundle, human readable
    - `version` string, required — Version id for this bundle format
    - `whitelists` Whitelist[] — Whitelists which define which policy matches to disregard explicitly in the final policy decision
      - `id` string, required
      - `name` string
      - `version` string, required
      - `comment` string
      - `items` WhitelistItem[]
        - `id` string
        - `gate` string, required
        - `trigger_id` string, required
        - `expires_on` string, date-time
    - `policies` Policy[], required — Policies which define the go/stop/warn status of an image using rule matches on image properties
      - `id` string, required
      - `name` string
      - `comment` string
      - `version` string, required
      - `rules` PolicyRule[]
        - `id` string
        - `gate` string, required
        - `trigger` string, required
        - `action` 'GO' | 'STOP' | 'WARN', required
        - `params` PolicyRuleParamsInner[]
          - `name` string, required
          - `value` string, required
    - `mappings` MappingRule[], required — Mapping rules for defining which policy and whitelist(s) to apply to an image based on a match of the image tag or id. Evaluated in order.
      - `id` string
      - `name` string, required
      - `whitelist_ids` string[]
      - `policy_id` string — Optional single policy to evalute, if set will override any value in policy_ids, for backwards compatibility. Generally, policy_ids should be used even with a array of length 1.
      - `policy_ids` string[] — List of policyIds to evaluate in order, to completion
      - `registry` string, required
      - `repository` string, required
      - `image` ImageRef, required — A reference to an image
        - `type` 'tag' | 'digest' | 'id', required
        - `value` string, required
    - `whitelisted_images` ImageSelectionRule[] — List of mapping rules that define which images should always be passed (unless also on the blacklist), regardless of policy result.
      - `id` string
      - `name` string, required
      - `registry` string, required
      - `repository` string, required
      - `image` ImageRef, required — A reference to an image
        - `type` 'tag' | 'digest' | 'id', required
        - `value` string, required
    - `blacklisted_images` ImageSelectionRule[] — List of mapping rules that define which images should always result in a STOP/FAIL policy result regardless of policy content or presence in whitelisted_images
      - `id` string
      - `name` string, required
      - `registry` string, required
      - `repository` string, required
      - `image` ImageRef, required — A reference to an image
        - `type` 'tag' | 'digest' | 'id', required
        - `value` string, required

## Other responses

- `500` — Internal Error

## Changes

- **2026-07-17** `38e5705e0b21` — 2 breaking, 2 info
  - the `policies/items/rules/items/params/items/` request property type/format changed from ``/`` to `object`/``
  - the `policybundle/policies/items/rules/items/params/items/` response's property type/format changed from ``/`` to `object`/`` for status `200`
  - added the new optional request property `whitelists/items/items/items/expires_on`
  - added the optional property `policybundle/whitelists/items/items/items/expires_on` to the response with the `200` status
- **2019-10-02** `75f483ab10a0` — 2 breaking, 2 warning
  - the `policies/items/rules/items/params/items/` request property type/format changed from `object`/`` to ``/``
  - the `policybundle/policies/items/rules/items/params/items/` response's property type/format changed from `object`/`` to ``/`` for status `200`
  - removed the request property `whitelists/items/items/items/expires_on`
  - removed the optional property `policybundle/whitelists/items/items/items/expires_on` from the response with the `200` status

[Change history](https://skmtc.dev/banzaicloud/apis/anchore-engine-api-server/changes/policies/post.md)

---

[API](https://skmtc.dev/banzaicloud/apis/anchore-engine-api-server.md) · [All operations](https://skmtc.dev/banzaicloud/apis/anchore-engine-api-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/banzaicloud/anchore-engine-api-server/revisions/38e5705e0b21/schema)