API Documentation

Integrate HIPAA Sherpa data into your own systems using our REST API.

Overview

The HIPAA Sherpa API allows you to programmatically access your organization's findings, assessments, and remediation data. All requests must be made over HTTPS.

Base URL	`https://hipaasherpa.com/api/v1/`
Availability	The REST API is an Enterprise-plan feature. Requests on other plans return `403` ("API access requires an Enterprise plan").
Format	JSON (`Content-Type: application/json`)
Authentication	`Authorization: Bearer <api_key>`
Rate limit	100 requests per minute per API key. Exceeding the limit returns `429 Too Many Requests`.

Authentication

All API requests require a Bearer token. To create an API key, go to Settings → API Keys in your dashboard and click Generate new key. Store the key securely - it will only be shown once.

Include the key in every request using the Authorization header:

Authorization: Bearer ohk_live_••••••••••••••••

Scopes

Each API key is issued with one or more scopes that control which resources it can access.

Scope	Access granted
`findings:read`	Read findings
`findings:write`	Create & update findings (write)
`assessments:read`	Read assessments
`assessments:write`	Create & update assessments (write)
`remediation:read`	Read remediation tasks
`remediation:write`	Create & update remediation tasks (write)
`evidence:read`	Read evidence metadata
`evidence:write`	Update evidence metadata (write)
`vendors:read`	Read vendors & BAAs
`vendors:write`	Create & update vendors & BAAs (write)
`incidents:read`	Read security incidents
`policies:read`	Read policies
`audit:read`	Read the audit log
`compliance:read`	Read the compliance score & posture
`training:read`	Read the training roster & assignment report
`training:write`	Manage the training employee roster (write)
`scans:read`	Read network scans, results & reports
`scans:write`	Manage scan schedules & request scans (write)
`webhooks:read`	List webhook endpoints
`webhooks:write`	Manage webhook endpoints (write)

Endpoints

GET /api/v1/findings.php

Returns a list of findings for your organization.

Required scope: findings:read

Query parameters

Parameter	Type	Description
`status`	string	Filter by status: `open`, `in_progress`, `resolved`
`risk_level`	string	Filter by risk: `critical`, `high`, `medium`, `low`

GET /api/v1/assessments.php

Returns a list of assessments for your organization.

Required scope: assessments:read

Query parameters

Parameter	Type	Description
`status`	string	Filter by status: `draft`, `in_progress`, `completed`

GET /api/v1/remediation.php

Returns a list of remediation tasks linked to your organization's findings.

Required scope: remediation:read

Query parameters

Parameter	Type	Description
`status`	string	Filter by status: `open`, `in_progress`, `completed`
`priority`	string	Filter by priority: `critical`, `high`, `medium`, `low`

GET PATCH /api/v1/evidence.php

Read and update evidence metadata (filename, type, size, description, review/expiry dates, version). File contents are never served or writable via the API.

GET — list evidence metadata (evidence:read).
PATCH — update metadata by id (evidence:write). Writable: description, review_date, expires_at only.

Query parameters (GET)

Parameter	Type	Description
`limit`	int	Page size, 1–100 (default 100)
`offset`	int	Row offset for pagination

GET POST PATCH /api/v1/vendors.php

Read and manage vendors / Business Associates, including BAA status and review dates. Pass ?id= to GET a single vendor.

GET — list or fetch vendors (vendors:read).
POST — create a vendor (vendors:write). Body: name (required), plus optional contact_name, contact_email, website, services_provided, data_access, risk_level, status, has_baa, baa_signed_at, baa_expires_at, next_review_date, notes. Returns HTTP 201.
PATCH — update a vendor by id (vendors:write).

Query parameters (GET)

Parameter	Type	Description
`id`	string	Return a single vendor by id
`status`	string	Filter by status: `active`, `under_review`, `terminated`
`risk_level`	string	Filter by risk: `critical`, `high`, `medium`, `low`

GET POST PATCH DELETE /api/v1/training-employees.php

Manage the delivered-training employee roster — built for HR-system sync. Employees are keyed by email (unique per organization), so re-posting a person updates them and never duplicates. Course assignment and invite emails stay in the dashboard.

GET — list the roster, ?id= for one employee, ?active=1 for active only (training:read).
POST — upsert by email (training:write). Body: full_name (required), email (required), optional department. Returns HTTP 201 when created, 200 when an existing email was updated.
PATCH — update by id: full_name, department, is_active (training:write). Deactivation excludes the employee from bulk assignment while preserving history.
DELETE — remove by ?id= (training:write). Employees with completed training cannot be deleted (HTTP 409) — completions are compliance evidence; deactivate instead.

GET /api/v1/training-assignments.php

Read-only delivered-training report (training:read): every assignment with its effective status (expired once a pass is older than the 12-month validity window), score, attempts, duration, valid-through date, reminder count, invite-failure flag, and certificate id, plus an org-level stats block. Filters: course_key, status, employee_id; paginate with limit/offset. Assigning, resending, and revoking are dashboard-only actions (they send email).

GET /api/v1/training-transcript.php

The complete merged training transcript (training:read) — both delivered employee training and legacy manually-logged completions, the same dataset as the dashboard transcript export. One call gives an auditor or HR system the organization's full training record. Filters: q (person name/email), source (delivered|logged), status; paginate with limit (max 200) / offset. Every pull is recorded in the audit log.

GET POST PATCH DELETE /api/v1/webhooks.php

Manage your organization's outbound webhook endpoints.

GET — list endpoints (webhooks:read). Append ?catalog=1 for the list of subscribable event names. Signing secrets are never returned on read.
POST — create an endpoint (webhooks:write). Body: url, events (array), optional description. The signing secret is returned once in the response.
PATCH — update url / events / description / is_active by id (webhooks:write).
DELETE — remove an endpoint by id (webhooks:write).

Webhook URLs are validated against an SSRF guard. Use the X-HTTP-Method-Override header if your client can't send PATCH/DELETE.

GET /api/v1/incidents.php

Returns security incidents for your organization, including breach-notification fields. Pass ?id= for a single incident.

Required scope: incidents:read

Query parameters

Parameter	Type	Description
`id`	string	Return a single incident by id
`status`	string	Filter: `open`, `under_review`, `resolved`, `reported`
`incident_type`	string	Filter: `unauthorized_access`, `theft_loss`, `improper_disposal`, `hacking`, `other`
`phi_involved`	boolean	Filter to incidents where PHI was involved

GET /api/v1/policies.php

Returns policies with status, version, owner, and review dates. Pass ?id= for a single policy.

Required scope: policies:read

Query parameters

Parameter	Type	Description
`id`	string	Return a single policy by id
`status`	string	Filter: `draft`, `active`, `under_review`, `retired`
`policy_type`	string	Filter by type (e.g. `security`, `privacy`, `breach_notification`)
`overdue_review`	boolean	Only policies past their review date

GET /api/v1/audit-log.php

Returns your organization's tamper-evident audit log, newest first — the same event stream that drives webhooks and SIEM export. Ideal for pulling activity into your own SIEM/GRC tooling.

Required scope: audit:read

Query parameters

Parameter	Type	Description
`event`	string	Prefix match on the event name (e.g. `incident` matches `incident.created`, `incident.closed`)
`event_exact`	string	Match one full event name exactly
`entity_type`	string	Filter by entity type (e.g. `finding`, `policy`)
`from` / `to`	string	Bound `created_at` (inclusive), `YYYY-MM-DD` or datetime

GET /api/v1/compliance-score.php

Returns your organization's current compliance score (0–100), letter grade, and the per-dimension breakdown (Findings, Policies & Docs, Training, Incident Response, Business Associates), plus the date of the last daily snapshot.

Required scope: compliance:read

Write operations

Each requires the matching *:write scope. Send a JSON body; use the X-HTTP-Method-Override header for PATCH if your client can't send it directly.

PATCH /api/v1/findings.php — update a finding by id. Editable: status (open, in_progress, resolved, accepted_risk, false_positive), risk_level, title, notes, description, category, recommendation, due_date.
POST /api/v1/remediation.php — create a task. Body: title (required), description, status, priority, assigned_to (an email), due_date, finding_id. Returns HTTP 201 with the created task.
PATCH /api/v1/remediation.php — update a task by id. Editable: title, description, status, priority, assigned_to, due_date.
PATCH /api/v1/assessments.php — update an assessment's name, status, or due_date by id.
POST / PATCH /api/v1/vendors.php — create (201) or update a vendor / BAA by id (vendors:write).
PATCH /api/v1/evidence.php — update evidence metadata (description, review_date, expires_at) by id (evidence:write).
POST / PATCH / DELETE /api/v1/training-employees.php — upsert (by email), update, or remove training-roster employees (training:write); employees with completions can only be deactivated. POST accepts auto_assign: true to also assign every due built-in course and email the invites (HR-sync onboarding in one call).

Response format

List (GET) responses return HTTP 200 with a data array, the count in this page, and the limit / offset used. Findings and remediation also include a total (the full match count); assessments omit total. A successful create (POST /api/v1/remediation.php) returns HTTP 201 with the created record.

{
  "data": [
    { "id": "abc123", "title": "...", "status": "open", ... }
  ],
  "count": 1,
  "total": 1,
  "limit": 100,
  "offset": 0
}

Paginate with ?limit= (1–100, default 100) and ?offset=.

Error responses

Errors return a non-2xx HTTP status with a JSON body:

{
  "error": "Unauthorized",
  "message": "Invalid or expired API key."
}

HTTP status	Meaning
`401`	Missing or invalid API key
`403`	Valid key, but insufficient scope, insufficient role, or no executed BAA
`429`	Rate limit exceeded
`500`	Internal server error

Example

Fetch all open critical findings using curl:

curl -s \
  -H "Authorization: Bearer ohk_live_••••••••••••••••" \
  -H "Accept: application/json" \
  "https://hipaasherpa.com/api/v1/findings.php?status=open&risk_level=critical"

Example response:

{
  "data": [
    {
      "id": "fnd_01j9kx4",
      "title": "Unencrypted ePHI at rest on workstation",
      "risk_level": "critical",
      "status": "open",
      "created_at": "2026-01-15T09:32:00Z"
    }
  ],
  "count": 1
}