KEkeycardai
Policies

List policies in a zone

Changed on

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.

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
    • HTTP bearer
    • or OAuth 2
      Client credentials
      Token URL: /service-account-token

Path parameters

zone_idstring required

The zone identifier

Query parameters

afterstring

An opaque cursor used for paginating through a list of results

Cursor for forward pagination. Returned in Pagination.after_cursor. Mutually exclusive with before.

beforestring

An opaque cursor used for paginating through a list of results

Cursor for backward pagination. Returned in Pagination.before_cursor. Mutually exclusive with after.

limitinteger

Maximum number of items to return per page.

expandPdpExpandField[]

Deprecated. Use expand[] instead.

Opt-in to additional response fields. Still honored for backward compatibility; supplying both expand and expand[] with disagreeing values returns 400 Bad Request.

expand[]PdpExpandField[]

Opt-in to additional response fields (total_count, user). Repeatable; matches the expand[] convention used across the Keycard API.

sort'created_at'

Field to sort by.

order'asc' | 'desc'

Sort direction. Default is desc (newest first).

query[name]string[]

Value shape for query[] and query[<field>] 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>]. Field names are endpoint-specific; services declare each query parameter per operation.

Case-insensitive substring search on name. Repeatable; if multiple terms are supplied they are OR-ed (any matching term returns the row).

query[description]string[]

Value shape for query[] and query[<field>] 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>]. Field names are endpoint-specific; services declare each query parameter per operation.

Case-insensitive substring search on description (policies only). Repeatable; if multiple terms are supplied they are OR-ed.

query[]string[]

Value shape for query[] and query[<field>] 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>]. Field names are endpoint-specific; services declare each query parameter per operation.

Case-insensitive substring search across all searchable fields of the resource. For policies that is name and description; for policy sets that is name. Repeatable; if multiple terms are supplied they are OR-ed.

querystring[]

Value shape for query[] and query[<field>] 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>]. Field names are endpoint-specific; services declare each query parameter per operation.

Deprecated. Use query[] instead.

Identical semantics to query[]: case-insensitive substring search across all searchable fields of the resource, repeatable and OR-ed across terms. Still honored for backward compatibility — generated SDK clients serialize the unscoped search parameter without brackets (the OpenAPI name query[] is normalized to query at generation time). Supplying both query and query[] with disagreeing values returns 400 Bad Request.

filter[owner_type]string[]

Value shape for filter[<field>] 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[<field>] parameter per operation with an appropriate items.type/items.enum override.

Filter on owner_type. Repeatable; repeated instances OR across values (e.g. ?filter[owner_type]=platform&filter[owner_type]=customer matches either). See FilterValues in the shared spec for the full wire convention.

Allowed values: platform, customer. Unknown values return 400 with the list of allowed values. Comma-separated single values (e.g. ?filter[owner_type]=platform,customer) are rejected with a 400 pointing at the repeated-parameter OR form.

Note: the allowed-value enum is enforced in the handler (not as an OpenAPI items.enum) so the server can return a targeted error for the comma-AND form instead of a generic "not in allowed values" response.

filter[id]string[]

Filter by policy ID. Repeatable; multiple values are OR-ed (e.g. ?filter[id]=p1&filter[id]=p2). Capped at 100 IDs per request — over-cap returns 400.

Cannot be combined with cursor pagination (after or before). The server returns 400 if both are present.

Composes with other filters (filter[owner_type], query[], etc.). When no explicit limit is provided, it 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 scope are silently omitted; callers diff against the request set if they care about missing IDs.

Headers

X-API-Versionstring

API version header (date-based, e.g. 2026-02-01)

X-Client-Request-IDstring uuid

Unique request identifier specified by the originating caller and passed along by proxies.

Response

A paginated list of policies

Changes

  • 0dee67e0a73aRevision changes
    • info

      added the new optional query request parameter query

  • 0cfaff865771Revision changes
    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • info

      added the enum value user to the property items/ of the query request parameter expand

    • info

      added the enum value user to the property items/ of the query request parameter expand[]

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status