---
title: "Create the next immutable draft version"
method: POST
path: "/v1/policies"
tags: ["Policies"]
---

# Create the next immutable draft version

`POST /v1/policies`

## Request

- Base URL: `https://api.thrd.email`
- URL: `https://api.thrd.email/v1/policies`
- Auth: HTTP bearer

Requires bearer scope policies:manage. Tenant and environment come only from server auth context.

## Request body

- object
  - `name` string, required
  - `description` string
  - `document` union, required
    - object
      - `version` '1.0', required
      - `name` string, required
      - `defaults` object, required
        - `unknownAction` 'review', required
        - `evaluationError` 'review', required
        - `criticalEvaluationError` 'deny', required
      - `rules` object[], required
    - string: Bounded YAML or JSON source. YAML snake_case defaults and reason_codes are normalized.

## Response `201`

Immutable draft created

- object
  - `policy` object, required
    - `id` string, uuid, required
    - `tenantId` string, uuid, required
    - `environment` 'development' | 'staging' | 'production', required
    - `name` string, required
    - `description` string, nullable, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `version` object, required
    - `id` string, uuid, required
    - `tenantId` string, uuid, required
    - `environment` 'development' | 'staging' | 'production', required
    - `policyId` string, uuid, required
    - `version` integer, required
    - `status` 'draft' | 'active' | 'retired', required
    - `policyHash` string, required
    - `engineVersion` string, required
    - `documentJson` object, required
    - `createdAt` string, date-time, required
    - `activatedAt` string, date-time, nullable, required
    - `retiredAt` string, date-time, nullable, required

## Other responses

- `400`: Invalid bounded policy document
- `403`: Missing policies:manage scope

---

[API](https://skmtc.dev/thrd/apis/thrd-agent-email-api.md) · [All operations](https://skmtc.dev/thrd/apis/thrd-agent-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thrd/apis/thrd-agent-email-api/revisions/d8a88129cd34?raw)