--- title: "List policies in a zone" method: GET path: "/zones/{zone_id}/policies" tags: ["Policies"] --- # List policies in a zone `GET /zones/{zone_id}/policies` ## Request - Base URL: `https://docs.keycard.ai` (the document declares no server; this is the origin it was published from) - URL: `https://docs.keycard.ai/zones/{zone_id}/policies` - Auth: one of: - HTTP bearer - OAuth 2 - Client credentials - Token URL: `/service-account-token` Returns a paginated list of policies in the zone. Supports cursor-based pagination, sorting, full-text search, and composable filters. The `filter[id]` parameter restricts results to a known set of policy IDs (up to 100). It composes with other filters (`filter[owner_type]`, `query[]`, etc.) but **cannot** be combined with cursor pagination (`after` / `before`) — the server returns 400 if both are present. When `filter[id]` is used without an explicit `limit`, the limit defaults to the number of requested IDs so all results fit in a single page. IDs that don't exist or fall outside the zone are silently omitted. ## Path parameters - `zone_id` string, required ## Query parameters - `after` string: An opaque cursor used for paginating through a list of results - `before` string: An opaque cursor used for paginating through a list of results - `limit` integer - `expand` PdpExpandField[] - `expand[]` PdpExpandField[] - `sort` 'created_at' - `order` 'asc' | 'desc' - `query[name]` string[]: Value shape for `query[]` and `query[]` search parameters. Wire conventions: - Case-insensitive substring match (ILIKE). - Repeated parameter instances are OR-ed across terms. - Comma splitting is NOT performed; literal commas in a search term are preserved as part of the term. Examples: ?query[name]=alpha&query[name]=beta -> name ILIKE %alpha% OR name ILIKE %beta% ?query[]=alpha -> any searchable field ILIKE %alpha% Cross-field form is `query[]`; field-scoped form is `query[]`. Field names are endpoint-specific; services declare each query parameter per operation. - `query[description]` string[]: Value shape for `query[]` and `query[]` search parameters. Wire conventions: - Case-insensitive substring match (ILIKE). - Repeated parameter instances are OR-ed across terms. - Comma splitting is NOT performed; literal commas in a search term are preserved as part of the term. Examples: ?query[name]=alpha&query[name]=beta -> name ILIKE %alpha% OR name ILIKE %beta% ?query[]=alpha -> any searchable field ILIKE %alpha% Cross-field form is `query[]`; field-scoped form is `query[]`. Field names are endpoint-specific; services declare each query parameter per operation. - `query[]` string[]: Value shape for `query[]` and `query[]` search parameters. Wire conventions: - Case-insensitive substring match (ILIKE). - Repeated parameter instances are OR-ed across terms. - Comma splitting is NOT performed; literal commas in a search term are preserved as part of the term. Examples: ?query[name]=alpha&query[name]=beta -> name ILIKE %alpha% OR name ILIKE %beta% ?query[]=alpha -> any searchable field ILIKE %alpha% Cross-field form is `query[]`; field-scoped form is `query[]`. Field names are endpoint-specific; services declare each query parameter per operation. - `query` string[]: Value shape for `query[]` and `query[]` search parameters. Wire conventions: - Case-insensitive substring match (ILIKE). - Repeated parameter instances are OR-ed across terms. - Comma splitting is NOT performed; literal commas in a search term are preserved as part of the term. Examples: ?query[name]=alpha&query[name]=beta -> name ILIKE %alpha% OR name ILIKE %beta% ?query[]=alpha -> any searchable field ILIKE %alpha% Cross-field form is `query[]`; field-scoped form is `query[]`. Field names are endpoint-specific; services declare each query parameter per operation. - `filter[owner_type]` string[]: Value shape for `filter[]` query parameters. Wire conventions: - Repeated parameter instances are OR-ed across values. - A single value containing comma-separated tokens is AND-ed across tokens. Examples: ?filter[status]=a&filter[status]=b -> status in (a, b) ?filter[tag]=foo,bar -> tag contains foo AND bar ?filter[tag]=foo,bar&filter[tag]=baz -> (foo AND bar) OR baz Field names and allowed values are endpoint-specific; services declare each filter[] parameter per operation with an appropriate items.type/items.enum override. - `filter[id]` string[] ## Headers - `X-API-Version` string - `X-Client-Request-ID` string, uuid ## Response `200` A paginated list of policies - PdpPoliciesList - `items` PdpPolicy[], required - `id` string, required - `zone_id` string, required - `name` string, required - `description` string, nullable - `archived_at` string, date-time, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `created_by` string, required - `created_by_user` PdpUser: The organization user behind a `created_by`, `updated_by` or `archived_by` value. Returned only when `expand[]=user` is requested. - `id` string, required: Public ID of the user in the organization's platform zone. This is not the same value as the `*_by` field it expands; use it to link to `/zones/{zone_id}/users/{id}`. - `zone_id` string, required: Public ID of the organization's platform zone the user belongs to. - `email` string, nullable, required: The user's email address, or null when not known. - `updated_by` string, nullable - `updated_by_user` PdpUser: The organization user behind a `created_by`, `updated_by` or `archived_by` value. Returned only when `expand[]=user` is requested. - `id` string, required: Public ID of the user in the organization's platform zone. This is not the same value as the `*_by` field it expands; use it to link to `/zones/{zone_id}/users/{id}`. - `zone_id` string, required: Public ID of the organization's platform zone the user belongs to. - `email` string, nullable, required: The user's email address, or null when not known. - `latest_version_id` string, nullable - `latest_version` integer, nullable: Human-readable version number of the latest version (e.g., 1, 2, 3) - `latest_schema_version` string, nullable: Schema version the latest version was validated against (e.g., "2026-02-24"). Null when the policy has no published versions. Denormalized from `PolicyVersion.schema_version` for the policy referenced by `latest_version_id`. - `owner_type` 'platform' | 'customer', required: Who manages this policy: - `"platform"` — managed by the Keycard platform (system policies). - `"customer"` — managed by the tenant (custom policies). - `pagination` PdpPagination, required: Cursor-based pagination metadata returned alongside a list of results - `before_cursor` string, required: An opaque cursor used for paginating through a list of results - `after_cursor` string, required: An opaque cursor used for paginating through a list of results - `total_count` integer: Total number of items across all pages. Only present when the request includes ?expand[]=total_count. ## Other responses - `400`: bad request error response when caller supplied invalid input data - `401`: unauthorized error response when caller session is not authenticated - `403`: forbidden error response when caller does not have permissions to a resource - `404`: not found error response when caller does not have permission to see a resource or the resource does not exist - `429`: rate limit exceeded error response when caller has exhausted api limits for the given time period - `500`: internal server error response when server encountered error of its own creation - `503`: service unavailable error when server you're attempting to reach is not available - `default`: internal server error response when server encountered error of its own creation ## Changes - **2026-10-29** `0dee67e0a73a`: 1 info - added the new optional `query` request parameter `query` - **2026-10-16** `0cfaff865771`: 16 breaking, 8 warning, 84 info - the response property `details/items/field` became optional for the status `400` - the response property `details/items/field` became optional for the status `401` - the response property `details/items/field` became optional for the status `403` - the response property `details/items/field` became optional for the status `404` - …104 more - **2026-05-07** `2abdf2efe2e6`: 1 info - added the new optional `query` request parameter `filter[id]` - **2026-05-06** `82ca6e382f13`: 1 info - added the optional property `items/items/latest_schema_version` to the response with the `200` status - **2026-04-24** `fcab5a5e6cd0`: 2 breaking, 2 warning, 8 info - for the `query` request parameter `after`, the minLength was increased from `0` to `1` - for the `query` request parameter `before`, the minLength was increased from `0` to `1` - for the `query` request parameter `after`, the maxLength was set to `255` - for the `query` request parameter `before`, the maxLength was set to `255` - …8 more [Operation history](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/changes/zones/:zone_id/policies/get.md) --- [API](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api.md) - [All operations](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/revisions/0dee67e0a73a?raw)