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

# Update Guardrail

> Changes the fields you send. The change applies to every agent using the guardrail.



## OpenAPI

````yaml /api-reference/openapi.json patch /v2/voice-agents/guardrails/{guardrailId}
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/guardrails/{guardrailId}:
    patch:
      summary: Update a guardrail
      description: >-
        Changes the fields you send. The change applies to every agent using the
        guardrail.
      parameters:
        - in: path
          name: guardrailId
          required: true
          description: ID of the guardrail.
          schema:
            type: string
            format: uuid
            example: 6e2b9c41-7d3a-4f58-9b12-c4d5e6f70812
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Rule name (1-255 characters), unique in the project.
                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.
                conditionsMatch:
                  type: string
                  enum:
                    - ALL
                    - ANY
                  description: >-
                    `ALL`: every condition must hold. `ANY`: at least one must
                    hold. Omitted: keeps the saved value.
                conditions:
                  type: array
                  items:
                    $ref: '#/components/schemas/PolicyCondition'
                  description: >-
                    Call variables that must hold for the rule to apply. Empty:
                    applies on every call.
                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.
                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'
                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.
                    Omitted: keeps the saved value.
                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`.
                instructions:
                  type: string
                  minLength: 1
                  maxLength: 100000
                  description: >-
                    The instruction added to the model's instructions while the
                    rule applies (1-100,000 characters).
                notes:
                  type: string
                  maxLength: 255
                  nullable: true
                  description: Your own notes. Not used on calls.
                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. Omitted: keeps the saved value.
              description: >-
                Send at least one field. Fields you leave out keep their value.
                `checksIn` and `callerAgentCheck` must still agree after the
                change.
            examples:
              some_fields:
                summary: Change some fields
                value:
                  severity: CRITICAL
                  notes: null
              mode:
                summary: Switch to enforce
                value:
                  mode: ENFORCE
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/Guardrail'
        '400':
          description: >-
            Invalid body, or no field to update (`DirectiveUpdateNeedsAField`),
            or `appliesIn: EVERY_TURN` while the saved `matchingExamples` are
            not empty (`DirectiveMatchingExamplesOnlyPerUserResponse`: send
            `matchingExamples: null` in the same request), `callerAgentCheck`
            that does not match `checksIn`, a missing or invalid `lookForValue`
            / `behaviourValue`, or a `FUNCTION` / `MACRO` ID that is not a
            function or macro of this project of the right type and use
            (`GuardrailFunctionMacroNotFound`,
            `GuardrailFunctionMacroTypeMismatch`,
            `GuardrailFunctionMacroUsedAsMismatch`).
          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:update`
            permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Guardrail not found in this project (`GuardrailNotFound`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '409':
          description: >-
            Another guardrail in the project has this name
            (`DirectiveNameAlreadyExists`).
          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:
    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.
    Guardrail:
      type: object
      description: >-
        A check on what the caller or the agent says, with an action when it
        matches.
      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'
    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
  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.