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

# Policy & Audit

> Real-time policy decisions and immutable audit event log for agentic cost-safety governance.

<Note>
  Both endpoints require **Bearer token** authentication.
</Note>

The Policy & Audit APIs are the enforcement and observability layer of the Agentic Control Plane.
**Policy check** gives any agent or tool an instant allow/deny/confirm decision before it takes
an action — the decision is deterministic, logged, and traceable. **Audit events** is the
append-only log of every decision made, so you can replay, audit, or export the full history of
agentic activity in your workspace.

***

## POST /v1/policy/check

Evaluate an agentic action against the workspace policy and AgentGuard rules. Returns a
structured decision (`allow` / `deny` / `confirm` / `approve`) with the factors that drove it and
the residual cost impact.

Use this before any write, deploy, or irreversible action so the agent can self-gate rather than
relying on human review after the fact.

<Note>
  **POST** `https://api.prysm1.com/v1/policy/check` · Auth required
</Note>

### Request Body

<ParamField body="workspace_id" type="string" required>
  The workspace whose policy to evaluate against.
</ParamField>

<ParamField body="action" type="string" required>
  Natural-language description of the action (e.g. `"deploy to production"`, `"delete user records"`).
</ParamField>

<ParamField body="action_kind" type="string">
  Structured action type: `edit` | `refactor` | `deploy` | `review` | `setup` | `delete`.
  Influences risk scoring independent of the free-text `action` field.
</ParamField>

<ParamField body="files_affected" type="string[]">
  Paths that will be read or written. Cross-checked against `protected_paths` in the workspace manifest.
</ParamField>

<ParamField body="commands" type="string[]">
  Shell commands the agent intends to run. Cross-checked against `forbidden_commands`.
</ParamField>

<ParamField body="estimated_cost_usd" type="number">
  Agent's estimate of the cost of this step. Used for budget-cap evaluation.
</ParamField>

<ParamField body="context" type="object">
  Arbitrary JSON context passed through to the decision record (useful for linking to handoff IDs,
  session IDs, or external ticket references).
</ParamField>

### Response

<ResponseField name="decision" type="string">
  `allow` | `deny` | `confirm` | `approve`. Maps directly to AgentGuard risk tiers:
  auto → allow, confirm → confirm, approve → approve, block → deny.
</ResponseField>

<ResponseField name="risk_score" type="integer">0–100 composite risk score.</ResponseField>
<ResponseField name="risk_tier" type="string">`auto` | `confirm` | `approve` | `block`</ResponseField>

<ResponseField name="factors" type="object[]">
  Ordered list of contributing factors: `id`, `label`, `weight`, `triggered` (bool).
</ResponseField>

<ResponseField name="reason" type="string">Human-readable explanation of the decision.</ResponseField>
<ResponseField name="event_id" type="string">The audit event ID for this check (`ae_...`).</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 timestamp.</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.prysm1.com/v1/policy/check \
    -H "Authorization: Bearer prysm_sk_..." \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "ws-myrepo",
      "action": "drop the users table and re-create from migration 42",
      "action_kind": "delete",
      "files_affected": ["migrations/42_recreate_users.sql"],
      "estimated_cost_usd": 0.02
    }'
  ```

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

  decision = prysm.policy.check(
      workspace_id="ws-myrepo",
      action="drop the users table and re-create from migration 42",
      action_kind="delete",
      files_affected=["migrations/42_recreate_users.sql"],
      estimated_cost_usd=0.02,
  )
  if decision["decision"] != "allow":
      raise RuntimeError(f"Policy blocked: {decision['reason']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — allow theme={null}
  {
    "decision": "allow",
    "risk_score": 28,
    "risk_tier": "auto",
    "factors": [
      {"id": "delete_action", "label": "Destructive action", "weight": 20, "triggered": true},
      {"id": "protected_path", "label": "Protected path touched", "weight": 15, "triggered": false}
    ],
    "reason": "Risk score 28 falls within the auto-allow tier.",
    "event_id": "ae_4f8a2b1c9e0d3f7a",
    "created_at": "2026-06-15T14:30:00+00:00"
  }
  ```

  ```json 200 — deny theme={null}
  {
    "decision": "deny",
    "risk_score": 91,
    "risk_tier": "block",
    "factors": [
      {"id": "delete_action", "label": "Destructive action", "weight": 20, "triggered": true},
      {"id": "forbidden_command", "label": "Forbidden command", "weight": 40, "triggered": true},
      {"id": "protected_path", "label": "Protected path touched", "weight": 15, "triggered": true}
    ],
    "reason": "Risk score 91 exceeds the block threshold (86). Action denied.",
    "event_id": "ae_9c1d5e2f8b4a7c3d",
    "created_at": "2026-06-15T14:31:00+00:00"
  }
  ```
</ResponseExample>

***

## GET /v1/audit/events

Paginated, filterable log of every policy check, handoff, and AgentGuard decision in a workspace.
Immutable — entries are append-only and cannot be deleted via the API.

<Note>
  **GET** `https://api.prysm1.com/v1/audit/events` · Auth required
</Note>

### Query Parameters

<ParamField query="workspace_id" type="string">
  Filter to a specific workspace. Omit to return events across all your workspaces.
</ParamField>

<ParamField query="event_type" type="string">
  Filter by event type: `policy_check` | `handoff_created` | `agent_plan` | `agent_record`.
</ParamField>

<ParamField query="decision" type="string">
  Filter policy\_check events by decision: `allow` | `deny` | `confirm` | `approve`.
</ParamField>

<ParamField query="since" type="string">
  ISO 8601 datetime — return events created at or after this time.
</ParamField>

<ParamField query="until" type="string">
  ISO 8601 datetime — return events created before this time.
</ParamField>

<ParamField query="limit" type="integer">
  Max results per page (1–200; default 50).
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from `next_cursor` in a prior response.
</ParamField>

### Response

<ResponseField name="object" type="string">`audit.events`</ResponseField>
<ResponseField name="count" type="integer">Number of events in this page.</ResponseField>
<ResponseField name="has_more" type="boolean">Whether more pages exist.</ResponseField>
<ResponseField name="next_cursor" type="string | null">Pass as `cursor` in the next request.</ResponseField>

<ResponseField name="data" type="object[]">
  Array of event objects. Each has `id`, `event_type`, `workspace_id`, `actor`, `payload`,
  `created_at`. Policy check events also include `decision`, `risk_score`, `risk_tier`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.prysm1.com/v1/audit/events?workspace_id=ws-myrepo&event_type=policy_check&decision=deny&limit=20" \
    -H "Authorization: Bearer prysm_sk_..."
  ```

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

  page = prysm.audit.events(
      workspace_id="ws-myrepo",
      event_type="policy_check",
      decision="deny",
      limit=20,
  )
  for event in page["data"]:
      print(event["id"], event["created_at"], event["payload"]["action"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "object": "audit.events",
    "count": 2,
    "has_more": false,
    "next_cursor": null,
    "data": [
      {
        "id": "ae_9c1d5e2f8b4a7c3d",
        "event_type": "policy_check",
        "workspace_id": "ws-myrepo",
        "actor": "agent:claude-code",
        "decision": "deny",
        "risk_score": 91,
        "risk_tier": "block",
        "payload": {
          "action": "drop the users table",
          "action_kind": "delete",
          "files_affected": ["migrations/42_recreate_users.sql"]
        },
        "created_at": "2026-06-15T14:31:00+00:00"
      },
      {
        "id": "ae_4f8a2b1c9e0d3f7a",
        "event_type": "policy_check",
        "workspace_id": "ws-myrepo",
        "actor": "agent:claude-code",
        "decision": "allow",
        "risk_score": 28,
        "risk_tier": "auto",
        "payload": {
          "action": "update auth middleware",
          "action_kind": "edit"
        },
        "created_at": "2026-06-15T14:30:00+00:00"
      }
    ]
  }
  ```
</ResponseExample>