Skip to content
Kindgi

List guardrails

View as Markdown
GET
/v1/guardrails
curl --request GET \
  --url 'https://example.com/v1/guardrails?limit=25&scopeKind=tenant&inherit=true' \
  --header 'Authorization: Bearer <token>'

Cursor-paginated list of registered guardrails. Optional ?name= filters by prefix on guardrail id.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.

name
string

Prefix match on the resource id.

scopeKind

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string
Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

scopeId
string
>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.

inherit
boolean
default: true

Default true. false = literal-at-this-scope only (admin/audit view). Load-bearing for policy/config-scoped resources (mcp-endpoints); documented no-op for content-scoped resources (agents/flows/tools/…).

Responses

Section titled “Responses”

200

Section titled “200”

Page of guardrails.

Media typeapplication/json
object
data
required
Array<object>
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
nextCursor

Opaque cursor for the next page. Absent when hasMore: false.

string
hasMore
required
boolean
Example
{
  "data": [
    {
      "kind": "zero-llm",
      "action": {
        "on-violation": "halt"
      },
      "severity": "info",
      "scope": {
        "when": "always"
      },
      "at": "before-tool",
      "sees": "turn"
    }
  ]
}

400

Section titled “400”

Malformed query parameter.

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

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