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

# Policy API

> API reference for policy evaluation — test tools against an agent's resolved policy and replay historical traces

<Note>
  Part of **[CLPI](/concepts/clpi) Phase 1: Policy Engine**. The Policy API is the programmatic interface to policy **evaluation**.
</Note>

The Policy API evaluates tool usage against an agent's resolved policy, and replays historical traces against the current policy for pre-enforcement auditing.

<Warning>
  **Setting a policy is done through the alignment card.** Agent and org policy are not standalone resources — they live in the unified [alignment card](/concepts/alignment-cards)'s `capabilities` and `enforcement` sections. Set an agent's policy via `PUT /v1/alignment/agent/{agent_id}`. See [Agent cards](/concepts/agent-cards) and the [Policy Management guide](/guides/policy-management). The two evaluation endpoints below are the way to test tools against a resolved policy — there is no separate policy CRUD surface.
</Warning>

For authentication, the base URL, rate limits, and the error envelope shared by every `/v1/*` endpoint, see the [API overview](/api-reference/overview) and [Errors](/api-reference/errors).

## Endpoints

<CardGroup cols={2}>
  <Card title="POST /policies/evaluate" icon="check" href="/api-reference/endpoint/post-policies-evaluate">
    Evaluate a caller-supplied list of tools against the policy derived from an agent's published canonical alignment card. Returns a verdict, any violations/warnings/card gaps, and a coverage report.
  </Card>

  <Card title="POST /policies/evaluate/historical" icon="clock-rotate-left" href="/api-reference/endpoint/post-policies-evaluate-historical">
    Replay an agent's most recent traces (up to 200) against its current canonical card, or against a hypothetical `card_json`, to see which past tool calls would violate today's policy.
  </Card>
</CardGroup>

Both endpoints derive the policy from the agent's canonical alignment card server-side — you never pass a policy document in the request body. See each endpoint's page for the exact request/response schema, or the [Policy Management guide](/guides/policy-management#evaluate-tools-against-the-active-policy) for worked examples.

<Note>
  A related endpoint, [`POST /teams/recommend-policy`](/api-reference/endpoint/post-teams-recommend-policy), generates a starting policy from a risk forecast rather than evaluating one. See [Policy Management → Using policy recommendations](/guides/policy-management#using-policy-recommendations).
</Note>

## SDK usage

`@mnemom/sdk` does not yet include a dedicated helper for policy evaluation. Call `/v1/policies/evaluate` (or `/evaluate/historical`) directly over HTTP:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await fetch('https://api.mnemom.ai/v1/policies/evaluate', {
    method: 'POST',
    headers: {
      'X-Mnemom-Api-Key': process.env.MNEMOM_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agent_id: 'mnm-550e8400-e29b-41d4-a716-446655440000',
      tools: [{ name: 'mcp__browser__navigate' }, { name: 'mcp__filesystem__delete' }],
    }),
  }).then((r) => r.json());

  console.log(result.verdict); // "pass" | "warn" | "fail"
  console.log(result.coverage.coverage_pct);
  ```

  ```python Python theme={null}
  import httpx

  result = httpx.post(
      "https://api.mnemom.ai/v1/policies/evaluate",
      headers={"X-Mnemom-Api-Key": api_key},
      json={
          "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
          "tools": [{"name": "mcp__browser__navigate"}, {"name": "mcp__filesystem__delete"}],
      },
  ).json()

  print(result["verdict"])
  print(result["coverage"]["coverage_pct"])
  ```
</CodeGroup>

## See also

* [Policy Engine](/concepts/policy-engine) -- how policies are evaluated and enforced
* [Policy Management Guide](/guides/policy-management) -- creating, testing, and publishing a card's policy
* [CI/CD Policy Gates](/guides/ci-cd-policy-gates) -- gating a pipeline on `mnemom card evaluate`
* [Alignment cards](/concepts/alignment-cards) -- where agent and org policy is declared


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