Skip to content
Zerker Gateway

Read the tenant's recent policy decisions

GET
/v1/policy/decisions
curl --request GET \
  --url 'https://example.com/v1/policy/decisions?limit=20&offset=0&action=allow' \
  --header 'Authorization: Bearer <token>'

Returns the calling tenant’s most-recent policy decisions (allow, warn, and deny), newest first — the audit-capture read side (spec 0009). Each row carries the action, the matched rule position, the coarse reason, and the agent/tool it applied to; a request body is never recorded (invariant #3). Tenant-scoped: a tenant only ever sees its own decisions.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

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

Maximum decisions to return, newest first. Clamped to [1, 100]; defaults to 20.

offset
integer
0

Matching decisions to skip, newest first. With total, this is what makes denials older than one page reachable at all — a denied call creates no invocation, so this feed is the only record of it.

since
string format: date-time

RFC 3339 inclusive lower bound on created_at.

until
string format: date-time

RFC 3339 inclusive upper bound on created_at.

action
string
Allowed values: allow warn deny

Filter by decision action. Unlike GET /v1/invocations, deny is accepted and is the most useful value: this is the store that has denials.

agent_id
string

Filter to one agent’s decisions.

Responses

Section titled “Responses”

200

Section titled “200”

The tenant’s recent policy decisions.

Media typeapplication/json

The GET /v1/policy/decisions response — recent decisions, newest first.

object
data
required
Array<object>

One recorded policy decision (spec 0009 audit capture). reason is the coarse, rule-position explanation — never call content (invariant #3).

object
id
required

The pdec_<uuidv7> decision ID (opaque).

string
agent_id
required

The agent the decision applied to.

string
protocol
required

The agent’s protocol (e.g. mcp, http).

string
mcp_tool

The parsed MCP tool the decision applied to; null for protocol=http calls.

string
nullable
action
required
string
Allowed values: allow warn deny
matched_rule
required

The 1-based position of the rule that produced the action, or empty when it came from default/on_error.

string
reason
required

A coarse explanation of the action.

string
created_at
required
string format: date-time
receipt_artifact_id

The Treeship artifact signed for this decision, or null. A denial has no invocation to carry evidence, so this is the only place the proof of a refusal is reachable.

string
nullable
limit
required

The effective limit applied to this response.

integer
offset
required

The offset applied to this response.

integer
total
required

Decisions matching the filter before limit/offset. Without it a caller cannot tell “no more rows” from “the page ended exactly here”, and cannot count a window’s denials without walking every page.

integer
Example
{
  "data": [
    {
      "action": "allow"
    }
  ]
}

400

Section titled “400”

An invalid since, until, or action value, or since after until.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object
error
required

A coarse, caller-safe message. Never contains internal state (invariant

string
Examplegenerated
{
  "error": "example"
}

401

Section titled “401”

Missing or invalid bearer token, or the token’s tenant/user claims are absent. No body.

500

Section titled “500”

An unexpected server-side error. No body (internal detail is never returned to callers, invariant