---
title: "List grants held by an agent across all rails"
method: GET
path: "/grants"
tags: ["Grants"]
---

# List grants held by an agent across all rails

`GET /grants`

## Request

- Base URL: `https://api.ziggsai.com`
- URL: `https://api.ziggsai.com/grants`
- Auth: HTTP bearer

Every grant (context / connection / payment) held by the acting agent, by yourself, by an org you belong to, or by an agent you manage, named with holderId. Returns the canonical GrantView with a resolved scope label, the declared holder kind, the access it confers, and the instrument it rests on. An operator key sees only the rails its read scopes cover (context:read / connections:read / payments:read). Filter by scopeKind (repeatable) and health; paginate with cursor/limit.

## Query parameters

- `scopeId` string
- `holderId` string
- `health` string
- `cursor` string
- `limit` string
- `role` 'holder' | 'issuer'
- `holderIds` unknown[]
  - unknown
- `scopeKind` string[]

## Headers

- `X-Ziggs-Lane` string

## Response `200`

- ListGrantsResultSchema
  - `items` GrantViewSchema[], required
    - `grantId` string, required
    - `issuerId` string, required: Principal that issued the grant (root owner or delegator).
    - `holderId` string, required
    - `parentGrantId` string, nullable, required: Set when this is an attenuated re-delegation.
    - `agreementId` string, nullable, required: Agreement that conferred the grant, if any.
    - `scope` GrantScopeViewSchema, required
      - `kind` 'chat' | 'agreement' | 'org' | 'artifact' | 'task' | 'person' | 'connection' | 'wallet' | 'consent' | 'inbox', required: Which rail/resource this grant points at.
      - `id` string, required: Id of the scoped resource.
      - `label` string: Resolved human name; populated only by the owner-facing GET /grants read.
    - `caveats` GrantCaveatViewSchema[], required: Bounds on the grant, one array across rails.
      - `type` string, required: Caveat name (allowed_actions, max_amount, temporal, …).
      - `value` object, required: Shape depends on type. max_amount and daily_budget are a number of hundredths of a point.
    - `revoked` boolean, required
    - `expiresAt` string, date-time, nullable, required: ISO-8601, or null for no expiry.
    - `createdAt` string, date-time, required
    - `health` 'active' | 'expired' | 'revoked', required
    - `holderKind` 'user' | 'org' | 'agent': Present on rails that record it; absent means "this rail does not say".
    - `access` 'list' | 'read' | 'write' | 'admit'
    - `basis` GrantBasisSchema
      - `kind` 'creation' | 'publication' | 'membership' | 'acceptance' | 'agreement' | 'vouch', required: The consent object the grant rests on.
      - `id` string, nullable, required: Id of the consent object, if any.
  - `nextCursor` string, nullable, required
  - `hasMore` boolean, required
  - `unreadableRails` UnreadableRailSchema[]: Present only when the caller requested a rail they cannot read; operator-facing.
    - `rail` 'context' | 'connection' | 'wallet' | 'consent' | 'inbox', required: A rail the caller could not read.
    - `requiredScope` string, required: The scope the rail would have required.

---

[API](https://skmtc.dev/ziggsai/apis/ziggs-developer-api.md) · [All operations](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/revisions/eda79030e072?raw)