> ## 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 Guardrails

> Replaces the agent's guardrails 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 guardrail itself still applies to every agent right away.



## OpenAPI

````yaml /api-reference/openapi.json put /v2/voice-agents/{voiceAgentId}/guardrails
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}/guardrails:
    put:
      summary: Set an agent's guardrails
      description: >-
        Replaces the agent's guardrails 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
        guardrail 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:
                - guardrailIds
              properties:
                guardrailIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: >-
                    IDs of the project's guardrails the agent should have.
                    Empty: remove all.
            examples:
              set:
                summary: Assign guardrails
                value:
                  guardrailIds:
                    - 6e2b9c41-7d3a-4f58-9b12-c4d5e6f70812
                    - 8f9a0b1c-2d3e-4f50-8617-2839a4b5c6d7
              clear:
                summary: Remove all
                value:
                  guardrailIds: []
      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/GuardrailAssignment'
        '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 `guardrails:assign`
            permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: >-
            Voice agent not found (`VoiceAgentDoesNotExist`), or an ID is not a
            guardrail 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:
    GuardrailAssignment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 6e2b9c41-7d3a-4f58-9b12-c4d5e6f70812
        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 guardrails (not case-sensitive).
          example: No passwords
        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: EVERY_TURN
        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: channel
              condition: is_not
              value: internal
        checksIn:
          type: string
          enum:
            - CALLER_SAYS
            - AGENT_SAYS
            - BOTH
          description: >-
            Whose words the guardrail checks: the caller's (`CALLER_SAYS`), the
            agent's replies (`AGENT_SAYS`) or both. It decides which keys
            `callerAgentCheck` must have.
          example: CALLER_SAYS
        callerAgentCheck:
          type: object
          additionalProperties: false
          description: >-
            What to look for and what to do, per side. Send `caller` for
            `CALLER_SAYS`, `agent` for `AGENT_SAYS`, both for `BOTH`, and no
            other key. On update it replaces the whole object.
          properties:
            caller:
              $ref: '#/components/schemas/GuardrailCheck'
            agent:
              $ref: '#/components/schemas/GuardrailCheck'
          example:
            caller:
              lookFor: PATTERN
              lookForValue: \b(password|pin)\b
              behaviour: MESSAGE
              behaviourValue: I can't take passwords over the phone.
        mode:
          type: string
          enum:
            - MONITOR
            - ENFORCE
          description: >-
            `MONITOR`: records when the guardrail would fire and changes nothing
            on the call. `ENFORCE`: acts on the call whenever it fires. Start in
            `MONITOR` to see when it would fire.
          example: ENFORCE
        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: null
        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: Never ask for or repeat a password or PIN.
        notes:
          type: string
          maxLength: 255
          nullable: true
          description: Your own notes. Not used on calls.
          example: null
        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: CRITICAL
        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: null
        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
    GuardrailCheck:
      type: object
      required:
        - lookFor
        - behaviour
      additionalProperties: false
      description: 'One side of a guardrail: how a hit is found and what happens then.'
      properties:
        lookFor:
          type: string
          enum:
            - NONE
            - WORDS
            - PATTERN
            - FUNCTION
            - MACRO
          description: >-
            `NONE`: no check on this side (the instructions still apply).
            `WORDS`: any of the words or phrases in `lookForValue`. `PATTERN`:
            the regular expression in `lookForValue`. `FUNCTION` / `MACRO`: the
            function or macro whose ID is in `lookForValue` (a
            `JAVASCRIPT_FUNCTION` or `JINJA_MACRO` used as `CHECK`).
          example: PATTERN
        lookForValue:
          type: string
          maxLength: 5000
          nullable: true
          description: >-
            Required for `WORDS` (one word or phrase per line), `PATTERN` (a
            valid regular expression), `FUNCTION` and `MACRO` (an ID). Leave out
            for `NONE`.
          example: \b(password|pin)\b
        behaviour:
          type: string
          enum:
            - NOTHING
            - MESSAGE
            - DISCONNECT
            - FUNCTION
            - MACRO
          description: >-
            What happens on a hit (in `ENFORCE` mode). `NOTHING`: no action.
            `MESSAGE`: say the line in `behaviourValue`. `DISCONNECT`: say the
            optional goodbye line in `behaviourValue`, then hang up. `FUNCTION`
            / `MACRO`: run the function or macro whose ID is in `behaviourValue`
            (used as `ACTION`) the text it returns replaces what the caller said
            (caller side, before the agent answers) or the agent's sentence
            (agent side, before it is spoken), and an object it returns sets
            variables; the call carries on.
          example: MESSAGE
        behaviourValue:
          type: string
          maxLength: 5000
          nullable: true
          description: >-
            Required for `MESSAGE` (the line), `FUNCTION` and `MACRO` (an ID).
            Optional for `DISCONNECT` (a goodbye line). Leave out for `NOTHING`.
          example: I can't take passwords over the phone.
  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.