Sign in

v1

latestOpenAPI 3.0.32026-07-267015229.9 KB
Guardrails

Create Guardrails

Create a new guardrail. Guardrails provide strict behavioral boundaries that are enforced throughout a conversation.

Attach guardrails to a PAL directly via guardrail_ids or by tag via guardrail_tags on Create PAL.

<Note> See [Deprecated guardrail sets](/api-reference/guardrails/legacy-guardrail-sets). </Note>
post/v2/guardrails

Request body

guardrail_namestring required

A descriptive name for the guardrail. Only alphanumeric characters and underscores are allowed. Maximum 100 characters.

guardrail_promptstring required

The detailed prompt that defines the behavioral boundaries and restrictions. Keep this short and direct for best enforcement. Maximum 1,000 characters.

modality'verbal' | 'visual'

The communication modality for the guardrail. If set to verbal, the guardrail is enforced against the participant's spoken/typed responses. If set to visual, the guardrail is enforced against visual/perception cues observed by Raven.

callback_urlstring

Optional URL that will receive a notification when the guardrail is triggered during a conversation. Maximum 2,048 characters.

tagsstring[]

Optional tags for organizing guardrails and for attaching them to PALs in bulk via guardrail_tags on Create PAL. Up to 32 tags per guardrail. Tag names are limited to 64 characters.

app_messageboolean

Whether triggering this guardrail emits a real-time app-message event on the conversation. Default true. Set to false to suppress the in-conversation event for guardrails you only want to observe server-side via callback_url.

Example request

{
  "guardrail_name": "healthcare_compliance_guardrail",
  "guardrail_prompt": "Never discuss competitor products, share sensitive medical information, or provide medical advice outside approved guidelines.",
  "modality": "verbal",
  "callback_url": "https://your-server.com/guardrails-webhook",
  "tags": [
    "compliance",
    "healthcare"
  ],
  "app_message": true
}

Response

Guardrail created successfully

uuidstring

Unique identifier for the created guardrail. Use this value in guardrail_ids on a PAL.

guardrail_namestring
guardrail_promptstring
modality'verbal' | 'visual'
callback_urlstring
tagsstring[]
app_messageboolean

Whether triggering this guardrail emits a real-time app-message event on the conversation.

created_atstring
updated_atstring

Example response

{
  "uuid": "g1234567890ab",
  "guardrail_name": "healthcare_compliance_guardrail",
  "guardrail_prompt": "Never share sensitive medical information or provide medical advice outside approved guidelines.",
  "modality": "verbal",
  "callback_url": "https://your-server.com/guardrails-webhook",
  "tags": [
    "compliance",
    "healthcare"
  ],
  "app_message": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}