Add a guardrail
Adds a check the instance runs on model and tool requests. It runs on every request when always_on, and otherwise on the requests that name it in guardrails. The instance must be ready; otherwise the request answers 409.
curl --request POST \
--url https://api.telnyx.com/v2/agent_gateways/{instance_id}/guardrails \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "mask-pii",
"modes": [
"before_request"
],
"type": "content_filter",
"settings": {
"patterns": [
{
"name": "us_ssn",
"action": "mask"
},
{
"name": "email",
"action": "mask"
}
]
}
}
'{
"data": {
"id": "9645e556-6532-4341-8cab-21b58cdef529",
"name": "mask-pii",
"modes": [
"before_request"
],
"always_on": false,
"type": "content_filter",
"settings": {
"patterns": [
{
"name": "us_ssn",
"action": "mask"
},
{
"name": "email",
"action": "mask"
}
],
"regexes": [],
"keywords": [],
"categories": []
},
"created_at": "2026-10-28T17:07:48.905000Z",
"updated_at": "2026-10-28T17:07:48.905000Z"
}
}{
"errors": [
{
"code": "10012",
"title": "Duplicate resource",
"detail": "Resource is a duplicate.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10012"
},
"source": {
"pointer": "/name"
}
}
]
}{
"errors": [
{
"code": "10009",
"title": "Authentication failed",
"detail": "The required authentication headers were either invalid or not included in the request.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10009"
}
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "The requested resource or URL could not be found.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10005"
}
}
]
}{
"errors": [
{
"code": "99901",
"title": "Instance not ready",
"detail": "The instance is not ready; its engine is not running."
}
]
}{
"errors": [
{
"code": "10027",
"title": "Unprocessable Entity",
"detail": "The type does not run in one of these modes.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10027"
},
"source": {
"pointer": "/modes"
}
}
]
}{
"errors": [
{
"code": "99903",
"title": "Engine unavailable",
"detail": "The instance's engine did not answer; try again shortly."
}
]
}Authorizations
Telnyx API key
Path Parameters
The Agent Gateway's id.
Body
A name, unique on the instance. A request names it in its guardrails field.
^[A-Za-z0-9_.-]{1,100}$When the guardrail runs. Each type runs in some modes only.
1before_request, during_request, after_request, logging_only, before_tool_request, during_tool_request, after_tool_request The kind of check. It cannot change after create.
content_filter, tool_permission, model_judge, custom_code, lakera, presidio, bedrock, azure_content_safety true runs the guardrail on every request, and a request cannot turn it off. false runs it on the requests that name it.
The type's settings. content_filter: patterns (prebuilt patterns by name, such as us_ssn or email), regexes (each a name, which tags masked matches, and a pattern), keywords (each a keyword), and categories (each a name), each entry with an action of block or mask. tool_permission: rules (id, tool_name, tool_type, decision, argument_patterns), a default decision, and on_denied (block or rewrite). model_judge: a model on the instance and weighted criteria (name, description, weight, the weights summing to 100). custom_code: code defining apply_guardrail(inputs, request_data, input_type). lakera: api_key, project_id, api_base. presidio: analyzer_url, anonymizer_url, entities (entity name to block or mask), language. bedrock: guardrail_id, version, region, and access_key_id with secret_access_key, or role_name. azure_content_safety: api_key, endpoint, severity (0 to 7). Provider secrets are write-only.
Response
The added guardrail
Show child attributes
Show child attributes
Was this page helpful?
curl --request POST \
--url https://api.telnyx.com/v2/agent_gateways/{instance_id}/guardrails \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "mask-pii",
"modes": [
"before_request"
],
"type": "content_filter",
"settings": {
"patterns": [
{
"name": "us_ssn",
"action": "mask"
},
{
"name": "email",
"action": "mask"
}
]
}
}
'{
"data": {
"id": "9645e556-6532-4341-8cab-21b58cdef529",
"name": "mask-pii",
"modes": [
"before_request"
],
"always_on": false,
"type": "content_filter",
"settings": {
"patterns": [
{
"name": "us_ssn",
"action": "mask"
},
{
"name": "email",
"action": "mask"
}
],
"regexes": [],
"keywords": [],
"categories": []
},
"created_at": "2026-10-28T17:07:48.905000Z",
"updated_at": "2026-10-28T17:07:48.905000Z"
}
}{
"errors": [
{
"code": "10012",
"title": "Duplicate resource",
"detail": "Resource is a duplicate.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10012"
},
"source": {
"pointer": "/name"
}
}
]
}{
"errors": [
{
"code": "10009",
"title": "Authentication failed",
"detail": "The required authentication headers were either invalid or not included in the request.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10009"
}
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "The requested resource or URL could not be found.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10005"
}
}
]
}{
"errors": [
{
"code": "99901",
"title": "Instance not ready",
"detail": "The instance is not ready; its engine is not running."
}
]
}{
"errors": [
{
"code": "10027",
"title": "Unprocessable Entity",
"detail": "The type does not run in one of these modes.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10027"
},
"source": {
"pointer": "/modes"
}
}
]
}{
"errors": [
{
"code": "99903",
"title": "Engine unavailable",
"detail": "The instance's engine did not answer; try again shortly."
}
]
}