---
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` object[]
        - `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` object[]
          - `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

---

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