> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Class: PolicyApi

> Python SDK reference: Policy API.

Policy API.

## Constructors

### Constructor

> **new PolicyApi**(`transport`): `PolicyApi`

#### Parameters

##### transport

[`Transport`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/Transport)

#### Returns

`PolicyApi`

## Methods

### inEffect()

> **inEffect**(`capability`): `Promise`\<[`PolicyInEffect`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PolicyInEffect)>

The policy a request for `capability` must declare right now, and what
the request must carry: every fact the rules read, their types, the
signals bound to the Intent, and the signals that need a signed
approval. Maps to GET /policies/in-effect. Call it before every
request: an approved new version replaces the old one at once.

Throws AuthorizationError (403, code CAPABILITY\_NOT\_ALLOWED) when the
key may not invoke the capability, NotFoundError (404, code
CAPABILITY\_NOT\_BOUND) when no policy governs it, and ConflictError
(409, NO\_APPROVED\_POLICY\_VERSION) or InternalServerError (503,
POLICY\_VERSION\_UNAVAILABLE) when every request for it is refused right
now. Do not send a request in any of those cases.

#### Parameters

##### capability

`string`

#### Returns

`Promise`\<[`PolicyInEffect`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PolicyInEffect)>

***

### validate()

> **validate**(`policyId`, `policyVersion`): `Promise`\<[`PolicyValidationResult`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PolicyValidationResult)>

Confirms that a policy (name + version) is loadable by the Runtime.

POST /policies/validate does not accept or check a policy
document body — it only checks that
policyRepository.load(policyId, policyVersion) succeeds
(packages/api/src/routes/policies.ts).

POST /policies/validate does not use the shared `{error, code?}`
envelope for 400 or 404: both are `{valid, errors}`, its own shape,
the caller's answer, not an SDK-level failure — so those two
statuses are exempted from the default throw-on-error behavior. 401
is not exempted: it is generated by caller-auth middleware before
this route's own handler ever runs, and does use the shared
envelope, identically to every other route. See
/api-reference/error-handling.

#### Parameters

##### policyId

`string`

##### policyVersion

`string`

#### Returns

`Promise`\<[`PolicyValidationResult`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PolicyValidationResult)>

***

### proposeChange()

> **proposeChange**(`name`, `version`, `input`): `Promise`\<[`ProposedPolicyChange`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/ProposedPolicyChange)>

Proposes a policy change. Maps to POST
/policies/{name}/{version}/pending-changes. The API key must belong to
a verified human (credential holder type USER). `proposedContent.policyId`
must equal `name`. Only one open proposal per name and version is
allowed; a second one fails with ConflictError.

#### Parameters

##### name

`string`

##### version

`string`

##### input

[`ProposePolicyChangeInput`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/ProposePolicyChangeInput)

#### Returns

`Promise`\<[`ProposedPolicyChange`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/ProposedPolicyChange)>

***

### listChanges()

> **listChanges**(`status?`): `Promise`\<[`PolicyChangeForReview`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PolicyChangeForReview)\[]>

Lists policy changes for review, with the content in effect now next to
the proposed content. Maps to GET /policies/pending-changes. The API key
must belong to a verified human.

#### Parameters

##### status?

[`PendingPolicyChangeStatus`](https://docs.parmanasystems.com/sdks/reference/typescript/type-aliases/PendingPolicyChangeStatus)

Only changes in this state. Omit for all.

#### Returns

`Promise`\<[`PolicyChangeForReview`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PolicyChangeForReview)\[]>

***

### approveChange()

> **approveChange**(`pendingPolicyChangeId`, `stepUpAuthorization`): `Promise`\<[`PendingPolicyChange`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PendingPolicyChange)>

Approves a policy change, which then takes effect. Maps to POST
/policies/pending-changes/{id}/approve. The API key must belong to a
verified human with a registered step up key, who is not the proposer.
Make `stepUpAuthorization` with `signPolicyChangeStepUp()` and action
"approve"; it is valid once, for 120 seconds by default.

#### Parameters

##### pendingPolicyChangeId

`string`

##### stepUpAuthorization

[`PolicyChangeStepUpAuthorization`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PolicyChangeStepUpAuthorization)

#### Returns

`Promise`\<[`PendingPolicyChange`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PendingPolicyChange)>

***

### rejectChange()

> **rejectChange**(`pendingPolicyChangeId`, `rejectionReason`, `stepUpAuthorization`): `Promise`\<[`PendingPolicyChange`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PendingPolicyChange)>

Rejects a policy change. Maps to POST
/policies/pending-changes/{id}/reject. Same caller rules as
approveChange(); sign with action "reject". A reason is required.

#### Parameters

##### pendingPolicyChangeId

`string`

##### rejectionReason

`string`

##### stepUpAuthorization

[`PolicyChangeStepUpAuthorization`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PolicyChangeStepUpAuthorization)

#### Returns

`Promise`\<[`PendingPolicyChange`](https://docs.parmanasystems.com/sdks/reference/typescript/interfaces/PendingPolicyChange)>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.