Guardrails API

Configure product-scoped AI guardrails for catalog products. Guardrail details are stored as a one-to-one extension row on a data product and are surfaced in Product Details for products of type Guardrail.

All endpoints are mounted under /api/v1.0. Paths below omit that global prefix for readability.

Base Path

/catalog/spaces/{space_slug}/products/{product_id}/guardrail/

Endpoints

Method	Endpoint	Description
GET	/catalog/spaces/{space_slug}/products/{product_id}/guardrail/	Read guardrail details for a product.
PUT	/catalog/spaces/{space_slug}/products/{product_id}/guardrail/	Upsert guardrail details for a product.

Product Scope And Permissions

The API first resolves {space_slug} and verifies that {product_id} belongs to that space.

• GET requires view permission on the product.
• PUT requires edit permission on the product.
• A missing product or space mismatch returns 404 Product not found.
• GET returns 404 Guardrail details not found when the product has no guardrail configuration yet.
• PUT updates the existing guardrail row or creates one when none exists.

The dedicated Guardrails API reads and writes the same guardrail_details object that can be embedded in catalog product create/update payloads. Product responses include guardrail_details when the relationship is loaded.

Runtime Relationship

Product guardrails are applied by runtime AI guardrail enforcement when a product is part of the current Copilot page context, retrieved source set, or tool-discovered source and the user can view that product.

Runtime enforcement currently consumes these fields:

• rule_type
• enforcement_mode
• topics_blocked
• topics_allowed
• regex_patterns
• pii_detection_enabled
• pii_categories
• toxicity_threshold
• max_token_limit
• fallback_response

Other fields are stored and returned as governance or monitoring metadata for the product guardrail record.

Guardrail Fields

Field	Type	Default	Description
rule_type	string	both	Direction for checks. Allowed values: input_filter, output_filter, both.
enforcement_mode	string	block	Enforcement action. Allowed values: block, warn, log.
topics_blocked	string[]	[]	Case-insensitive topic substrings that should trigger blocked_topic.
topics_allowed	string[]	[]	Allowlist topic substrings. If configured and none match, runtime triggers outside_allowed_topics.
regex_patterns	string[]	[]	Custom case-insensitive regex patterns. Limited to 10 patterns, 256 characters each.
pii_detection_enabled	boolean	false	Enables built-in PII detection.
pii_categories	string[]	[]	Server-accepted values: email, ssn, credit_card, phone. Empty means all built-in categories.
toxicity_threshold	number | null	null	Enables current toxicity checks when set. Must be between 0.0 and 1.0.
max_token_limit	integer | null	null	Approximate token limit for matching input/output text. Must be 1 through 8000.
fallback_response	string | null	null	Response returned when a blocking guardrail fires. Maximum 1000 characters.
alert_on_trigger	boolean	false	Stored monitoring preference for trigger alerts.
evaluation_model	string | null	null	Model identifier used for evaluation/testing metadata.
last_evaluated_at	datetime | null	null	Last evaluation timestamp.
allowed_use_cases	string[]	[]	Governance allowlist of product use cases.
disallowed_inputs	string[]	[]	Governance metadata for disallowed input categories.
disallowed_outputs	string[]	[]	Governance metadata for disallowed output categories.
human_approval_required	boolean	false	Whether the guardrail record requires human approval in governance workflows.
data_access_boundary	string | null	null	Text description of the data boundary the AI system must not cross.
escalation_route	string | null	null	Team, channel, or queue for escalated runtime events.
policy_refs	string[]	[]	Linked policy identifiers or URLs.

id, product_id, created_at, and updated_at are response-only fields.

Runtime Enforcement Modes

Mode	Runtime effect
block	Blocking input checks set a refusal before the model call. Blocking output checks replace the model output with the configured fallback or the default refusal.
warn	The guardrail event is recorded as warned, but runtime continues.
log	The guardrail event is recorded as logged, but runtime continues.

Runtime metadata records the product id, direction, reason, match, enforcement mode, and whether the event blocked, warned, or logged.

Validation Rules

• rule_type must be input_filter, output_filter, or both.
• enforcement_mode must be block, warn, or log.
• pii_categories accepts only email, ssn, credit_card, and phone.
• toxicity_threshold must be between 0.0 and 1.0.
• max_token_limit must be between 1 and 8000.
• fallback_response must be at most 1000 characters after trimming.
• regex_patterns must be valid regex strings, at most 10 total, at most 256 characters each, and cannot include nested unbounded quantifiers.

Invalid payloads return FastAPI validation errors.

Get Guardrail Details

GET /catalog/spaces/{space_slug}/products/{product_id}/guardrail/

Example

curl -X GET "https://api.qarion.com/api/v1.0/catalog/spaces/ml-platform/products/550e8400-e29b-41d4-a716-446655440000/guardrail/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "rule_type": "both",
  "enforcement_mode": "block",
  "topics_blocked": ["credential exfiltration", "self-harm"],
  "topics_allowed": ["customer analytics", "retention analysis"],
  "regex_patterns": ["(?i)api[_-]?key\\s*[:=]"],
  "pii_detection_enabled": true,
  "pii_categories": ["email", "credit_card"],
  "toxicity_threshold": 0.75,
  "max_token_limit": 4000,
  "fallback_response": "This request is blocked by the product guardrail.",
  "alert_on_trigger": true,
  "evaluation_model": "gpt-4o-mini",
  "last_evaluated_at": "2026-06-01T10:30:00Z",
  "allowed_use_cases": ["customer-retention-analysis"],
  "disallowed_inputs": ["raw secrets"],
  "disallowed_outputs": ["customer PII"],
  "human_approval_required": true,
  "data_access_boundary": "Do not use raw production customer records.",
  "escalation_route": "privacy-review",
  "policy_refs": ["POL-AI-017"],
  "created_at": "2026-05-01T09:00:00Z",
  "updated_at": "2026-06-01T10:30:00Z"
}

Upsert Guardrail Details

PUT /catalog/spaces/{space_slug}/products/{product_id}/guardrail/

The request body is partial. Omitted fields are unchanged for existing records and use model defaults for new records.

Example

curl -X PUT "https://api.qarion.com/api/v1.0/catalog/spaces/ml-platform/products/550e8400-e29b-41d4-a716-446655440000/guardrail/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "both",
    "enforcement_mode": "block",
    "topics_blocked": ["credential exfiltration", "self-harm"],
    "regex_patterns": ["(?i)api[_-]?key\\s*[:=]"],
    "pii_detection_enabled": true,
    "pii_categories": ["email", "credit_card"],
    "max_token_limit": 4000,
    "fallback_response": "This request is blocked by the product guardrail.",
    "policy_refs": ["POL-AI-017"]
  }'

Returns the saved GuardrailDetailResponse.

Catalog Product Embedding

Product create and update payloads may include a nested guardrail_details object:

{
  "name": "Safety Guardrail",
  "product_type": "Guardrail",
  "description": "Runtime controls for customer analytics prompts",
  "guardrail_details": {
    "rule_type": "output_filter",
    "enforcement_mode": "warn",
    "topics_blocked": ["raw customer identifiers"],
    "pii_detection_enabled": true,
    "pii_categories": ["email", "phone"]
  }
}

Use the dedicated Guardrails API when you need to fetch or update guardrail configuration independently from the broader catalog product payload.