API Reference

The action-check API your agents call before they act. See How It Works for concepts.

Authentication

Create a service account in Settings → Service Accounts; copy the API key (shown once). Send it as a bearer token. Find your policy ID on the policy's page.

Authorization: Bearer <PATHREADER_API_KEY>
Content-Type: application/json

POST /api/v1/check

Evaluate one proposed action against a policy's active version.

Request

curl -X POST https://app.pathreader.ai/api/v1/check \
  -H "Authorization: Bearer $PATHREADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "<your-policy-id>",
    "action_type": "Bash",
    "actor_id": "claude-code-agent",
    "payload": { "tool": "Bash", "command": "git push origin main" }
  }'
  • policy_id (required) — evaluates the policy's active version.
  • payload — structured action (e.g. tool, command, file_path). Either payload or proposed_action_summary (plain language) is required.
  • actor_id / action_type (optional) — appear in the audit log; improve matching.

Response

{
  "audit_id": "aud_01jx2k9m3p",
  "decision": "block",
  "runtimeMode": "OBSERVE",
  "coverage_gap": false,
  "matched_rule_count": 1,
  "violations": [
    {
      "rule_id": "rule_...",
      "rule_name": "Block git push to main branch",
      "severity": "block",
      "reason": "Direct pushes to protected branches are not permitted.",
      "citation": "Engineers must merge to main via reviewed pull request.",
      "recommended_next_step": "Open a pull request instead of pushing to main."
    }
  ],
  "policy_name": "Eng Coding Agent rules",
  "policy_version": 3,
  "evaluated_at": "2026-06-13T12:00:00.000Z"
}

On allow, violations is empty. Full field list: audit_id, decision, runtimeMode, coverage_gap, matched_rule_count, synthesis_current, violations[], near_misses[], policy_name, policy_version, evaluated_at.

Decisions

allow — no rule fired. Proceed.

block — a block-severity rule fired. Stop the action.

flag — an escalate rule fired, or a coverage gap (coverage_gap: true, no rule applied). In ENFORCE mode, honor flags as blocks.

Errors & rate limits

  • E002 — policy version still compiling; retry shortly.
  • E003 — policy version not found in the engine; re-activate.
  • E004 — no LLM service configured for natural-language normalization; send structured payload.
  • Rate limit: 1,000 checks/hour per service account. Responses include X-RateLimit-Remaining / X-RateLimit-Reset.

Treat network/5xx errors as fail-open (proceed) or fail-closed — your choice; the reference hook fails open.

Claude Code / VS Code hook

The fastest integration: a PreToolUse hook that checks every tool call. Your PathReader contact provides install-hook.sh; run it with your API key and restart Claude Code (VS Code: Cmd+Shift+P → Developer: Reload Window). See How It Works → Agent Hook.