Register an guardrail

POST

/v1/guardrails

curl --request POST \
  --url https://example.com/v1/guardrails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example", "description": "example", "kind": "zero-llm", "check": "example", "config": {}, "action": { "on-violation": "halt", "retry": { "maxAttempts": 1 }, "escalateTo": "example", "compensateWith": "example" }, "severity": "info", "scope": { "when": "always", "agents": [ "example" ], "flows": [ "example" ], "tenants": [ "example" ] }, "budget": { "maxCostUsd": 1, "maxLatencyMs": 1 }, "judgeCapabilities": {} }'

• Same-origin — path relative to the deployment root.

Body is a full Guardrail shape. Server validates via @kindgi/guardrails.validateGuardrailSpec. The check id must reference an implementation already available to the runtime; check code is not uploaded through this route.

Authorizations

• bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Request Body^required

Media typeapplication/json

Guardrail spec. Validated server-side via @kindgi/guardrails.validateGuardrailSpec. Metadata-only registration: the check id must reference an implementation already available to the runtime.

object

id

required

string

>= 1 characters

projectId

required

Project this belongs to (its content scope). Required: missing, or not a project in the caller’s tenant → 400 bad-input.

string format: uuid

name

string

description

string

kind

required

How the guardrail is checked. Open string: the built-in kinds are listed in examples; adapters register strategies for their own kinds.

string

>= 1 characters

check

required

Reference to the concrete check implementation registered server-side.

string

>= 1 characters

config

object

key

additional properties

any

action

required

object

on-violation

required

What happens when the guardrail fires. Open string: the built-in actions are listed in examples; any other name needs an action handler registered under it where the guardrail is evaluated.

string

>= 1 characters

retry

object

maxAttempts

required

integer

>= 1 <= 10

escalateTo

string

compensateWith

string

severity

string

Allowed values: info warn error critical

scope

object

when

string

Allowed values: always ci-only runtime-only

agents

Array<string>

flows

Array<string>

tenants

Array<string>

budget

object

maxCostUsd

number

maxLatencyMs

integer

judgeCapabilities

object

key

additional properties

any

Responses

201

Guardrail registered.

Media typeapplication/json

object

guardrailId

required

string

Example^generated

{
  "guardrailId": "example"
}

400

Validation failed (see details.issues); or projectId isn’t a project id (a UUID). Or reference-out-of-scope: a pack check it names isn’t registered in its project, its org or the tenant (details.issues); a built-in check is every project’s.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

The body’s projectId names no project of this tenant (project-not-found).

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Guardrail already registered at that id. Or registry-read-only: this registry takes no writes (under kindgi dev, the pack’s files are the source); the message says what to do instead.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

422

guardrail-config-invalid: the guardrail’s config breaks the configSchema of the check it names (a pack check’s, or a built-in’s), which would refuse it on every call. details.issues lists each problem, { path, message } with path a JSON pointer into the guardrail (/config/maxChars); the message names the guardrail, the check and the setting. Checked when the check’s deployment carries its schema.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

429

rate-limit-exceeded with details.limit: "schema-compile-time", on a server with a compile budget (Kindgi Cloud): this tenant’s schemas spent details.budgetMs compiling in the last 60 seconds. Nothing was stored; Retry-After says when to send it again.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Server error (unmapped domain code or framework crash).

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also

• GET /v1/guardrails: List guardrails
• Operate a self-hosted runtime
• Error code guardrail-config-invalid
• Error code project-not-found
• Error code rate-limit-exceeded
• Error code reference-out-of-scope
• Error code registry-read-only
• Error code request-too-large
• Every error code