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

# Guardrails

> Manage organization-level guardrails that every agent must follow

Guardrails are organization-level rules — a name plus an optional description —
that every agent in the organization must follow on every response and tool
call. They are injected into each agent's system prompt at call start.

Guardrails apply to **all** agents in the organization; there is no per-agent
assignment and no feature gate.

## Limits

* Up to **5 guardrails per organization**. Creating a sixth returns
  `409 limit_reached`.
* `name`: 1–100 characters, unique within the organization.
* `description`: up to 1000 characters.

## Workflow

1. Create guardrails for an organization (e.g. "No PII — never reveal or
   confirm a caller's full account number, SSN, or payment card details").
2. Toggle `enabled` to pause a rule without deleting it — disabled guardrails
   stay listed but are not injected into the agent prompt.
3. Update or delete rules as policies change; changes take effect on the next
   call.

## Endpoints

| Endpoint                                                                                       | Purpose                                         |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [`GET /v1/organizations/{organization_id}/guardrails`](/api-reference/guardrails/list-create)  | List guardrails                                 |
| [`POST /v1/organizations/{organization_id}/guardrails`](/api-reference/guardrails/list-create) | Create a guardrail                              |
| [`PATCH /v1/guardrails/{guardrailId}`](/api-reference/guardrails/update-delete)                | Update a guardrail (name, description, enabled) |
| [`DELETE /v1/guardrails/{guardrailId}`](/api-reference/guardrails/update-delete)               | Delete a guardrail                              |

The API exposes exactly the same guardrail fields you manage in the dashboard —
nothing more. There are no internal or secret fields on a guardrail.

## Guardrail object

`GET` and `POST` return the full guardrail object (inside a `data` wrapper);
`PATCH` and `DELETE` return `{ "success": true }`.

| Field             | Type              | Description                                                           |
| ----------------- | ----------------- | --------------------------------------------------------------------- |
| `id`              | string (UUID)     | Guardrail identifier.                                                 |
| `organization_id` | string (UUID)     | Organization the guardrail belongs to.                                |
| `name`            | string            | Rule name, 1–100 characters, unique within the organization.          |
| `description`     | string \| null    | Optional rule text, up to 1000 characters.                            |
| `enabled`         | boolean           | Whether the rule is injected into agent prompts (defaults to `true`). |
| `created_at`      | string (ISO 8601) | When the guardrail was created.                                       |
| `updated_at`      | string (ISO 8601) | When the guardrail was last updated.                                  |

## Errors

Errors use one of two JSON shapes with the matching HTTP status:

* Request-schema failures return `{ "error": "Invalid request data", "details": [...] }`
  (`400`), where `details` is the list of failed field validations.
* All other errors return `{ "error": "<code>", "error_description": "<message>" }`.

| Status | `error` code           | When                                                                                                                                                          |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `Invalid request data` | Missing/too-long `name`, too-long `description`, an unknown field, or (on `PATCH`) an empty body.                                                             |
| `400`  | `invalid_request`      | Body was not valid JSON, or `name` was only whitespace.                                                                                                       |
| `404`  | `not_found`            | The guardrail or organization does not exist, or the caller can't access it. A foreign but existing id returns the same `404` — there is no existence oracle. |
| `409`  | `conflict`             | A guardrail with that `name` already exists in the organization.                                                                                              |
| `409`  | `limit_reached`        | The organization already has the maximum of 5 guardrails.                                                                                                     |