Guardrails

Create a guardrail

Creates a new guardrail in the project, archiving its document as version 1. The document is validated on write: class must be a literal (A/B/C/D) or a JSON Logic expression, and every variable it (and guard) reference must resolve to the args.* / context.* / runtime.* namespaces — an out-of-catalog runtime.* key is rejected with 400.

post/v1/projects/{project_id}/guardrails

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/guardrails
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

namestring required

Human-readable name

descriptionstring nullable
context_tool_idstring nullable
context_mode'merge' | 'replace'
version_labelstring

Optional tag for the config version this write archives (e.g. initial). Annotates the version only — it is not stored on the guardrail and is not part of the config, so labelling a change is never itself a change.

Example request

{
  "name": "Budget Update Guardrail",
  "version_label": "initial"
}

Response

Guardrail created

idstring

Public ID of the guardrail

project_idstring

Public ID of the owning project

namestring

Human-readable name

descriptionstring nullable

Optional description

versioninteger

Incremented on every document write; prior versions are archived

context_tool_idstring nullable

Optional tool the platform calls at evaluation time to fetch fresh guardrail context.

context_mode'merge' | 'replace' | 'null' nullable

How tool-fetched context combines with the caller-supplied context.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "guard_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "name": "Budget Update Guardrail",
  "version": 1
}

Changes

No recorded changes to this operation across all 1 revision of this API.