# Policy Schemas

## List

`client.zones.policySchemas.list(stringzoneID, PolicySchemaListParamsparams?, RequestOptionsoptions?): PolicySchemaListResponse`

**get** `/zones/{zone_id}/policy-schemas`

List policy schemas

### Parameters

- `zoneID: string`

- `params: PolicySchemaListParams`

  - `after?: string`

    Query param: Cursor for forward pagination. Returned in `Pagination.after_cursor`. Mutually exclusive with `before`.

  - `before?: string`

    Query param: Cursor for backward pagination. Returned in `Pagination.before_cursor`. Mutually exclusive with `after`.

  - `expand?: Array<"total_count">`

    Query param: Opt-in to additional response fields. Repeatable; matches the `expand[]` convention used across the Keycard API.

    - `"total_count"`

  - `filterDefault?: boolean`

    Query param: Filter schemas by default status. When `true`, returns only the zone's default schema. When `false`, returns only non-default schemas. Omit to return all schemas.

  - `format?: "cedar" | "json"`

    Query param: Schema representation format. `cedar` returns human-readable Cedar syntax in `cedar_schema`, `json` returns Cedar JSON schema object in `cedar_schema_json`.

    - `"cedar"`

    - `"json"`

  - `is_default?: boolean`

    Query param: **Deprecated.** Use `filter[default]` instead.

    Filter schemas by default status. When `true`, returns only the zone's default schema. When `false`, returns only non-default schemas. Omit to return all schemas.

    Still honored for backward compatibility. Supplying both `is_default` and `filter[default]` with conflicting values returns `400 Bad Request`.

  - `limit?: number`

    Query param: Maximum number of items to return per page.

  - `order?: "asc" | "desc"`

    Query param: Sort direction. Default is desc (newest first).

    - `"asc"`

    - `"desc"`

  - `sort?: "created_at"`

    Query param: Field to sort by.

    - `"created_at"`

  - `xAPIVersion?: string`

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

  - `xClientRequestID?: string`

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

### Returns

- `PolicySchemaListResponse`

  - `items: Array<SchemaVersionWithZoneInfo>`

    - `is_default: boolean`

      Whether this is the zone's default schema. Clients use this to pre-select which schema to write policies against. Has no effect on evaluation.

  - `pagination: Pagination`

    Cursor-based pagination metadata returned alongside a list of results

    - `after_cursor: string | null`

      An opaque cursor used for paginating through a list of results

    - `before_cursor: string | null`

      An opaque cursor used for paginating through a list of results

    - `total_count?: number`

      Total number of items across all pages. Only present when the request includes ?expand[]=total_count.

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const policySchemas = await client.zones.policySchemas.list('zone_id');

console.log(policySchemas.items);
```

## Retrieve

`client.zones.policySchemas.retrieve(stringversion, PolicySchemaRetrieveParamsparams, RequestOptionsoptions?): SchemaVersionWithZoneInfo`

**get** `/zones/{zone_id}/policy-schemas/{version}`

Get a policy schema by version

### Parameters

- `version: string`

- `params: PolicySchemaRetrieveParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `format?: "cedar" | "json"`

    Query param: Schema representation format. `cedar` returns human-readable Cedar syntax in `cedar_schema`, `json` returns Cedar JSON schema object in `cedar_schema_json`.

    - `"cedar"`

    - `"json"`

  - `xAPIVersion?: string`

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

  - `xClientRequestID?: string`

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

### Returns

- `SchemaVersionWithZoneInfo extends SchemaVersion`

  A versioned Cedar schema that defines the entity model, actions, and
  context shape used for policy evaluation. The schema contains the valid
  entity types (User, Application, Resource), their attributes, and the
  allowed attribute values. See the Credentials API spec for a full
  reference of entity attributes and valid values.

  - `is_default: boolean`

    Whether this is the zone's default schema. Clients use this to pre-select which schema to write policies against. Has no effect on evaluation.

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const schemaVersionWithZoneInfo = await client.zones.policySchemas.retrieve('version', {
  zone_id: 'zone_id',
});

console.log(schemaVersionWithZoneInfo);
```

## Set Default

`client.zones.policySchemas.setDefault(stringversion, PolicySchemaSetDefaultParamsparams, RequestOptionsoptions?): SchemaVersionWithZoneInfo`

**patch** `/zones/{zone_id}/policy-schemas/{version}`

Set the default policy schema for a zone

### Parameters

- `version: string`

- `params: PolicySchemaSetDefaultParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `body?: unknown`

    Body param

  - `xAPIVersion?: string`

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

  - `xClientRequestID?: string`

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

### Returns

- `SchemaVersionWithZoneInfo extends SchemaVersion`

  A versioned Cedar schema that defines the entity model, actions, and
  context shape used for policy evaluation. The schema contains the valid
  entity types (User, Application, Resource), their attributes, and the
  allowed attribute values. See the Credentials API spec for a full
  reference of entity attributes and valid values.

  - `is_default: boolean`

    Whether this is the zone's default schema. Clients use this to pre-select which schema to write policies against. Has no effect on evaluation.

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const schemaVersionWithZoneInfo = await client.zones.policySchemas.setDefault('version', {
  zone_id: 'zone_id',
});

console.log(schemaVersionWithZoneInfo);
```

## Domain Types

### Schema Version

- `SchemaVersion`

  A versioned Cedar schema that defines the entity model, actions, and
  context shape used for policy evaluation. The schema contains the valid
  entity types (User, Application, Resource), their attributes, and the
  allowed attribute values. See the Credentials API spec for a full
  reference of entity attributes and valid values.

  - `created_at: string`

  - `status: "active" | "deprecated" | "archived"`

    Controls what can be done with this schema version:

    - `"active"` - new policy versions can be created and validated against it.
    - `"deprecated"` - superseded by a newer version but still accepts new policy versions.
    - `"archived"` - closed to new policy versions. Existing policy set versions pinned to this schema still evaluate normally.

    - `"active"`

    - `"deprecated"`

    - `"archived"`

  - `updated_at: string`

  - `version: string`

  - `archived_at?: string | null`

  - `cedar_schema?: string | null`

    Cedar schema in human-readable syntax. Populated when format=cedar.

  - `cedar_schema_json?: unknown`

    Cedar schema as JSON object. Populated when format=json (default).

  - `deprecated_at?: string | null`

### Schema Version With Zone Info

- `SchemaVersionWithZoneInfo extends SchemaVersion`

  A versioned Cedar schema that defines the entity model, actions, and
  context shape used for policy evaluation. The schema contains the valid
  entity types (User, Application, Resource), their attributes, and the
  allowed attribute values. See the Credentials API spec for a full
  reference of entity attributes and valid values.

  - `is_default: boolean`

    Whether this is the zone's default schema. Clients use this to pre-select which schema to write policies against. Has no effect on evaluation.