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

# Set Agent Policies

> Replaces the agent's policies with this list. New ones start active, ones already assigned keep their switch, ones left out are removed. An empty list removes all. The change is saved in your own draft, like Update Voice Agent: a test call of the draft uses it, and callers get it when the draft is published. Only active ones reach calls. Editing a policy itself still applies to every agent right away.



## OpenAPI

````yaml /api-reference/openapi.json put /v2/voice-agents/{voiceAgentId}/policies
openapi: 3.0.1
info:
  title: Hamsa API
  description: >-
    The Hamsa API: voice agents and their calls, phone numbers, batch calls and
    knowledge bases; speech to text, text to speech, voices and AI content.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v2/voice-agents/{voiceAgentId}/policies:
    put:
      summary: Set an agent's policies
      description: >-
        Replaces the agent's policies with this list. New ones start active,
        ones already assigned keep their switch, ones left out are removed. An
        empty list removes all. The change is saved in your own draft, like
        Update Voice Agent: a test call of the draft uses it, and callers get it
        when the draft is published. Only active ones reach calls. Editing a
        policy itself still applies to every agent right away.
      parameters:
        - in: path
          name: voiceAgentId
          required: true
          description: ID of the voice agent.
          schema:
            type: string
            format: uuid
            example: 3f6c8a1e-2b4d-4e7f-9a0b-1c2d3e4f5a6b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - policyIds
              properties:
                policyIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: >-
                    IDs of the project's policies the agent should have. Empty:
                    remove all.
            examples:
              set:
                summary: Assign policies
                value:
                  policyIds:
                    - a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f601
                    - c4d5e6f7-0819-4a2b-8c3d-4e5f60718293
              clear:
                summary: Remove all
                value:
                  policyIds: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PolicyAssignment'
        '400':
          description: Invalid body, for example an ID that is not a UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '401':
          description: 'Unauthorized: missing or invalid API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '403':
          description: Your API key or role does not have the `policies:assign` permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: >-
            Voice agent not found (`VoiceAgentDoesNotExist`), or an ID is not a
            policy of this project (`DirectiveNotInProject`): nothing is
            changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    PolicyAssignment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: a3f1c2d4-5b6e-4f70-8a91-b2c3d4e5f601
        projectId:
          type: string
          format: uuid
          example: fbb9e8b2-2dbb-40f9-a051-9404624e3247
        userId:
          type: string
          nullable: true
          example: b7d9e979-4a16-437b-8571-4ed92a94faa8
        createdBy:
          type: string
          description: ID of the member who created it.
          example: b7d9e979-4a16-437b-8571-4ed92a94faa8
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Unique among the project's policies (not case-sensitive).
          example: Refund policy
        appliesIn:
          type: string
          enum:
            - EVERY_TURN
            - PER_USER_RESPONSE
          description: >-
            `EVERY_TURN`: applies on every turn of the call.
            `PER_USER_RESPONSE`: applies only when what the caller says matches
            the rule, found by meaning (the name, `instructions` and
            `matchingExamples` are searched), so the exact words don't matter.
          example: PER_USER_RESPONSE
        conditionsMatch:
          type: string
          enum:
            - ALL
            - ANY
          description: '`ALL`: every condition must hold. `ANY`: at least one must hold.'
          example: ALL
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/PolicyCondition'
          description: >-
            Call variables that must hold for the rule to apply. Empty: applies
            on every call.
          example:
            - variable: customer_tier
              condition: equals
              value: gold
        matchingExamples:
          type: string
          maxLength: 5000
          nullable: true
          description: >-
            What a caller might say, in any language, to help the search find
            this rule. Only allowed with `appliesIn: PER_USER_RESPONSE`.
          example: I want my money back. Can I get a refund?
        instructions:
          type: string
          minLength: 1
          maxLength: 100000
          description: >-
            The instruction added to the model's instructions while the rule
            applies (1-100,000 characters).
          example: >-
            Refunds are offered only within 14 days of purchase. Never promise a
            refund outside that window.
        notes:
          type: string
          maxLength: 255
          nullable: true
          description: Your own notes. Not used on calls.
          example: Reviewed by legal
        severity:
          type: string
          enum:
            - NORMAL
            - HIGH
            - CRITICAL
          description: >-
            How important the rule is. `CRITICAL` rules are placed closest to
            the model's reply and are flagged first in call review.
          example: HIGH
        status:
          type: string
          nullable: true
          enum:
            - PROCESSING
            - PROCESSED
            - INGESTION_FAILURE
          description: >-
            Search index state, for `PER_USER_RESPONSE` rules: `PROCESSING`,
            then `PROCESSED` (searchable) or `INGESTION_FAILURE` (see
            `failureReason`; save the rule again to retry). `null` for
            `EVERY_TURN` rules, which are never indexed.
          example: PROCESSED
        failureReason:
          type: string
          nullable: true
          description: Why indexing failed. `null` otherwise.
          example: null
        createdAt:
          type: string
          format: date-time
          example: '2026-10-20T09:15:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-10-20T09:15:00.000Z'
        isActive:
          type: boolean
          description: >-
            This agent's on/off switch. Only active ones reach the agent's
            calls.
          example: true
    ErrorSchema:
      type: object
      properties:
        code:
          type: integer
          description: >-
            Service error code: the HTTP status with a service prefix (for
            example `8404`). Missing when the service has no code for that
            status.
          example: 8404
        message:
          type: string
          description: >-
            What went wrong. Some services (calls and recordings) put the error
            key here, for example `CallNotFoundOrUnavailable`, and send no
            `messageKey`.
          example: Policy not found!
        messageKey:
          type: string
          description: >-
            Stable key for the error, safe to match on in code. Not returned by
            every service.
          example: PolicyNotFound
        params:
          type: object
          additionalProperties: true
          description: >-
            Details for some errors (for example `reason`). Not returned by
            every service.
          example:
            reason: NO_DRAFT
    PolicyCondition:
      type: object
      required:
        - variable
        - condition
        - value
      description: A test on one call variable (policies and guardrails).
      properties:
        variable:
          type: string
          minLength: 1
          maxLength: 100
          description: >-
            Name of the call variable, as written in `{{name}}`: letters, digits
            and `_`, not starting with a digit, not a word like `true`, `none`
            or `and`.
          example: customer_tier
        condition:
          type: string
          enum:
            - equals
            - is_not
            - contains
            - does_not_contain
            - is_more_than
            - is_less_than
            - is_set
            - is_not_set
          description: How the variable is compared with `value`.
          example: equals
        value:
          type: string
          minLength: 1
          maxLength: 1000
          description: >-
            The value to compare with (1-1,000 characters). Required for every
            condition.
          example: gold
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.