API Reference

Endpoints Overview

Method Endpoint Description Auth Required
GET /v1/_healthcheck Check API availability No
GET /v1/frameworks List available compliance frameworks Yes
POST /v1/map Map documents to framework controls Yes

Health Check

Check if the API is available and responding.

GET /v1/_healthcheck

Request

curl https://compliance.secberus.ai/v1/_healthcheck

Response

Status: 200 OK

List Frameworks

Retrieve all available compliance frameworks that can be used for document mapping.

GET /v1/frameworks

Request

curl -H "authorization: YOUR_API_KEY" \
  https://compliance.secberus.ai/v1/frameworks

Response

Status: 200 OK

[
  {
    "id": "pci_dss_v4",
    "name": "PCI DSS v4.0",
    "region": "Global"
  },
  {
    "id": "nist_csf_v2",
    "name": "NIST Cybersecurity Framework v2.0",
    "region": "US"
  }
]

Framework Object

Field Type Description
id string Unique framework identifier (use this in map requests)
name string Human-readable framework name
region string Geographic region or applicability

Control Object

Field Type Required Description
id string Yes Control identifier within the framework
framework_id string Yes Parent framework identifier
family string No Control family name
family_id string No Control family identifier
markdown string No Markdown-formatted control text

Map Documents

Map one or more documents to controls across specified compliance frameworks. The API uses AI to analyze document content and find semantically similar framework controls.

POST /v1/map

Request Body

Field Type Required Description
frameworks array[string] Yes Framework IDs to map against (from /v1/frameworks)
documents array[InputDocument] Yes Documents to map
min_similarity float No Minimum similarity score (0.01-1.0). Results below this threshold are excluded.
min_confidence string No Minimum confidence level: High, Medium, Low, or Very Low. Mutually exclusive with min_similarity.
topk integer No Maximum controls to return per framework/document combination (default: 1)

InputDocument Object

Field Type Required Description
id string Yes Client-generated unique identifier for the document
document string Yes Document text to map (limit ~250 words)
category string No Optional category for the document
format string No Document format: plaintext (default) or json

Request Example

curl -X POST https://compliance.secberus.ai/v1/map \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["pci_dss_v4"],
    "min_similarity": 0.3,
    "topk": 3,
    "documents": [
      {
        "id": "doc1",
        "document": "Organization must enforce password rotation. Password rotation must occur every 90 days."
      }
    ]
  }'

Response

Status: 200 OK

{
  "messages": [
    {
      "severity": "info",
      "message": "Processing completed successfully"
    }
  ],
  "frameworks": [
    {
      "framework_id": "pci_dss_v4",
      "controls": [
        {
          "document_id": "doc1",
          "similarity": 0.87,
          "confidence": "High",
          "control": {
            "id": "8.3.9",
            "framework_id": "pci_dss_v4",
            "family": "Identify Users and Authenticate Access",
            "family_id": "8"
          }
        }
      ]
    }
  ]
}

Response Fields

Field Type Description
frameworks array[MapResponseItem] Results grouped by framework
messages array[Message] Informational or warning messages (optional)

MapResponseItem Object

Field Type Description
framework_id string Framework identifier
controls array[MapResult] Matched controls for this framework

MapResult Object

Field Type Description
document_id string ID of the input document
similarity float Similarity score (0.0-1.0)
confidence string Confidence level: High, Medium, Low, or Very Low
control Control Matched framework control

Message Object

Field Type Description
severity string warning or info
message string Message text

Error Responses

All endpoints return errors in RFC 7807 format:

{
  "requestid": "req-abc123",
  "link": "https://docs.secberus.com/errors/400",
  "http_status": 400,
  "title": "Bad Request",
  "detail": "Invalid framework ID: unknown_framework"
}

Error Codes

Status Description
400 Bad Request - Invalid input parameters
403 Forbidden - Invalid or missing API key
500 Internal Server Error - Contact support if persistent
Authentication Best Practices