Guardrails

Update a guardrail

Updates an existing guardrail. A document write that actually changes the policy increments version and archives the new document as a GuardrailVersion; metadata-only edits (name / description / context), and re-writing the document the guardrail already holds, leave the version untouched.

patch/v1/projects/{project_id}/guardrails/{guardrail_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/guardrails/{guardrail_id}
  • 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)

Path parameters

guardrail_idstring required

Headers

If-Matchstring

The version the caller believes the resource holds, as an entity tag (3 or "3"). Equivalent to expected_version in the request body; * states no precondition beyond the resource existing. A mismatch is 409 VERSION_CONFLICT.

Request body

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

Optional tag for the config version this write archives (e.g. pre-tightening). 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. Ignored when the write changes no policy, since no version is created.

expected_versioninteger nullable

The version the caller believes the resource holds. When the resource is at any other version the write is refused with 409 VERSION_CONFLICT and nothing is written; meta.current_version on that response names the version in force.

Omit it to write unconditionally. Omitting it does not make the write unordered: two writes that reach the server together are still serialized, and the one whose version was taken first is refused the same way. What the field adds is refusing a write whose author read the resource some time ago and has not seen what happened since.

The If-Match header carries the same precondition for a client that prefers the HTTP spelling. Sending both with different versions is 400 VALIDATION_FAILED.

Example request

{
  "version_label": "pre-tightening",
  "expected_version": 3
}

Response

Guardrail updated

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.