Skip to content
Kindgi

Fetch an guardrail

View as Markdown
GET
/v1/guardrails/{guardrailId}
curl --request GET \
  --url https://example.com/v1/guardrails/example \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
guardrailId
required
string

GuardrailId — unique identifier for the guardrail.

Responses

Section titled “Responses”

200

Section titled “200”

Guardrail.

Media typeapplication/json
object
id
required
string
>= 1 characters
projectId

The guardrail’s project. Absent when the runtime doesn’t record it: a pack kindgi dev serves from disk, or a runtime before Kindgi 0.1.6.

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 a failed check does to the agent turn. Open string: the built-in actions are listed in examples, and any other non-empty name is accepted. The runtime acts on halt: the turn fails with guardrail-violation and its response is not stored. It acts on retry too: the answer goes back to the model with the check’s reason, for a new one, until retry.maxAttempts run out, and then the turn fails the same way, with details.attempts. Any other value is recorded as a violation, as log-only is, and the turn completes: in 0.1 nothing escalates or calls a compensating tool.

string
>= 1 characters
retry

Counts the answers this guardrail fails in a turn, the first one included (with maxAttempts: 3 it sends a failed answer back up to twice, and the third answer it fails ends the turn). Left out, 2. The turn’s maxSteps, and the agent loop’s 32 model calls, bound it too.

object
maxAttempts
required
integer
>= 1 <= 10
escalateTo

Where an escalate goes. In 0.1 nothing escalates.

string
compensateWith

The tool id a compensate names. In 0.1 that tool isn’t called.

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>
tools

At before-tool and after-tool: the tools whose calls it checks, by id. A trailing * matches every id with that prefix, and a * anywhere else is refused. Absent: every tool.

Array<string>
>= 1 items
at

Where in the agent’s turn the check runs: before a tool call runs, after it runs, on each model reply, or on the final answer. It must be one of the check’s points.

string
default: final-answer
Allowed values: before-tool after-tool model-step final-answer
sees

What the check sees: this turn, or the conversation’s earlier turns too.

string
default: turn
Allowed values: turn conversation
budget
object
maxCostUsd
number
maxLatencyMs
integer
judgeCapabilities
object
key
additional properties
any
Example
{
  "kind": "zero-llm",
  "action": {
    "on-violation": "halt"
  },
  "severity": "info",
  "scope": {
    "when": "always"
  },
  "at": "before-tool",
  "sees": "turn"
}

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"
  }
}

404

Section titled “404”

No guardrail with that id under this tenant.

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"
  }
}

503

Section titled “503”

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try 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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also