> ## 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. # Evaluate policy against historical traces > Evaluate a CLPI policy against historical AIP traces for an agent. ## OpenAPI ````yaml POST /policies/evaluate/historical openapi: 3.1.0 info: title: Mnemom API description: >- Trust infrastructure for AI agents. Transparent alignment verification, behavioral drift detection, and accountability primitives. version: 1.0.0 contact: name: Mnemom url: https://mnemom.ai email: support@mnemom.ai license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://api.mnemom.ai/v1 description: Production security: - BearerAuth: [] - ApiKeyAuth: [] tags: - name: A2A description: >- Public A2A AgentCard projection of the canonical alignment card, with embedded AAP attestation extension (cards-as-primitive Phase 5). - name: Agents description: Agent registration, lifecycle, and metadata. - name: Agent Containment description: Containment policies and quarantine controls. - name: Alignment description: >- Alignment manifest CRUD — canonical `/v1/alignment//` surface across platform / org / team / agent (cards-as-primitive Phase 4). - name: Analyze description: Behavioral analysis endpoints. - name: Attestation description: >- AAP attestation token JWKS surface and platform-admin signing-key rotation (cards-as-primitive Phase 5). - name: Auth description: Authentication, sessions, and access management. - name: Billing description: Subscription, usage, and invoicing. - name: Blog description: Public blog content. - name: Card Templates description: Org-level alignment and protection card templates. - name: Catalog description: >- Discovery surface for the 25-entry Mnemom value catalog v1 (cards-as-primitive Phase 4). - name: Checkpoints description: Integrity checkpoints and proof artifacts. - name: Conscience Values description: Org-level conscience-value configuration. - name: Drift description: Drift detection and resolution. - name: Enforcement description: Enforcement-mode configuration and queries. - name: Governance description: Operator-actionable governance signals (ADR-048). - name: Integrity description: AIP integrity checkpoints and verdicts. - name: Intelligence description: Intelligence reports and queries. - name: Licensing description: License management. - name: Network description: >- Protection Network L4 thermometer read surface. Public-aggregate disclosure: any authenticated principal may read; rows carry no per-tenant identifiers. - name: OAuth description: >- OAuth 2.1 authorization-code + PKCE flow for MCP clients (MNE-328). Identity delegated to Supabase GoTrue; mnemom-api mints its own short-lived MCP-scoped tokens. Includes RFC 7591 dynamic client registration and RFC 7009 revocation. - name: On-Chain description: On-chain verification and proofs. - name: Organizations description: Org-level resources and management. - name: Policy description: Policy evaluation and configuration. - name: Postures description: Trust posture management (ADR-045). - name: Protection description: >- Protection manifest CRUD — canonical `/v1/protection//` surface across platform / org / team / agent (cards-as-primitive Phase 4). - name: Recipes description: >- Customer-facing detection-recipe surface — FN/FP reports. Distinct from the Admin recipe-promotion surface and the Internal seeding surface. - name: Reclassification description: Reclassification workflows. - name: Reputation description: Per-agent reputation scores. - name: Risk description: Risk assessment endpoints. - name: Safe House description: Safe House threat detection and quarantine. - name: Sideband description: Sideband detection queries (legacy; sunsetting). - name: Team Reputation description: Team-level reputation aggregates. - name: Teams description: Team-scope resources. - name: Tools description: >- Mnemom-side tools registry — per-tool class+domain+schema metadata (cards-as-primitive Phase 4). - name: Traces description: AP-Trace artifacts and queries. - name: Transparency description: >- Append-only public log of every canonical card identity ever composed. Signed Merkle root + per-row inclusion proofs (cards-as-primitive Phase 5). - name: Trust description: >- Protection Network L5 public-trust surface — security advisories, IoC feed (STIX 2.1), and platform-admin CMS for both. - name: Verification description: Trace verification endpoints. - name: Webhook Notifications description: Webhook event subscription management. - name: Webhooks description: Webhook delivery and lifecycle. - name: Misc description: >- Miscellaneous operator-facing endpoints (contact, enterprise inquiries, compliance). - name: Notifications description: >- Reactive notification channels — SSE stream + signed-webhook subscriptions for canonical card changes (cards-as-primitive Phase 5). paths: /policies/evaluate/historical: post: tags: - Policy summary: Evaluate policy against historical traces description: >- Evaluate a CLPI policy against historical AIP traces for an agent. Replays past tool invocations through the policy to identify what would have been blocked, escalated, or flagged. Useful for understanding the impact of a policy change before rolling it out. operationId: evaluatePolicyHistorical requestBody: required: true content: application/json: schema: type: object required: - policy - agent_id properties: policy: $ref: '#/components/schemas/Policy' agent_id: type: string description: Agent whose historical traces will be evaluated from: type: string format: date-time description: Start of time range for historical traces to: type: string format: date-time description: End of time range for historical traces limit: type: integer default: 100 description: Maximum number of traces to evaluate responses: '200': description: Historical evaluation result content: application/json: schema: type: object properties: evaluation: $ref: '#/components/schemas/PolicyEvaluationResult' traces_evaluated: type: integer time_range: type: object properties: from: type: string format: date-time to: type: string format: date-time '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] - ApiKeyAuth: [] components: schemas: Policy: type: object description: >- A complete CLPI policy document defining capability mappings, forbidden tools, escalation triggers, and enforcement defaults. properties: meta: $ref: '#/components/schemas/PolicyMeta' capability_mappings: type: object additionalProperties: $ref: '#/components/schemas/CapabilityMapping' description: Map of capability names to their definitions forbidden: type: array items: $ref: '#/components/schemas/ForbiddenRule' description: List of forbidden tool rules escalation_triggers: type: array items: $ref: '#/components/schemas/EscalationTrigger' description: List of escalation trigger definitions defaults: $ref: '#/components/schemas/PolicyDefaults' PolicyEvaluationResult: type: object description: Result of evaluating a CLPI policy against a set of tools or traces. properties: verdict: type: string enum: - pass - warn - fail description: Overall evaluation verdict violations: type: array items: $ref: '#/components/schemas/PolicyViolation' description: List of policy violations detected warnings: type: array items: type: object properties: tool: type: string message: type: string description: Non-blocking warnings about potential issues card_gaps: type: array items: type: object properties: capability: type: string missing_card_field: type: string suggestion: type: string description: Gaps between the policy and the alignment card coverage: type: number minimum: 0 maximum: 1 description: Fraction of tools covered by the policy (0.0 to 1.0) PolicyMeta: type: object description: >- Metadata for a CLPI policy including schema version, name, description, and scope. properties: schema_version: type: string description: Semantic version of the policy schema (e.g. '1.0.0') name: type: string description: Human-readable name of the policy description: type: string description: Detailed description of the policy's purpose scope: type: string enum: - agent - org - global description: Scope at which the policy applies CapabilityMapping: type: object description: Maps a named capability to specific tools and alignment card actions. properties: description: type: string description: Human-readable description of what this capability represents tools: type: array items: type: string description: List of tool identifiers that belong to this capability card_actions: type: array items: type: string description: Alignment card action types associated with this capability ForbiddenRule: type: object description: A rule that forbids tools matching a specific pattern. required: - pattern - reason properties: pattern: type: string description: Glob or regex pattern matching tool identifiers to forbid reason: type: string description: Human-readable reason why these tools are forbidden severity: type: string enum: - low - medium - high - critical default: high description: Severity level when a forbidden tool is invoked EscalationTrigger: type: object description: Defines a condition that triggers an escalation action. required: - condition - action properties: condition: type: string description: >- Expression or rule describing when this trigger fires (e.g. 'violation_count > 3') action: type: string enum: - notify - pause - block - require_approval description: Action to take when the condition is met reason: type: string description: Human-readable explanation of why this escalation exists PolicyDefaults: type: object description: >- Default enforcement behavior for tools and situations not explicitly covered by the policy. properties: unmapped_tool_action: type: string enum: - allow - warn - block - escalate default: warn description: Action to take when a tool is not mapped to any capability unmapped_severity: type: string enum: - low - medium - high - critical default: medium description: Severity level assigned to unmapped tool invocations fail_open: type: boolean default: false description: >- If true, allow actions when the policy engine is unavailable. If false, block by default. enforcement_mode: type: string enum: - observe - enforce - nudge default: observe description: Default enforcement mode for the policy grace_period_hours: type: integer default: 0 description: >- Number of hours to allow violations before enforcement kicks in (for new policy rollouts) PolicyViolation: type: object description: A single policy violation detected during evaluation. properties: type: type: string enum: - forbidden - unmapped - escalation - capability_mismatch description: Type of policy violation tool: type: string description: Tool identifier that triggered the violation capability: type: - string - 'null' description: Capability the tool was mapped to, if any rule: type: - string - 'null' description: The specific rule or pattern that was matched reason: type: string description: Human-readable explanation of the violation severity: type: string enum: - low - medium - high - critical description: Severity level of the violation Error: type: object description: >- Canonical error envelope (ADR-API-001 conv 1). `error` is always an object — never a bare string. Every 4xx/5xx response across the API conforms to this shape; the runtime helper is `src/http-errors.ts::buildErrorBody`. required: - error properties: error: type: object required: - code - message properties: code: type: string pattern: ^[a-z][a-z0-9_]*$ description: >- Stable, machine-matchable failure identifier (lowercase snake_case). Clients may branch on this; the string is part of the contract. **Status-class defaults** — emitted when no caller code is supplied (`errorCodeForStatus(status)`): `bad_request` (400), `unauthorized` (401), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `conflict` (409), `gone` (410), `precondition_failed` (412), `payload_too_large` (413), `unsupported_media_type` (415), `unprocessable_entity` (422), `precondition_required` (428), `rate_limited` (429), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). Fallback `error` for unmapped statuses. **Caller-supplied codes** — handlers may pass an explicit `code` for a specific failure class. Examples: `agent_not_found`, `invalid_hash_proof`, `already_linked`, `idempotency_conflict`, `feature_gated`, `schema_validation_failed`, `no_token`, `bad_canonical_payload`. **Care-framed sub-resource codes** — the cards-as-primitive surface passes its stable care code-string straight through as `error.code`. Examples: `if_match_absent`, `if_match_stale`, `if_match_malformed`, `primitive_validation_failed`. message: type: string description: Human-readable, care-framed explanation of the failure. details: description: >- Optional structured context for the failure (any JSON value: object, array, or primitive). Common shapes: validation findings list, idempotency-conflict diff, `{presented_etag, current_etag}` on a stale `If-Match`, etc. Mirrors the helper's `details?: unknown`. responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: >- Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 X-RateLimit-Limit: description: Requests permitted per window. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current window (0 on a 429). schema: type: integer minimum: 0 X-RateLimit-Reset: description: Unix epoch seconds at which the current window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: >- Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Supabase JWT token in Authorization: Bearer header' ApiKeyAuth: type: apiKey in: header name: X-Mnemom-Api-Key description: Mnemom API key (mnm_... format) ````