> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roe-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Policy

> List all policies and create a new policy

Create a new policy with an initial version. The initial version is automatically set as the current version.

## Query Parameters

| Parameter         | Type | Required | Description                                      |
| ----------------- | ---- | -------- | ------------------------------------------------ |
| `organization_id` | uuid | Yes      | UUID of the organization to create the policy in |

## Request Body

| Field          | Type   | Required | Description                                         |
| -------------- | ------ | -------- | --------------------------------------------------- |
| `name`         | string | Yes      | Name of the policy (max 255 characters)             |
| `description`  | string | No       | Description of the policy                           |
| `content`      | object | Yes      | Policy content structure (see below)                |
| `version_name` | string | No       | Name for the initial version (default: "version 1") |

### Content Object

The `content` field accepts a JSON object with the following optional sections:

| Field              | Type   | Description                                                  |
| ------------------ | ------ | ------------------------------------------------------------ |
| `guidelines`       | object | Hierarchical structure with categories, rules, and sub-rules |
| `instructions`     | string | Free-form text instructions for the agent                    |
| `dispositions`     | object | Classification options for agent outputs                     |
| `summary_template` | object | Handlebars-style template for generating summaries           |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.roe-ai.com/v1/policies/?organization_id=YOUR_ORG_ID" \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "Compliance Review Policy",
      "description": "Policy for reviewing documents against compliance requirements",
      "content": {
        "guidelines": {
          "categories": [
            {
              "title": "Document Verification",
              "rules": [
                {
                  "title": "Check all signatures",
                  "flag": "RED_FLAG"
                }
              ]
            }
          ]
        },
        "instructions": "Review all documents carefully."
      },
      "version_name": "version 1"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Compliance Review Policy",
    "description": "Policy for reviewing documents against compliance requirements",
    "organization_id": "org-12345678-1234-1234-1234-123456789012",
    "current_version_id": "456e7890-e89b-12d3-a456-426614174001",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
  ```

  ```json 400 Missing required fields theme={null}
  {
    "name": ["This field is required."],
    "content": ["This field is required."]
  }
  ```

  ```json 400 Invalid content structure theme={null}
  {
    "content": ["Invalid new format content: guidelines.categories[0].title must be a non-empty string"]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /policies/
openapi: 3.1.0
info:
  title: Roe AI API
  version: 1.0.0
  description: Complete API documentation for Roe AI platform
servers:
  - url: https://api.roe-ai.com
    description: Production API
security: []
paths:
  /policies/:
    post:
      tags:
        - policies
      description: List all policies and create a new policy
      operationId: policies_create
      parameters:
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: >-
            Organization ID. This is required for access control. It can be
            provided via query or request body depending on the endpoint.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePolicyRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePolicy'
          description: ''
      security:
        - jwtAuth: []
components:
  schemas:
    CreatePolicyRequest:
      type: object
      description: Serializer for creating a new policy with initial version
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
        content:
          writeOnly: true
          description: Content for the initial policy version
        version_name:
          type: string
          writeOnly: true
          minLength: 1
          default: version 1
          description: Name for the initial version (defaults to 'version 1')
          maxLength: 255
      required:
        - content
        - name
    CreatePolicy:
      type: object
      description: Serializer for creating a new policy with initial version
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 255
        description:
          type: string
        organization_id:
          type: string
          format: uuid
          readOnly: true
        current_version_id:
          type:
            - string
            - 'null'
          format: uuid
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      required:
        - created_at
        - current_version_id
        - id
        - name
        - organization_id
        - updated_at
  securitySchemes:
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````