Skip to content
Kindgi

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", "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": {}, "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

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

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

Caller-supplied idempotency key. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

Request Bodyrequired

Section titled “Request Bodyrequired”
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
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
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

Responses

Section titled “Responses”

201

Section titled “201”

Guardrail registered.

Media typeapplication/json
object
guardrailId
required
string
Examplegenerated
{
  "guardrailId": "example"
}

400

Section titled “400”

Validation failed (see details.issues).

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

Guardrail already registered at that id.

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}