Skip to content
Kindgi

List workspace policies

View as Markdown
GET
/v1/policies
curl --request GET \
  --url 'https://example.com/v1/policies?limit=25&kind=access-control&includeRetired=false' \
  --header 'Authorization: Bearer <token>'

Cursor-paginated. Optional ?kind= narrows to a single policy kind (exact match); optional ?name= is a prefix match on Policy.id. Sort order: policy id ascending. Latest version per id. A retired policy (every version unregistered) is listed only with ?includeRetired=true, as its highest version with unregisteredAt, so it can be found and a version reinstated.

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.

kind
string
Allowed values: access-control model-routing adapter-allowlist rate-limit retention compliance tool-errors hitl

Filter to policies of a single kind. Values: access-control | model-routing | adapter-allowlist | rate-limit | retention | compliance | tool-errors | hitl.

name
string

Prefix match on Policy.id. Dotted namespaces are the natural filter shape.

includeRetired
boolean

When true, retired items (every version unregistered) are listed too, each as its highest version with that version’s unregisteredAt. Default: false (items with an active version only).

Responses

Section titled “Responses”

200

Section titled “200”

Page of policies.

Media typeapplication/json
object
data
required
Array<object>
object
id
required
string
>= 1 characters
tenantId
required
string format: uuid
version
required

Semver — publishing a modified policy produces a new version.

string
/^\d+\.\d+\.\d+$/
kind
required
string
Allowed values: access-control model-routing adapter-allowlist rate-limit retention compliance tool-errors hitl
description
string
spec
required

Kind-specific policy body. For access-control, matches @kindgi/specs/policy.schema.json (rules + defaults). For model-routing, matches TenantPolicy from @kindgi/capabilities (providers.allow / providers.deny / models.allow / models.deny / regionAllow / maxCostPerCallUsd / maxTokensPerCall). For tool-errors, ToolErrorsSpec (maxRetries / retryOn). For hitl, HitlSpec from @kindgi/policy-contract (maxTimeoutMs / minReviewerRole / tools — per tool id a mode or { mode, requiredRole }); it only tightens an agent’s approvals. For retention, { v: 1, doc: RetentionSpec } from @kindgi/policy-contract (domain / graceSeconds / mode, which must be purge); a workspace has one retention policy per domain, plus one for *. tool-errors, hitl and retention specs are validated on publish. For other kinds, the shape is defined by the runtime consumer.

object
key
additional properties
any
unregisteredAt

Present only on an unregistered version: a retired policy (every version unregistered) as GET /v1/policies?includeRetired=true lists it. GET /v1/policies/{policyId} answers the latest active version, which never carries it.

string format: date-time
nextCursor
string
hasMore
required
boolean
Example
{
  "data": [
    {
      "kind": "access-control"
    }
  ]
}

400

Section titled “400”

Malformed query parameter (unknown kind).

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

403

Section titled “403”

Not a member of the workspace (permission-denied). Without an authorization store, anyone reads it.

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