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",
    "controls": [
      {
        "id": "1.1.1",
        "title": "Roles and responsibilities for performing activities...",
        "description": "...",
        "family": "Build and Maintain a Secure Network",
        "family_id": "1",
        "category": "Network Security Controls",
        "framework_name": "PCI DSS v4.0",
        "framework_id": "pci_dss_v4"
      }
    ]
  },
  {
    "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
`controls`	array	List of controls within the framework (optional)

Control Object

Field	Type	Description
`id`	string	Control identifier within the framework
`title`	string	Control title
`description`	string	Detailed control description
`family`	string	Control family name
`family_id`	string	Control family identifier
`category`	string	Control category
`framework_name`	string	Parent framework name
`framework_id`	string	Parent framework identifier

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

{
  "methods": ["semantic"],
  "messages": [
    {
      "severity": "info",
      "message": "Processing completed successfully"
    }
  ],
  "controls": [
    {
      "document_id": "doc1",
      "similarity": 0.87,
      "confidence": "High",
      "control": {
        "id": "8.3.9",
        "title": "Password/passphrase policies",
        "description": "If passwords/passphrases are used as authentication factors...",
        "family": "Identify Users and Authenticate Access",
        "family_id": "8",
        "category": "Authentication",
        "framework_name": "PCI DSS v4.0",
        "framework_id": "pci_dss_v4"
      }
    }
  ]
}

Response Fields

Field	Type	Description
`methods`	array[string]	Mapping methods used
`messages`	array[Message]	Informational or warning messages
`controls`	array[MapResult]	Matched controls

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