Create a guardrail

POST/v1/guardrails

Create a guardrail.

Creates a guardrail in a workspace and returns it with a new slug (gr-...). Each check names a validator from GET /v1/guardrail-validators and its settings. Requires an organization admin, or an admin of the workspace in workspace_id.

Errors: 400 when a check's type is not a validator id or its config is rejected; 402 when the plan's guardrail limit for the workspace is reached, or a check uses an LLM_JUDGE validator on a plan without AI guardrails; 403 without access; 409 when the organization already has a guardrail with this name.

Authorization

AuthorizationBearer va_
A platform API key (va_...), created under Settings > API keys. Scoped to an organization or one workspace, with an admin or member role. Used by the management API.

Request body application/json

the guardrail to create

namestringrequired
Display name, unique within the organization (409 if taken).
organizationstringrequired
Slug of the organization that will own the guardrail.
workspace_idstring<uuid>required
Id (UUID) of the workspace the guardrail belongs to. It must belong to organization.
checksobject[]required
The checks to run. Every check's type must be a validator id and its config must be accepted by that validator (400 otherwise).
Child attributes
- typestringrequired
  The validator's id, from GET /v1/guardrail-validators, for example PII_DETECTOR, REGEX_MATCH, banned_words or prompt_injection. An unknown id is a 400. A validator of kind LLM_JUDGE needs a plan with AI guardrails (402 otherwise).
- targetenum<string>required
  Where the check runs: INPUT (the request's messages, before the provider is called), OUTPUT (the provider's answer, before it is returned) or BOTH.
  One of "INPUT", "OUTPUT", "BOTH"
- actionenum<string>required
  What a finding does: BLOCK (the request fails with 422), REDACT (the match is replaced with a placeholder and the request continues) or MONITOR (logged only). Use an action the validator lists in supported_actions.
  One of "BLOCK", "REDACT", "MONITOR"
- configmap<string, object>
  The validator's settings, as a JSON object matching its config_schema (its default_config is a starting point). A config the validator rejects is a 400. Default: an empty object.
descriptionstring
Free-text description. Optional.
enabledboolean
Whether the guardrail runs. Default true.

Responses

201application/json

Created

idstring<uuid>
The guardrail's unique id (UUID).
slugstring
The guardrail's identifier in URLs, on virtual keys and in the x-guardrail header: gr- and 16 hex characters. It never changes.
namestring
Display name, unique within the organization.
descriptionstring
Free-text description. Null when none is set.
organizationstring
Slug of the organization that owns the guardrail.
workspace_idstring<uuid>
Id (UUID) of the workspace the guardrail belongs to.
enabledboolean
Whether the guardrail runs. A disabled guardrail is skipped wherever it is applied.
checksobject[]
The guardrail's checks.
Child attributes
- typestringrequired
  The validator's id, from GET /v1/guardrail-validators, for example PII_DETECTOR, REGEX_MATCH, banned_words or prompt_injection. An unknown id is a 400. A validator of kind LLM_JUDGE needs a plan with AI guardrails (402 otherwise).
- targetenum<string>required
  Where the check runs: INPUT (the request's messages, before the provider is called), OUTPUT (the provider's answer, before it is returned) or BOTH.
  One of "INPUT", "OUTPUT", "BOTH"
- actionenum<string>required
  What a finding does: BLOCK (the request fails with 422), REDACT (the match is replaced with a placeholder and the request continues) or MONITOR (logged only). Use an action the validator lists in supported_actions.
  One of "BLOCK", "REDACT", "MONITOR"
- configmap<string, object>
  The validator's settings, as a JSON object matching its config_schema (its default_config is a starting point). A config the validator rejects is a 400. Default: an empty object.
attached_keysobject[]
The virtual keys that apply this guardrail. Filled by GET /v1/guardrails/{slug}; empty in the other responses.
Child attributes
- slugstring
  The virtual key's slug.
- namestring
  The virtual key's display name.
- statusstring
  The virtual key's status: ACTIVE, DISABLED, EXHAUSTED or EXPIRED.
- workspace_idstring<uuid>
  Id (UUID) of the virtual key's workspace. Null for a key with no workspace.
attached_key_countinteger<int32>
How many virtual keys apply this guardrail. Filled by GET /v1/guardrails/{slug}; null in the other responses.
created_bystring
Identifier of the caller (user or API key) that created the guardrail.
created_atstring<date-time>
When the guardrail was created (ISO 8601).
updated_atstring<date-time>
When the guardrail was last changed (ISO 8601).

Request

curl -X POST "https://api.vectoraxis.ai/v1/guardrails" \
  -H "Authorization: Bearer $VECTORAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "organization": "string",
  "workspace_id": "3f6c1a2e-8b4d-4c1e-9a7f-2d5e6b8c9a01",
  "checks": [
    {
      "type": "string",
      "target": "INPUT",
      "action": "BLOCK"
    }
  ]
}'

VectorAxis is built by GK Labs, a member of NVIDIA Inception.