Skip to main content

​
Policy API

Part of CLPI Phase 1: Policy Engine. The Policy API is the programmatic interface to policy evaluation.
The Policy API provides programmatic access to policy evaluation — evaluate tool usage against an agent’s resolved policy, and replay historical traces against the current policy for pre-enforcement auditing.
Setting a policy is done through the alignment card. Agent and org policy are no longer standalone resources — they are part of the unified alignment card surface. Set an agent’s policy via PUT /v1/alignment/agent/{agent_id} and an org’s baseline via the org-card surface. See Agent cards and the Policy Management guide. The evaluation endpoints below are the canonical way to test tools against a resolved policy.
Base URL: https://api.mnemom.ai/v1

​
Authentication

EndpointAuth RequiredNotes
POST /v1/policies/evaluateAPI key or Bearer JWTEvaluate tools against an agent’s resolved policy
POST /v1/policies/evaluate/historicalAPI key or Bearer JWTReplay historical traces against the current policy
API key authentication: Pass in the X-Mnemom-Api-Key header: 
X-Mnemom-Api-Key: mnm_your_key_here
Bearer JWT authentication: Pass in the Authorization header: 
Authorization: Bearer {token}
API keys can be created in your dashboard under Settings or via POST /v1/api-keys.

​
Rate limits

EndpointRate LimitWindow
POST /policies/evaluate60 requestsper minute
POST /policies/evaluate/historical30 requestsper minute
Rate-limited responses return HTTP 429 with a Retry-After header.

​
Endpoints

​
POST /v1/policies/evaluate

Evaluate a policy against a set of tools. Returns a verdict indicating whether the tools are permitted, any violations or warnings, and coverage analysis against the agent’s card actions. Request body: 
{
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "tools": ["mcp__browser__navigate", "mcp__filesystem__delete"],
  "context": "gateway"
}
FieldTypeRequiredDescription
agent_idstringYesAgent identifier whose resolved policy will be evaluated
toolsstring[]YesList of tool names to evaluate against the policy
contextstringNoEvaluation context: "gateway", "runtime", or "audit" (default: "gateway")
Response: 200 OK 
{
  "verdict": "fail",
  "violations": [
    {
      "type": "forbidden",
      "tool": "mcp__filesystem__delete",
      "reason": "Deletion not permitted",
      "severity": "critical"
    }
  ],
  "warnings": [],
  "card_gaps": [],
  "coverage": {
    "total_card_actions": 5,
    "mapped_card_actions": ["web_fetch", "web_search"],
    "unmapped_card_actions": ["read", "write", "send_response"],
    "coverage_pct": 40
  },
  "policy_id": "pol-abc123",
  "policy_version": 3,
  "evaluated_at": "2026-02-25T14:00:00.000Z",
  "context": "gateway",
  "duration_ms": 12
}
Response fields:
FieldTypeDescription
verdictstringOverall result: "pass", "fail", or "warn"
violationsarrayPolicy violations found during evaluation
warningsarrayNon-blocking warnings (e.g., unmapped tools in "warn" mode)
card_gapsarrayCard actions that are declared but have no tool mapping
coverageobjectCoverage analysis of card actions vs. capability mappings
policy_idstringID of the policy that was evaluated
policy_versionnumberVersion of the policy that was evaluated
evaluated_atstringISO 8601 timestamp of evaluation
contextstringEvaluation context used
duration_msnumberTime taken for evaluation in milliseconds
Violation object:
FieldTypeDescription
typestringViolation type: "forbidden", "unmapped", or "escalation"
toolstringTool name that triggered the violation
reasonstringHuman-readable explanation
severitystringSeverity level: "low", "medium", "high", or "critical"
coverage object:
FieldTypeDescription
total_card_actionsnumberTotal number of card actions declared for the agent
mapped_card_actionsstring[]Card actions that have at least one tool mapping
unmapped_card_actionsstring[]Card actions with no tool mapping
coverage_pctnumberPercentage of card actions covered by capability mappings (0 — 100)
Error responses:
StatusMeaning
400Invalid request body (missing agent_id or tools)
401API key required or invalid
404Agent not found or no policy exists

​
POST /v1/policies/evaluate/historical

Evaluate a policy against historical traces for an agent. Replays past tool invocations through the current policy to surface retroactive violations. Useful for auditing policy changes before enforcement. Request body: 
{
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "time_range": {
    "start": "2026-02-18T00:00:00.000Z",
    "end": "2026-02-25T23:59:59.000Z"
  },
  "context": "audit"
}
FieldTypeRequiredDescription
agent_idstringYesAgent identifier
time_rangeobjectYesTime range with start and end ISO 8601 timestamps
contextstringNoEvaluation context (default: "audit")
Response: 200 OK 
{
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "traces_evaluated": 142,
  "verdict": "fail",
  "violation_count": 7,
  "violations": [
    {
      "type": "forbidden",
      "tool": "mcp__filesystem__delete",
      "reason": "Deletion not permitted",
      "severity": "critical",
      "trace_id": "tr-abc123",
      "occurred_at": "2026-02-22T09:15:00.000Z"
    }
  ],
  "summary": {
    "pass": 135,
    "warn": 0,
    "fail": 7
  },
  "policy_id": "pol-abc123",
  "policy_version": 3,
  "evaluated_at": "2026-02-25T14:05:00.000Z",
  "duration_ms": 340
}
Response fields:
FieldTypeDescription
agent_idstringAgent identifier
traces_evaluatednumberNumber of historical traces evaluated
verdictstringOverall result: "pass", "fail", or "warn"
violation_countnumberTotal number of violations found
violationsarrayViolation details including trace_id and occurred_at
summaryobjectBreakdown of trace verdicts: pass, warn, and fail counts
policy_idstringID of the policy evaluated against
policy_versionnumberVersion of the policy evaluated against
evaluated_atstringISO 8601 timestamp of evaluation
duration_msnumberTime taken for evaluation in milliseconds
Error responses:
StatusMeaning
400Invalid request body or time range
401API key required or invalid
404Agent not found or no policy exists
422Time range exceeds maximum (30 days)

​
Error codes

StatusCodeDescription
400invalid_requestMissing or invalid parameters
401unauthorizedAPI key required but not provided or invalid
404not_foundAgent or policy not found
422validation_errorSemantic validation failed (e.g., invalid time range)
429rate_limitedToo many requests; check Retry-After header
500internal_errorServer error; retry with exponential backoff
All error responses follow the standard envelope: 
{
  "error": {
    "code": "not_found",
    "message": "No policy found for agent 'mnm-550e8400-e29b-41d4-a716-446655440000'"
  }
}

​
SDK usage

Policy evaluation is not yet wrapped by the @mnemom/sdk client (which currently covers the agents and catalog namespaces). Call /v1/policies/evaluate directly over HTTP until an SDK helper ships.
const API_BASE = 'https://api.mnemom.ai';

// Evaluate tools against the agent's resolved policy
const result = await fetch(`${API_BASE}/v1/policies/evaluate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MNEMOM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agent_id: 'mnm-550e8400-e29b-41d4-a716-446655440000',
    tools: ['mcp__browser__navigate', 'mcp__filesystem__delete'],
    context: 'gateway',
  }),
}).then((r) => r.json());

console.log(result.verdict);                // "fail"
console.log(result.violations);             // [{ tool: "mcp__filesystem__delete", ... }]
console.log(result.coverage.coverage_pct);  // 40
To set or update an agent’s policy, use the unified alignment-card endpoint — see the Policy Management guide.

​
See also