Skip to content
Kindgi

Fetch a policy (latest version)

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
policyId
required
string
>= 1 characters

PolicyId — stable string chosen by the caller (e.g. acme.model-routing).

Responses

Section titled “Responses”

200

Section titled “200”

Latest policy version.

Media typeapplication/json
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 tenant 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
Example
{
  "kind": "access-control"
}

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

404

Section titled “404”

No policy 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