organization-guardrail-definitions

Create Organization Guardrail Definition

Changed on

Define a guardrail this deployment will build and call itself. Organization owners and admins only.

guardrail_name must be one the built-in guardrail catalog lists (GET /api/v1/tool-settings/guardrails/catalog), and create_kwargs must satisfy that guardrail's constructor as the catalog describes it: no argument it does not declare, nothing it types as a live object rather than configuration, and every required argument no environment variable can supply. Arguments the catalog marks secret are encrypted at rest.

A definition on its own changes no request. Mandate it through /api/v1/organizations/me/guardrails for it to run.

The definition is saved first and built second, so a guardrail this deployment cannot construct is still stored and answers build_state: "failed" rather than refusing the write. Why it failed is not reported: a vendor library may put the arguments it was handed, which are your credentials, into its own error message. The reason is in the gateway's log.

post/api/v1/organizations/me/guardrail-definitions

Request

  • The document declares no server URL.
  • Auth: one of:
    • API key in header Otari-Key
    • API key in header x-api-key

Request body

create_kwargsobject

Constructor arguments for the guardrail. Every argument the catalog marks secret is encrypted at rest and never returned; the rest are stored and returned as sent

enabledboolean

False stops the guardrail everywhere it is mandated

guardrail_namestring required

The any-guardrail class to build, as the built-in guardrail catalog names it

namestring required

The organization's own label for this definition, unique within the organization

Example request

{
  "create_kwargs": {
    "api_key": "lakera-...",
    "endpoint": "https://api.lakera.ai"
  },
  "enabled": true,
  "guardrail_name": "lakera_guard",
  "name": "prod-lakera"
}

Response

Successful Response

build_state'built' | 'failed' | 'pending' | 'disabled' required

Whether the worker that answered this request holds a guardrail built from this version of the definition. built means it does and the check runs; failed means that worker tried these exact arguments and could not build them, so every mandate pointing here is unevaluable; pending means it holds nothing for this version yet, which is the answer right after a write and on any worker that has not caught up within the refresh interval; disabled means the definition is switched off and nothing is built on purpose. It answers for one worker, so two reads can disagree while a write propagates. Why a build failed is never reported here: the reason is in the gateway's log

create_kwargsobject required

The constructor arguments the catalog does not mark secret, as they were stored. Returned in clear: the secrets were taken out of this map by flag, and a form has to round-trip an endpoint or a project id

create_secretsobject required

The secret constructor arguments this definition holds, each as ***. Sending one back unchanged keeps the stored value; sending a new one rotates it, and leaving one out clears it

created_atstring required
enabledboolean required
guardrail_namestring required
idstring uuid required
namestring required
organization_idstring uuid required
secrets_decryptableboolean required

False when the stored secrets cannot be read with the current OTARI_SECRET_KEY, in which case create_secrets is empty and the definition needs its credentials sent again

updated_atstring required

Changes