API Documentation

Integrate OnlyHIPAA data into your own systems using our REST API.

Overview

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

Base URL https://app.onlyhipaa.com/api/v1/
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 for the organization
assessments:read Read assessments and their status
remediation:read Read remediation tasks
evidence:read Read evidence metadata (no file contents)
vendors:read Read vendors & Business Associate Agreements
webhooks:read List webhook endpoints
findings:write Update findings (status, risk level, title, notes, description, category, recommendation, due date)
assessments:write Update an assessment's name, status, or due date
remediation:write Create & update remediation tasks (title, description, status, priority, assignee, due date)
webhooks:write Create, update & delete webhook endpoints

Endpoints

GET /api/v1/findings.php

Returns a list of findings for your organization.

Required scope: findings:read

Query parameters

ParameterTypeDescription
statusstringFilter by status: open, in_progress, resolved
risk_levelstringFilter 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

ParameterTypeDescription
statusstringFilter 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

ParameterTypeDescription
statusstringFilter by status: open, in_progress, completed
prioritystringFilter by priority: critical, high, medium, low
GET /api/v1/evidence.php

Returns evidence metadata for your organization (filename, type, size, description, review/expiry dates, version). File contents are never served via the API.

Required scope: evidence:read

Query parameters

ParameterTypeDescription
limitintPage size, 1–100 (default 100)
offsetintRow offset for pagination
GET /api/v1/vendors.php

Returns vendors / Business Associates for your organization, including BAA status and review dates.

Required scope: vendors:read

Query parameters

ParameterTypeDescription
statusstringFilter by status: active, under_review, terminated
risk_levelstringFilter by risk: critical, high, medium, low
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.

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.

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 statusMeaning
401Missing or invalid API key
403Valid key but insufficient scope
429Rate limit exceeded
500Internal server error

Example

Fetch all open critical findings using curl:

curl -s \
  -H "Authorization: Bearer ohk_live_••••••••••••••••" \
  -H "Accept: application/json" \
  "https://app.onlyhipaa.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
}