# HIPAA Agent -- Complete API Reference

> Full technical reference for all protocols, tools, and endpoints.
> For a summary, see https://hipaaagent.ai/llms.txt
> Agent: HIPAA Agent by Sentinel Health Compliance, LLC -- hipaaagent.ai
> Contact: compliance@hipaaagent.ai
> Version: 2026-03-15

---

## 1. Authentication

All authenticated requests use one of the following methods:

### API Key (primary)
Header: `X-API-Key: <key>`
Format: `ha_...` (SHA-256 hashed, looked up in api_keys table)
Get a free key: https://hipaaagent.ai/developers

### OAuth2 Client Credentials
Enterprise integrations can use OAuth2 client credentials flow.

### Bearer JWT
Header: `Authorization: Bearer <token>`
Used for GPT Actions, customer portal sessions, and admin/cron access (higher rate limit: 600 RPM).

### Public Endpoints (no auth required)
- `GET /api/reputation` -- Platform reputation stats
- `GET /api/verify/{npi}` -- Compliance verification badge
- `GET /api/verify/anchor/{date}` -- Blockchain anchor proof
- `GET /api/health` -- System health check
- `GET /api/threat-intel` -- Threat intelligence feed
- `GET /api/breach/probability?npi=X` -- Breach probability
- `POST /api/vendor/risk` -- Vendor risk check
- `POST /api/validate/transfer` -- Workflow validation
- `GET /api/compliance/controls?npi=X` -- Control assessment
- `GET /api/compliance/state/{npi}` -- Compliance readiness
- `GET /api/compliance/delta?npi=X&since=DATE` -- Control delta

### API Key Types

| Type | Credits | Rate Limit | Access |
|------|---------|------------|--------|
| `free` | 500 | 60 req/min | Public APIs, basic scanning |
| `starter` | 5,000 | 120 req/min | + Reports, findings |
| `professional` | 25,000 | 300 req/min | + BAA, policies, SRA |
| `platform` | 100,000 | 600 req/min | + Batch scans, all tools |
| `msp` | 250,000 | 600 req/min | + Multi-tenant management |
| `api` | Custom | Custom | Full enterprise access |

---

## 2. Rate Limiting

Rate limits are applied per API key.

| Context | Limit |
|---------|-------|
| Default per-key RPM | 60 |
| Admin/Bearer RPM | 600 |
| `scan_practice` (MCP) | 5 per NPI per 15 minutes |
| `/api/lookup` | 10 per IP per 15 minutes |
| `/api/scan/lite` | 10 per IP per 15 minutes |
| `/api/lookup/verify` | 3 OTPs per NPI per hour |

### Rate Limit Headers
Every response includes:
- `X-RateLimit-Limit` -- maximum requests per window
- `X-RateLimit-Remaining` -- remaining requests in current window
- `X-RateLimit-Reset` -- Unix timestamp when the window resets

### 429 Response Format
```
{
  "error": "rate_limit_exceeded",
  "retry_after_seconds": 45,
  "limit": 60
}
```

---

## 3. MCP Tools (36 total)

Endpoint: `POST /api/mcp`
Transport: Streamable HTTP (JSON-RPC 2.0)
Server name: `hipaa-agent` version `2.0.0`

Required headers:
- `Content-Type: application/json`
- `Accept: application/json, text/event-stream`
- `X-API-Key: <key>`

Tool invocation via standard MCP `tools/call` method:
```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": { ... }
  }
}
```

### OAuth Scopes
| Scope | Description |
|-------|-------------|
| `scan:read` | Read scan results, grades, compliance data |
| `scan:write` | Trigger new scans |
| `report:read` | Access reports, audit logs, evidence packages |
| `breach:read` | Access breach intelligence data |
| `internal:read` | Read internal network scan results |
| `internal:write` | Deploy internal scanner agents |
| `practice:read` | Read practice info, outreach status |
| `platform:read` | Read training, BAA tracking, incidents |
| `platform:write` | Log incidents, manage webhooks |
| `baa:write` | Generate and execute BAAs |
| `policy:read` | Access HIPAA policy documents |
| `sra:write` | Start Security Risk Assessments |

API key auth (no scopes) is always allowed for backward compatibility.

### Tool Annotations Legend
| Annotation | Meaning |
|------------|---------|
| `readOnlyHint` | Tool does not modify any server-side state |
| `destructiveHint` | Tool may delete or irreversibly alter data |
| `idempotentHint` | Calling multiple times with same input produces same result |
| `openWorldHint` | Tool interacts with external systems beyond HIPAA Agent |

---

### Group 1: Scanning (3 tools)

#### scan_practice
- Credits: 150
- Scope: `scan:write`
- Annotations: readOnly=false, destructive=false, idempotent=false, openWorld=true
- Description: Trigger a fresh HIPAA compliance scan for a healthcare practice. Always dispatches a new 70+ control scan via VPS. Returns a job_id for polling via get_scan_status. Optionally specify notification_email to receive the PDF report when the scan completes.
- Parameters:
  - `npi` (string, required) -- 10-digit National Provider Identifier
  - `domain` (string, optional) -- Practice website domain (e.g. exampleclinic.com). If omitted, looked up from existing scan data.
  - `notification_email` (string, optional) -- Email address to send the completed PDF report to.
- Response fields: job_id, npi, domain, status, credits_remaining

#### batch_scan
- Credits: 150 per practice
- Scope: `scan:write`
- Annotations: readOnly=false, destructive=false, idempotent=false, openWorld=true
- Description: Dispatch fresh HIPAA compliance scans for multiple practices at once. Each practice costs 150 credits. If insufficient credits for the full batch, the entire request is rejected. Max 50 practices per call.
- Parameters:
  - `practices` (array, required) -- Array of practice objects (max 50). Each object:
    - `npi` (string, required) -- 10-digit NPI
    - `domain` (string, optional) -- Practice website domain
    - `notification_email` (string, optional) -- Email to send the completed report to
- Response fields: dispatched, failed, total_credits_charged, credits_remaining, results[]

#### get_scan_status
- Credits: 25
- Scope: `scan:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Check the status of the latest scan for a practice. Returns grade, scan date, and whether data is available.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, status, practice_name, website, grade, hipaa_agent_compliance_score, hipaa_risk_score, category_scores, severity, scanned_at, age_days, has_comprehensive_data, credits_remaining

---

### Group 2: Reports & Evidence (4 tools)

#### get_compliance_score
- Credits: 25
- Scope: `scan:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get the HIPAA Agent Compliance Score™ breakdown for a practice. Returns overall grade, numerical score, and per-category scores across 10 compliance categories.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, practice_name, grade, hipaa_agent_compliance_score, hipaa_risk_score, category_scores, scanned_at, credits_remaining

#### get_report
- Credits: 25
- Scope: `report:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get the full compliance report for a practice including all findings, severity breakdown, grade, and HIPAA section citations.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, practice (name, website, city, state), grade, severity, findings_summary (critical, high, medium, low, total), findings[] (code, severity, title, description, hipaa_section, remediation), scanned_at, credits_remaining

#### get_audit_log
- Credits: 25
- Scope: `report:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=true
- Description: Retrieve the SHA-256 hash chain audit trail for a practice. Returns timestamped, tamper-evident log entries for all compliance actions.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: entries[] (event_type, event_category, title, severity, details, hash, created_at), total, credits_remaining

#### get_evidence_package
- Credits: 25
- Scope: `report:read`
- Premium: Requires active subscription or platform/msp/api key
- Annotations: readOnly=false, destructive=false, idempotent=true, openWorld=true
- Description: Compile a 10-component evidence package for auditors and insurers. Includes scan results, policy attestations, training records, BAA ledger, and audit trail. Async -- returns job_id.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: job_id, status, credits_remaining

---

### Group 3: Documents (3 tools)

#### generate_baa
- Credits: 25
- Scope: `baa:write`
- Premium: Requires active subscription or platform/msp/api key
- Annotations: readOnly=false, destructive=false, idempotent=false, openWorld=true
- Description: Generate a Business Associate Agreement for a vendor.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI of the covered entity (practice)
  - `vendor_name` (string, required) -- Name of the business associate / vendor
  - `services_description` (string, required) -- Description of services the vendor provides that involve PHI
  - `vendor_email` (string, optional) -- Vendor email; if provided, the BAA is sent for signing
  - `vendor_contact_name` (string, optional) -- Name of vendor contact person
  - `agreement_type` (string, optional) -- `baa` (default) or `subcontractor_baa`
  - `risk_level` (string, optional) -- `low`, `standard` (default), or `high`
  - `effective_date` (string, optional) -- Effective date (ISO 8601)
  - `expiration_date` (string, optional) -- Expiration date (ISO 8601)
- Response fields: baa_id, vendor_name, agreement_type, status, credits_remaining

#### get_policies
- Credits: 25
- Scope: `policy:read`
- Premium: Requires active subscription or platform/msp/api key
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get HIPAA policy documents generated for a practice.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, policies[] (id, policy_key, policy_name, hipaa_section, status, created_at), total, credits_remaining

#### generate_sra
- Credits: 500
- Scope: `sra:write`
- Premium: Requires active subscription or platform/msp/api key
- Annotations: readOnly=false, destructive=false, idempotent=false, openWorld=true
- Description: Initiate a HIPAA Security Risk Assessment. Returns the first batch of questions for the respondent to answer.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI of the practice
  - `respondent_email` (string, required) -- Email of the person completing the SRA
  - `respondent_name` (string, required) -- Full name of the person completing the SRA
  - `respondent_role` (string, optional) -- Role/title of the respondent (e.g. Practice Manager, HIPAA Officer)
  - `practice_name` (string, optional) -- Practice name (auto-looked up from scan data if omitted)
- Response fields: sra_id, npi, respondent_email, status, questions_count, credits_remaining

---

### Group 4: Breach Intelligence (3 tools)

#### get_breach
- Credits: 25
- Scope: `breach:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Check if a practice has been involved in any known HIPAA breaches reported to HHS. Matches by practice name and state.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, practice_name, matched (boolean), breaches[] (entity, individuals_affected, date, type, location), state_breaches_sampled, credits_remaining

#### get_breach_score
- Credits: 25
- Scope: `breach:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Calculate a breach exposure risk score for a practice based on breach history, breached credentials, and industry benchmarks.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, practice_name, breach_risk_score (0-100), risk_level (LOW/MEDIUM/HIGH/CRITICAL), breached_email_count, risk_factors[] (factor, impact, points), credits_remaining

#### get_breach_probability
- Credits: 25
- Scope: `breach:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=true
- Description: Calculate breach probability for a practice. Model: HHS base rate by specialty, adjusted by security grade penalty, gap penalties (no MFA +8%, no encryption +12%, flat network +15%, no backups +10%), and prior breach history 3x multiplier.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, breach_probability, confidence, risk_factors[], base_rate_pct, grade_penalty_pct, gap_penalty_pct, prior_breach_multiplier, industry_average_pct, percentile, security_grade, based_on_scan_date, credits_remaining

---

### Group 5: Internal Network (3 tools)

#### trigger_internal_scan
- Credits: 25
- Scope: `internal:write`
- Annotations: readOnly=false, destructive=false, idempotent=false, openWorld=true
- Description: Generate a deploy token for the internal network scanner agent. Returns an API key and installation instructions for deploying the agent inside a practice network.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: agent_id, status, deploy_token, credits_remaining

#### get_internal_scan_status
- Credits: 25
- Scope: `internal:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Check the status of the internal network scan agent deployment and whether results have been received.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, status, internal_scan_deployed (boolean), last_results_at, agent_version, credits_remaining

#### get_internal_findings
- Credits: 25
- Scope: `internal:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=true
- Description: Get the latest internal network scan results including encryption status, MFA compliance, network segmentation, patch levels, and endpoint security.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: findings[] (code, category, severity, title, description, remediation, hipaa_sections), credits_remaining

---

### Group 6: Practice Info (3 tools)

#### lookup_practice
- Credits: 25
- Scope: `practice:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=true
- Description: Look up a healthcare practice by NPI number. Always fetches from the NPPES registry and augments with HIPAA Agent scan data if available. Returns provider name, specialty, address, and compliance grade.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, found, provider_type, practice_name, specialty, address (line1, line2, city, state, zip, phone), enumeration_date, status, scan_data (website, grade, severity, last_scanned), credits_remaining

#### get_outreach_status
- Credits: 25
- Scope: `practice:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get the outreach and drip campaign status for a practice. Returns email send history, drip stage, and engagement data.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, drip (stage, status, enrolled_at, last_sent_at, next_send_at), emails_sent[] (to, sent_at, template, status), total_emails, credits_remaining

#### get_practice_summary
- Credits: 25
- Scope: `practice:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get a comprehensive summary of a practice combining scan results, compliance score, findings count, breach history, and internal scan status.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, found, practice (name, website, city, state), compliance (grade, numerical_score, severity, total_findings), internal_scan (deployed, last_results_at), breach_exposure (breached_emails), last_scanned, credits_remaining

---

### Group 7: Platform (4 tools)

#### get_training_status
- Credits: 25
- Scope: `platform:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get staff training completion records for a practice. Returns staff members and their training course completions including scores and dates.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, staff_count, training_summary (total_courses, completed, completion_rate), staff[] (id, name, email, role, courses[]), credits_remaining

#### get_vendor_baa_list
- Credits: 25
- Scope: `platform:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get vendor Business Associate Agreement tracking records for a practice. Returns all vendor BAAs with status, dates, and contact info.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, summary (total, active, pending, expired, expiring_soon), vendor_baas[] (id, vendor_name, service_provided, status, signed_date, expiration_date, contact_name, contact_email), credits_remaining

#### log_incident
- Credits: 25
- Scope: `platform:write`
- Annotations: readOnly=false, destructive=false, idempotent=false, openWorld=false
- Description: Log a HIPAA security or privacy incident for a practice. Creates an incident report with type, description, and severity. Returns the incident ID for tracking.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
  - `incident_type` (string, required) -- Type: breach, unauthorized_access, device_loss, phishing, policy_violation, system_failure, other
  - `description` (string, required) -- Detailed description of the incident
  - `severity` (string, optional) -- low, medium (default), high, critical
- Response fields: npi, incident_id, incident_type, severity, status, reported_at, credits_remaining

#### get_incidents
- Credits: 25
- Scope: `platform:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get incident history for a practice. Returns all logged security and privacy incidents with status, severity, and resolution dates.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, summary (total, open, in_progress, resolved), incidents[] (id, type, description, severity, status, reported_at, resolved_at), credits_remaining

---

### Group 8: Controls & Compliance (11 tools)

#### get_compliance_delta
- Credits: 25
- Scope: `scan:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get compliance controls that changed status since a given date. Shows improved and regressed controls with before/after comparison.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
  - `since` (string, required) -- ISO date to compare from (e.g. 2026-01-01)
- Response fields: npi, since, changes[] (control_id, control_name, hipaa_section, previous_status, current_status, previous_risk_score, current_risk_score, changed), total_changes, improved, regressed, credits_remaining

#### check_vendor
- Credits: 25
- Scope: `scan:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=true
- Description: Check vendor risk profile including breach history, BAA coverage, and security score. Input vendor_name or domain.
- Parameters:
  - `vendor_name` (string, optional) -- Vendor/business associate name (at least one of vendor_name or domain required)
  - `domain` (string, optional) -- Vendor website domain
- Response fields: vendor_name, domain, risk_rating, security_score, breach_history, baa_coverage, credits_remaining

#### get_compliance_state
- Credits: 25
- Scope: `scan:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get the HIPAA compliance readiness state for a practice. Tracks 13 requirements against the May 2026 deadline. Returns state (compliant/near_compliant/in_progress/early_stage/not_started), completed count, next action, and per-requirement status.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, state, completed_controls, total_controls, next_action, deadline, days_remaining, security_grade, requirements[] (id, name, status, source), credits_remaining

#### subscribe_webhook
- Credits: 25
- Scope: `platform:write`
- Annotations: readOnly=false, destructive=false, idempotent=false, openWorld=true
- Description: Register a webhook URL to receive HIPAA compliance event notifications. Events: breach_detected, score_dropped, baa_expiring, scan_completed, control_failed, sra_expired. Payloads signed with HMAC-SHA256.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI to monitor
  - `url` (string, required) -- HTTPS URL to receive webhook POST payloads
  - `events` (string[], required) -- Event types to subscribe to
- Response fields: subscription (id, npi, url, events, secret, active, created_at), credits_remaining

#### list_webhooks
- Credits: 25
- Scope: `platform:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: List active webhook subscriptions for a practice.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, subscriptions[] (id, npi, url, events, active, created_at, last_triggered, failure_count), total, credits_remaining

#### validate_workflow
- Credits: 25
- Scope: `scan:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Validate whether a data workflow is HIPAA-compliant. Synchronous guardrail -- returns allowed/denied with risk score, missing controls, and HIPAA citations. No prior scan required. Zero PHI.
- Parameters:
  - `workflow_type` (string, required) -- Type: data_transfer, cloud_migration, vendor_share, backup, messaging
  - `data_type` (string, required) -- Data classification: phi, de_identified, limited_data_set, non_phi
  - `destination` (string, required) -- Target: cloud_us, cloud_intl, on_prem, vendor, email, fax, portal
  - `controls_applied` (string[], required) -- Controls in place (e.g. encryption_in_transit, baa, mfa)
  - `npi` (string, optional) -- Optional NPI for practice context
- Response fields: allowed (boolean), risk_level, risk_score, required_actions[], hipaa_citations[], workflow_type, data_type, destination, controls_required, controls_applied, controls_missing, evaluated_in_ms, credits_remaining

#### get_controls
- Credits: 25
- Scope: `scan:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get HIPAA/NIST control-level assessment for a practice. Maps scan findings to 13 standardized controls with pass/fail/partial status, risk scores, and required actions.
- Parameters:
  - `npi` (string, required) -- 10-digit NPI
- Response fields: npi, total_controls, passed, failed, partial, controls[] (control_id, control_name, hipaa_section, status, risk_score, findings[], action_required), credits_remaining

#### execute_agent_baa
- Credits: 25
- Scope: `baa:write`
- Annotations: readOnly=false, destructive=false, idempotent=false, openWorld=true
- Description: Execute a digital Business Associate Agreement between two healthcare practices. Verifies both parties have passing compliance grades (C or above), creates a signed BAA with SHA-256 digital signature, and logs to the audit trail.
- Parameters:
  - `initiator_npi` (string, required) -- 10-digit NPI of the initiating party
  - `counterparty_npi` (string, required) -- 10-digit NPI of the counterparty
  - `services_description` (string, optional) -- Description of services involving PHI (default: Healthcare data processing services)
  - `effective_date` (string, optional) -- BAA effective date (ISO 8601, default: today)
  - `expiration_date` (string, optional) -- BAA expiration date (ISO 8601, default: 1 year from today)
- Response fields: baa_id, status, initiator (npi, grade), counterparty (npi, grade), effective_date, expiration_date, signed_at, digital_signature, signature_algorithm, agreement_ids, credits_remaining

#### get_model_insights
- Credits: 25
- Scope: `scan:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get HIPAA Agent data intelligence model stats -- vulnerability patterns discovered, remediation effectiveness tracking, breach calibration coefficients, specialty benchmarks, and state coverage.
- Parameters: none
- Response fields: practices_monitored, total_scans_completed, total_findings, grade_distribution, most_common_findings[], average_score, states_covered, specialties_covered, breach_correlation, credits_remaining

#### get_state_coverage
- Credits: 25
- Scope: `scan:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get scanning coverage by US state -- total NPIs in registry, scanned count, average grade per state.
- Parameters:
  - `state` (string, optional) -- Filter to a specific 2-letter state code (e.g., CA, TX). Omit for all states.
- Response fields: states[] (state, status, npis_total, npis_scanned, scans_with_grade, grade_distribution), total_states, credits_remaining

#### get_threat_intel
- Credits: 25
- Scope: `scan:read`
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get recent healthcare threat intelligence alerts from FBI Watchdog, HHS HC3, CISA KEV, and MS-ISAC. Returns alerts with severity, healthcare relevance scores, and source attribution.
- Parameters:
  - `source` (string, optional) -- Filter by source: FBI_Watchdog, HHS_HC3, CISA_KEV, MS_ISAC
  - `severity` (string, optional) -- Filter by severity: critical, high, medium, low
  - `days` (number, optional) -- Lookback period in days (default 30, max 90)
  - `limit` (number, optional) -- Max results (default 50, max 100)
- Response fields: alerts[] (id, source, alert_type, severity, title, description, category, cve_id, is_ransomware, healthcare_relevance_score, source_url, affected_sectors, published_at, ingested_at), stats, pagination, credits_remaining

---

### Group 9: Free Tools (2 tools, no auth required)

#### get_reputation
- Credits: 0 (free, no auth)
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get HIPAA Agent verified reputation stats -- total scans, unique practices, documents generated, breaches tracked, uptime, and SHA-256 data integrity hash.
- Parameters: none
- Response fields: agent, version, powered_by, stats (total_scans, unique_practices, baas_generated, sras_completed, policies_generated, breaches_tracked, findings_detected, avg_response_ms, uptime_pct), dimensions (reliability, capability_accuracy, protocol_compliance, data_freshness), verified_at, data_hash, signature, signature_algorithm, verification_url, blockchain_anchor (date, root_hash, tx_hash, chain, basescan_url, status)

#### get_blockchain_anchor
- Credits: 0 (free, no auth)
- Annotations: readOnly=true, destructive=false, idempotent=true, openWorld=false
- Description: Get the blockchain anchor proof for a specific date. Returns the SHA-256 root hash of all audit events from that date, the Base L2 transaction hash, and a Basescan verification link. Proves compliance records have not been tampered with.
- Parameters:
  - `date` (string, required) -- Date in YYYY-MM-DD format
- Response fields: date, root_hash, tx_hash, block_number, chain, event_count, status, anchored_at, basescan_url, verification (method, chain, explorer)

---

## 4. JSON-RPC 2.0 Methods (28 methods)

Endpoint: `POST /api/a2a`
Version: `"2.0"`
Content-Type: `application/json`
Auth: `X-API-Key` header

JSON-RPC mode is activated when the request body contains `"jsonrpc": "2.0"`.

### Request Format
```
{
  "jsonrpc": "2.0",
  "method": "hipaa.grade",
  "params": { "npi": "1234567890" },
  "id": 1
}
```

### Batch Support
Send an array of JSON-RPC requests; responses are processed in parallel and returned as an array.

### Notifications
Omit `id` to fire-and-forget (HTTP 204 for single, omitted from batch array).

### Error Codes
| Code | Name | Description |
|------|------|-------------|
| `-32700` | Parse error | Request body is not valid JSON |
| `-32600` | Invalid Request | Missing jsonrpc field, missing method, or empty batch |
| `-32601` | Method not found | Method name does not match any hipaa.* method |
| `-32602` | Invalid params | Missing or malformed parameters (e.g., NPI not 10 digits) |
| `-32603` | Internal error | Server-side processing failure or tier access denied |

### Method Map

| JSON-RPC Method | REST Task | Type |
|-----------------|-----------|------|
| `hipaa.scan` | hipaa_scan | Cacheable Async |
| `hipaa.grade` | hipaa_grade | Sync |
| `hipaa.breach_check` | hipaa_breach_check | Sync |
| `hipaa.breach` | hipaa_breach_check (alias) | Sync |
| `hipaa.findings` | hipaa_findings | Sync |
| `hipaa.report` | hipaa_report | Cacheable Async |
| `hipaa.sra` | hipaa_sra | Premium Async |
| `hipaa.policies` | hipaa_policies | Premium Async |
| `hipaa.training` | hipaa_training | Premium Async |
| `hipaa.baa` | hipaa_baa | Premium Async |
| `hipaa.evidence` | hipaa_evidence | Premium Async |
| `hipaa.intelligence` | hipaa_intelligence | Premium Async |
| `hipaa.audit_ledger` | hipaa_audit_ledger | Sync |
| `hipaa.batch` | hipaa_scan (batch) | Async |
| `hipaa.validate_workflow` | hipaa_validate_workflow | Sync |
| `hipaa.breach_probability` | hipaa_breach_probability | Sync |
| `hipaa.vendor_risk` | hipaa_vendor_risk | Sync |
| `hipaa.check_vendor` | hipaa_vendor_risk (alias) | Sync |
| `hipaa.get_controls` | hipaa_get_controls | Sync |
| `hipaa.subscribe_webhook` | hipaa_subscribe_webhook | Sync |
| `hipaa.list_webhooks` | hipaa_list_webhooks | Sync |
| `hipaa.compliance_state` | hipaa_compliance_state | Sync |
| `hipaa.compliance_delta` | hipaa_compliance_delta | Sync |
| `hipaa.baa_execute` | hipaa_baa_execute | Sync |
| `hipaa.reputation` | hipaa_reputation | Sync |
| `hipaa.model_insights` | hipaa_model_insights | Sync |
| `hipaa.state_coverage` | hipaa_state_coverage | Sync |
| `hipaa.threat_intel` | hipaa_threat_intel | Sync |

### Sync Methods
Return data immediately from cached Supabase records: hipaa.grade, hipaa.breach_check, hipaa.breach, hipaa.findings, hipaa.audit_ledger, hipaa.validate_workflow, hipaa.breach_probability, hipaa.vendor_risk, hipaa.check_vendor, hipaa.get_controls, hipaa.compliance_state, hipaa.compliance_delta, hipaa.subscribe_webhook, hipaa.list_webhooks, hipaa.baa_execute, hipaa.reputation, hipaa.model_insights, hipaa.state_coverage, hipaa.threat_intel.

### Cacheable Async Methods
Check for cached data (<30 days old). If cached, return immediately. If not, dispatch background job and return job_id: hipaa.scan, hipaa.report.

### Premium Async Methods
Always create background jobs. Require paid subscription tier: hipaa.sra, hipaa.policies, hipaa.training, hipaa.baa, hipaa.evidence, hipaa.intelligence.

### Key Method Parameters

**hipaa.grade** -- params: { npi (string, required) }
Returns: score, grade, categories[], as_of

**hipaa.findings** -- params: { npi (string, required) }
Returns: findings[] (code, severity, title, description, citation, remediation), total

**hipaa.breach_check** -- params: { npi (string, required) }
Returns: matched (boolean), breaches[] (entity, individuals_affected, breach_date, type, location)

**hipaa.audit_ledger** -- params: { npi (string, required) }
Returns: entries[] (event_type, event_category, title, severity, details, hash, created_at), total

**hipaa.scan** -- params: { npi (string, required), domain (string, optional), force_fresh (boolean, optional), notification_email (string, optional) }
Returns (cached): compliance_score, grade, findings[], critical_findings, cached, generated_at
Returns (async): job_id, status, poll

**hipaa.batch** -- params: { practices[] (array, required, max 50), each with npi (required), domain (optional), notification_email (optional) }
Returns: dispatched, results[] (npi, job_id, status)

**hipaa.report** -- params: { npi (string, required) }
Returns: job_id, status

**hipaa.sra** -- params: { npi (string, required), respondent_email (string, required), respondent_name (string, required), respondent_role (string, optional), practice_name (string, optional) }

**hipaa.policies** -- params: { npi (string, required), practice_name (optional), specialty (optional), city (optional), state (optional), website (optional), employee_count (number, optional), callback_url (optional) }

**hipaa.training** -- params: { npi (string, required), employees[] (array, required, each with name and email required, role optional), modules[] (string[], optional) }

**hipaa.baa** -- params: { npi (string, required), vendor_name (string, required), services_description (string, required), vendor_email (optional), vendor_contact_name (optional), agreement_type (optional), risk_level (optional), effective_date (optional), expiration_date (optional) }

**hipaa.evidence** -- params: { npi (string, required), practice_name (optional), callback_url (optional) }

**hipaa.intelligence** -- params: { npi (string, required), callback_url (optional) }

**hipaa.validate_workflow** -- params: { workflow_type (required), data_type (required), destination (required), controls_applied (string[], required), npi (optional) }

**hipaa.breach_probability** -- params: { npi (string, required) }

**hipaa.vendor_risk** / **hipaa.check_vendor** -- params: { vendor_name (string, conditional), domain (string, conditional), npi (optional) }

**hipaa.get_controls** -- params: { npi (string, required) }

**hipaa.compliance_state** -- params: { npi (string, required) }

**hipaa.compliance_delta** -- params: { npi (string, required), since (string, required) }

**hipaa.baa_execute** -- params: { initiator_npi (string, required), counterparty_npi (string, required), services_description (optional), effective_date (optional), expiration_date (optional) }

**hipaa.subscribe_webhook** -- params: { npi (string, required), url (string, required), events (string[], required) }

**hipaa.list_webhooks** -- params: { npi (string, required) }

**hipaa.reputation** -- params: {} (none required)

**hipaa.model_insights** -- params: {} (none required)

**hipaa.state_coverage** -- params: { state (string, optional) }

**hipaa.threat_intel** -- params: { source (optional), severity (optional), days (number, optional) }

---

## 5. REST Tasks (16 tasks)

Endpoint: `POST /api/a2a`
Auth: `X-API-Key` header

### Request Format
```
{
  "task": "hipaa_grade",
  "input": { "npi": "1234567890" },
  "callback_url": "https://yourapp.com/webhook",
  "request_id": "idempotency-key"
}
```

### Valid Tasks

| Task | Type | Description |
|------|------|-------------|
| `hipaa_scan` | Async | Trigger fresh 70+ control HIPAA compliance scan |
| `hipaa_grade` | Sync | Get HIPAA Agent Compliance Score™ and letter grade |
| `hipaa_breach_check` | Sync | Check HHS breach database for practice matches |
| `hipaa_findings` | Sync | Get all findings with severity, citations, remediation |
| `hipaa_report` | Async | Generate full PDF risk posture report |
| `hipaa_sra` | Async | Initiate Security Risk Assessment |
| `hipaa_policies` | Async | Generate HIPAA policy documents |
| `hipaa_training` | Async | Deploy staff training modules |
| `hipaa_baa` | Async | Generate Business Associate Agreement |
| `hipaa_evidence` | Async | Compile 10-component evidence package |
| `hipaa_intelligence` | Async | Generate compliance intelligence briefing |
| `hipaa_audit_ledger` | Sync | Get SHA-256 hash chain audit trail |
| `hipaa_baa_execute` | Sync | Execute digital BAA between practices |
| `hipaa_reputation` | Sync | Platform reputation stats |
| `hipaa_model_insights` | Sync | Data intelligence model stats |
| `hipaa_state_coverage` | Sync | Scanning coverage by US state |
| `hipaa_threat_intel` | Sync | Threat intelligence alerts |

### Sync Response Format
```
{
  "status": "completed",
  "task": "hipaa_grade",
  "request_id": "...",
  "result": { ... },
  "meta": {
    "agent": "HIPAA Agent by Sentinel Health Compliance",
    "version": "1.0",
    "processing_time_ms": 245,
    "agent_card": "https://hipaaagent.ai/.well-known/agent.json",
    "powered_by": "HIPAA Agent by Sentinel Health Compliance, LLC -- hipaaagent.ai"
  }
}
```

### Async Response Format (202)
```
{
  "status": "processing",
  "task": "hipaa_scan",
  "request_id": "...",
  "job_id": "uuid",
  "poll_url": "https://hipaaagent.ai/api/v1/a2a/jobs/{jobId}",
  "estimated_completion_seconds": 120,
  "callback_url": "...",
  "agent": "HIPAA Agent by Sentinel Health Compliance",
  "powered_by": "HIPAA Agent by Sentinel Health Compliance, LLC -- hipaaagent.ai"
}
```

### Error Response Format
```
{
  "status": "error",
  "task": "...",
  "request_id": "...",
  "error": "Human-readable error message",
  "meta": {
    "agent": "HIPAA Agent by Sentinel Health Compliance",
    "version": "1.0",
    "agent_card": "https://hipaaagent.ai/.well-known/agent.json",
    "powered_by": "HIPAA Agent by Sentinel Health Compliance, LLC -- hipaaagent.ai"
  }
}
```

---

## 6. Public REST Endpoints

### GET /api/reputation
Returns verified platform reputation statistics including total scans, unique practices, documents generated, breaches tracked, uptime, multi-dimensional trust scores, SHA-256 data integrity hash, Ed25519 digital signature, and the latest blockchain anchor. Cached for 1 hour.

Response fields: agent, version, powered_by, stats (total_scans, unique_practices, baas_generated, sras_completed, policies_generated, breaches_tracked, findings_detected, avg_response_ms, uptime_pct), dimensions (reliability, capability_accuracy, protocol_compliance, data_freshness), verified_at, data_hash, signature, signature_algorithm, verification_url, blockchain_anchor (date, root_hash, tx_hash, chain, basescan_url, status)

### GET /api/verify/{npi}
Public compliance verification badge data for any scanned practice. Returns grade, score, scan date, validity, and embeddable badge URLs. Cached for 1 hour.

Response fields: npi, practice_name, verified, grade, score, scanned_at, valid_until, expired, badge_url, embed_script, verification_page

### GET /api/verify/anchor/{date}
Blockchain anchor proof for a specific date. Returns SHA-256 root hash of all audit events, Base L2 transaction hash, and Basescan verification link.

Response fields: date, root_hash, tx_hash, block_number, chain, event_count, status, anchored_at, basescan_url, metadata, verification (method, how_root_hash_computed, chain, explorer)

### GET /api/health
System health check. Returns status of all services (Supabase, VPS scanner, Resend email, MCP endpoint) and cron job health.

Response fields: status (green/yellow/red), timestamp, response_ms, services (supabase, vps, resend, mcp), crons

### GET /api/threat-intel
Threat intelligence alerts from FBI Watchdog, HHS HC3, CISA KEV, MS-ISAC. Filterable by source, severity, days, limit, offset. Cached for 5 minutes.

Query parameters: source, severity, days (default 30, max 90), limit (default 50, max 200), offset

### GET /api/compliance/state/{npi}
HIPAA compliance readiness for May 2026 deadline. Tracks 13 requirements.

States: compliant (13/13), near_compliant (10+), in_progress (5+), early_stage (1+), not_started (0)

Requirements tracked: external_scan, security_risk_assessment, policies, staff_training, baa_management, encryption, access_control, audit_controls, email_security, network_security, privacy_notice, backup_contingency, integrity_controls

### GET /api/compliance/delta?npi=X&since=DATE
Controls that changed status since a given date.

### GET /api/compliance/controls?npi=X
HIPAA/NIST control-level assessment with pass/fail/partial status for 13 controls.

### GET /api/breach/probability?npi=X
Actuarial breach probability based on specialty, grade, gaps, and prior history.

### POST /api/vendor/risk
Vendor risk profile. Body: { vendor_name, domain }.

### POST /api/validate/transfer
HIPAA workflow compliance guardrail (<100ms). Body: { workflow_type, data_type, destination, controls_applied, npi }.

### POST /api/baa/execute
Digital BAA execution between two practices. Body: { initiator_npi, counterparty_npi, services_description, effective_date, expiration_date }.

### GET /.well-known/agent.json
Machine-readable A2A agent card with 5 capabilities, pricing, rate limits.

### GET /.well-known/jwks.json
JSON Web Key Set for Ed25519 signature verification.

---

## 7. Response Branding

Every response from MCP, A2A, and JSON-RPC endpoints includes:

- `agent`: "HIPAA Agent by Sentinel Health Compliance"
- `powered_by`: "HIPAA Agent by Sentinel Health Compliance, LLC -- hipaaagent.ai"
- Scores are labeled as `hipaa_agent_compliance_score` (numerical_score is renamed)
- Grades include the label: "HIPAA Agent Compliance Score™: {grade}"

---

## 8. Credit System

### Free Tier
500 credits at signup. No credit card required.

### Credit Costs
| Cost | Operations |
|------|------------|
| 0 | get_reputation, get_blockchain_anchor |
| 25 | get_scan_status, get_compliance_score, get_report, get_audit_log, get_evidence_package, generate_baa, get_policies, get_breach, get_breach_score, get_breach_probability, trigger_internal_scan, get_internal_scan_status, get_internal_findings, lookup_practice, get_outreach_status, get_practice_summary, get_training_status, get_vendor_baa_list, log_incident, get_incidents, get_compliance_delta, check_vendor, get_compliance_state, subscribe_webhook, list_webhooks, validate_workflow, get_controls, execute_agent_baa, get_model_insights, get_state_coverage, get_threat_intel |
| 150 | scan_practice, batch_scan (per practice) |
| 500 | generate_sra |

### Premium Tools
These tools require an active subscription on the target NPI or a platform/msp/api key type:
- generate_baa
- get_policies
- generate_sra
- get_evidence_package

If neither condition is met, the tool returns a 403 premium_required error:
```
{
  "error": "premium_required",
  "code": 403,
  "message": "This tool requires a HIPAA Agent subscription or a platform/MSP API key.",
  "upgrade_url": "https://hipaaagent.ai/pricing"
}
```

---

## 9. Webhook Events

### Registration
Use the `subscribe_webhook` MCP tool or `hipaa.subscribe_webhook` JSON-RPC method.

### Event Types
| Event | Description |
|-------|-------------|
| `breach_detected` | New HHS breach record matches this practice |
| `score_dropped` | Compliance score decreased since last scan |
| `baa_expiring` | A BAA is expiring within 30 days |
| `scan_completed` | A new scan has completed for this NPI |
| `control_failed` | A previously passing control is now failing |
| `sra_expired` | Security Risk Assessment has expired |

### Payload Format
Payloads are sent as HTTP POST with JSON body. Signed with HMAC-SHA256 using the subscription secret. Signature is in the `X-Webhook-Signature` header.

```
{
  "event": "scan_completed",
  "npi": "1234567890",
  "timestamp": "2026-03-18T12:00:00Z",
  "data": {
    "grade": "B",
    "score": 78,
    "findings_count": 8
  }
}
```

### Verification (Python)
```
import hmac, hashlib
def verify(payload_body, signature_header, secret):
    expected = hmac.new(secret.encode(), payload_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)
```

---

## 10. SDKs & Integrations

### Python
```
pip install hipaa-agent
```

### Node.js
```
npm install hipaa-agent
```

### LangChain
```
pip install hipaa-agent-langchain
```

### LlamaIndex
```
pip install hipaa-agent-llamaindex
```

### Claude Desktop (MCP)
```
{
  "mcpServers": {
    "hipaa-agent": {
      "url": "https://hipaaagent.ai/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}
```

### Cursor / VS Code (MCP)
Add to MCP server configuration in IDE settings with the same URL and headers as above.

---

## 11. May 2026 HIPAA Security Rule

The updated HIPAA Security Rule takes effect May 2026, introducing mandatory requirements for:
- Technology asset inventory
- Network segmentation
- Multi-factor authentication
- Encryption at rest and in transit
- Vulnerability scanning on a 90-day cycle
- Documented risk assessments

### 13 Tracked Requirements
1. External Infrastructure Scan
2. Security Risk Assessment (SRA)
3. HIPAA Policy Documents
4. Staff Security Awareness Training
5. Business Associate Agreements
6. Transmission Security (TLS/SSL)
7. Access Control & Authentication
8. Audit Controls & Logging
9. Email Security (SPF/DKIM/DMARC)
10. Network Security (Port Exposure)
11. Notice of Privacy Practices
12. Contingency Plan & Data Backup
13. Data Integrity Controls

### Tools
- `get_compliance_state` -- Returns overall readiness state (compliant / near_compliant / in_progress / early_stage / not_started), completed count, next action, and per-requirement status
- `get_compliance_delta` -- Shows which controls improved or regressed since a given date
- Compliance drift is monitored daily via cron; webhook event `control_failed` fires when a passing control regresses

---

## 12. Pricing

| Plan | Price | Credits | Features |
|------|-------|---------|----------|
| Free Developer Tier | $0 | 500 | 36 MCP tools, JSON-RPC, A2A, basic scanning |
| HIPAA Monitor | $99/month | Included | Compliance scan, score tracking, monthly monitoring, breach alerts |
| HIPAA Compliance | $299/month | Included | Everything in Monitor + SRA, policies, training, BAA, evidence, intelligence |
| Enterprise / MSP | Custom | Custom | Volume pricing, batch scanning, white-label, dedicated support |

Get a free API key at https://hipaaagent.ai/developers

---

## 13. Job Polling

### GET /api/jobs/{jobId}
Poll async job status. Auth: `X-API-Key` header.

Job statuses: `pending`, `processing`, `completed`, `failed`

Pending/processing response:
```
{
  "job_id": "uuid",
  "task": "hipaa_scan",
  "status": "pending",
  "created_at": "2026-03-18T15:30:00Z",
  "estimated_completion_seconds": 120,
  "poll_url": "https://hipaaagent.ai/api/jobs/uuid",
  "meta": {
    "agent": "HIPAA Agent",
    "version": "1.0",
    "agent_card": "https://hipaaagent.ai/.well-known/agent.json"
  }
}
```

Completed response includes `result` with task-specific data and `completed_at` timestamp.
Failed response includes `error` message and `failed_at` timestamp.

---

## 14. Error Handling

### Standard HTTP Status Codes
| Code | Meaning |
|------|---------|
| `200` | Success |
| `201` | Created (webhooks, BAAs) |
| `202` | Accepted (async jobs dispatched) |
| `400` | Bad request (missing or invalid parameters) |
| `401` | Unauthorized (invalid or missing session/key) |
| `402` | Payment required (insufficient credits) |
| `403` | Forbidden (tier too low or subscription required) |
| `404` | Not found (NPI not in database, job not found) |
| `422` | Unprocessable (BAA grade requirements not met) |
| `429` | Rate limit exceeded |
| `500` | Internal server error |
| `502` | Scanner unreachable |
| `504` | Scan timeout (scan continues in background) |

### MCP Error Format
```
{
  "content": [{
    "type": "text",
    "text": "{\"error\":\"Invalid NPI format\",\"hint\":\"NPI must be exactly 10 digits\"}"
  }]
}
```

### REST Error Format
```
{
  "error": "Human-readable error message",
  "detail": "Optional additional context"
}
```

---

## 15. Contact & Links

- Email: compliance@hipaaagent.ai
- Sales: sales@hipaaagent.ai
- Developer Portal: https://hipaaagent.ai/developers
- Agent Card: https://hipaaagent.ai/.well-known/agent.json
- JWKS: https://hipaaagent.ai/.well-known/jwks.json
- OpenAPI Spec: https://hipaaagent.ai/openapi.json
- GPT Actions OpenAPI: https://hipaaagent.ai/openapi-gpt.json
- Health Check: https://hipaaagent.ai/api/health
- Summary: https://hipaaagent.ai/llms.txt
- Social: @HipaaAgent (X/Twitter, TikTok)