API Endpoints

Complete reference for all CSE Registry API endpoints. All endpoints require authentication via API key.

Base URL: https://api.cseregistry.org/v1

Signals

List Signals

GET /signals

Returns a paginated list of signals with optional filtering.

Query Parameters

ParameterTypeDescription
domainstringFilter by domain (e.g., HIPAA, SOC2)
categorystringFilter by category (e.g., TECH, ACCESS)
severitystringFilter by severity (critical, high, medium, low, info)
tagstringFilter by tag (can specify multiple)
pageintegerPage number (default: 1)
per_pageintegerResults per page (default: 20, max: 100)
# List high-severity HIPAA signals
curl "https://api.cseregistry.org/v1/signals?domain=HIPAA&severity=high" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "CSE-HIPAA-TECH-ENCRYPT-REST-001",
      "domain": "HIPAA",
      "category": "TECH",
      "title": "Data at Rest Encryption Not Enabled",
      "description": "Storage resource does not have encryption at rest enabled...",
      "severity": "high",
      "tags": ["encryption", "storage", "data-protection"],
      "version": "1.0.0"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

Get Signal

GET /signals/:id

Returns the complete signal definition for a specific signal ID.

Path Parameters

idThe signal ID (e.g., CSE-HIPAA-TECH-ENCRYPT-REST-001)
curl "https://api.cseregistry.org/v1/signals/CSE-HIPAA-TECH-ENCRYPT-REST-001" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "id": "CSE-HIPAA-TECH-ENCRYPT-REST-001",
    "domain": "HIPAA",
    "category": "TECH",
    "title": "Data at Rest Encryption Not Enabled",
    "description": "Storage resource does not have encryption at rest enabled...",
    "severity": "high",
    "tags": ["encryption", "storage", "data-protection"],
    "detection": {
      "artifact_types": ["cloud_resource", "configuration"],
      "conditions": ["encryption_enabled == false"]
    },
    "remediation_hint": "Enable server-side encryption on the storage resource",
    "version": "1.0.0",
    "created": "2024-01-15",
    "updated": "2024-06-20"
  }
}

Get Signal Mappings

GET /signals/:id/mappings

Returns all framework control mappings for a specific signal.

Query Parameters

frameworkFilter mappings by framework (e.g., HIPAA, NIST-CSF)
curl "https://api.cseregistry.org/v1/signals/CSE-HIPAA-TECH-ENCRYPT-REST-001/mappings" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "signal_id": "CSE-HIPAA-TECH-ENCRYPT-REST-001",
    "mappings": [
      {
        "framework": "HIPAA",
        "control_id": "§164.312(a)(2)(iv)",
        "control_title": "Encryption and decryption",
        "relationship": "primary",
        "rationale": "Encryption at rest directly implements..."
      },
      {
        "framework": "NIST-CSF",
        "control_id": "PR.DS-1",
        "control_title": "Data-at-rest is protected",
        "relationship": "primary",
        "rationale": "Signal detects absence of data-at-rest protection"
      }
    ]
  }
}

Domains

List Domains

GET /domains

Returns all available compliance domains with metadata.

curl "https://api.cseregistry.org/v1/domains" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "CMMC",
      "name": "Cybersecurity Maturity Model Certification",
      "signal_count": 134,
      "categories": ["ACCESS", "AUDIT", "COMMS", "CONFIG", "IDENTITY"]
    },
    {
      "id": "HIPAA",
      "name": "Health Insurance Portability and Accountability Act",
      "signal_count": 75,
      "categories": ["TECH", "ADMIN", "PHYS"]
    }
    // ... more domains
  ],
  "meta": {
    "total": 12
  }
}

Get Domain

GET /domains/:id

Returns detailed information about a specific domain including statistics by category and severity.

curl "https://api.cseregistry.org/v1/domains/HIPAA" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "id": "HIPAA",
    "name": "Health Insurance Portability and Accountability Act",
    "description": "U.S. regulation protecting sensitive patient health information",
    "signal_count": 75,
    "categories": ["TECH", "ADMIN", "PHYS"],
    "stats": {
      "by_category": {
        "TECH": 45,
        "ADMIN": 20,
        "PHYS": 10
      },
      "by_severity": {
        "critical": 5,
        "high": 30,
        "medium": 25,
        "low": 10,
        "info": 5
      }
    }
  }
}

Search Signals

GET /search

Full-text search across signal titles, descriptions, and tags.

Query Parameters

qSearch query (required)
domainLimit search to specific domain
pagePage number (default: 1)
per_pageResults per page (default: 20, max: 100)
curl "https://api.cseregistry.org/v1/search?q=encryption" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "CSE-HIPAA-TECH-ENCRYPT-REST-001",
      "domain": "HIPAA",
      "title": "Data at Rest Encryption Not Enabled",
      "severity": "high",
      "score": 0.95
    },
    {
      "id": "CSE-HIPAA-TECH-ENCRYPT-TRANSIT-001",
      "domain": "HIPAA",
      "title": "Data in Transit Encryption Not Enabled",
      "severity": "high",
      "score": 0.92
    }
  ],
  "meta": {
    "total": 45,
    "query": "encryption",
    "page": 1,
    "per_page": 20
  }
}

Validation

Validate Object

POST /validate

Validates a single object against a CSE schema (signal, finding, artifact, or mapping).

Request Body

schemaSchema type: signal, finding, artifact, or mapping
dataThe object to validate
curl -X POST "https://api.cseregistry.org/v1/validate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "signal",
    "data": {
      "id": "CSE-HIPAA-TECH-TEST-001",
      "canonical_name": "Test Signal",
      "domain": "HIPAA",
      "category": "TECH",
      "severity": "high"
    }
  }'

# Response (valid)
{
  "data": {
    "valid": true,
    "schema_type": "signal",
    "schema_version": "1.0.0"
  }
}

# Response (invalid)
{
  "data": {
    "valid": false,
    "schema_type": "signal",
    "schema_version": "1.0.0",
    "errors": [
      {
        "path": "/severity",
        "message": "must be equal to one of the allowed values",
        "keyword": "enum"
      }
    ]
  }
}

Batch Validate

POST /validate/batch

Validates multiple objects against a CSE schema in a single request. Maximum 100 items per request.

Request Body

schemaSchema type: signal, finding, artifact, or mapping
itemsArray of objects to validate (max 100)
curl -X POST "https://api.cseregistry.org/v1/validate/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "finding",
    "items": [
      { "signal_id": "CSE-HIPAA-TECH-001", "status": "open" },
      { "signal_id": "CSE-HIPAA-TECH-002", "status": "invalid_status" }
    ]
  }'

# Response
{
  "data": {
    "schema_type": "finding",
    "schema_version": "1.0.0",
    "results": [
      { "index": 0, "valid": true },
      {
        "index": 1,
        "valid": false,
        "errors": [{ "path": "/status", "message": "must be equal to one of the allowed values", "keyword": "enum" }]
      }
    ],
    "summary": {
      "total": 2,
      "valid": 1,
      "invalid": 1
    }
  }
}

Bulk Operations

Bulk Signal Lookup

POST /signals/bulk

Look up multiple signals by ID in a single request. Maximum 100 IDs per request.

Request Body

idsArray of signal IDs to look up (max 100)
curl -X POST "https://api.cseregistry.org/v1/signals/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "CSE-CMMC-COMMS-UNRESTRICTED-SSH-001",
      "CSE-HIPAA-TECH-ENCRYPT-REST-001",
      "CSE-INVALID-001"
    ]
  }'

# Response
{
  "data": {
    "results": [
      {
        "id": "CSE-CMMC-COMMS-UNRESTRICTED-SSH-001",
        "status": "found",
        "signal": {
          "id": "CSE-CMMC-COMMS-UNRESTRICTED-SSH-001",
          "canonical_name": "Unrestricted SSH Access from Internet",
          "severity": "high",
          "domain": "CMMC"
        }
      },
      {
        "id": "CSE-HIPAA-TECH-ENCRYPT-REST-001",
        "status": "found",
        "signal": { ... }
      },
      {
        "id": "CSE-INVALID-001",
        "status": "not_found"
      }
    ],
    "summary": {
      "total": 3,
      "found": 2,
      "not_found": 1
    }
  }
}

Bulk Mappings Lookup

POST /mappings/bulk

Get framework mappings for multiple signals in a single request. Maximum 100 signal IDs per request.

Request Body

signal_idsArray of signal IDs (max 100)
framework(Optional) Filter mappings by framework
min_confidence(Optional) Minimum confidence score (0-1)
curl -X POST "https://api.cseregistry.org/v1/mappings/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signal_ids": [
      "CSE-CMMC-COMMS-UNRESTRICTED-SSH-001",
      "CSE-HIPAA-TECH-ENCRYPT-REST-001"
    ],
    "framework": "NIST SP 800-53",
    "min_confidence": 0.8
  }'

# Response
{
  "data": {
    "results": [
      {
        "signal_id": "CSE-CMMC-COMMS-UNRESTRICTED-SSH-001",
        "mappings": [
          {
            "framework": "NIST SP 800-53",
            "control_id": "SC-7",
            "control_name": "Boundary Protection",
            "confidence": 0.92
          }
        ]
      },
      {
        "signal_id": "CSE-HIPAA-TECH-ENCRYPT-REST-001",
        "mappings": [
          {
            "framework": "NIST SP 800-53",
            "control_id": "SC-28",
            "control_name": "Protection of Information at Rest",
            "confidence": 0.95
          }
        ]
      }
    ],
    "summary": {
      "total_signals": 2,
      "total_mappings": 2
    }
  }
}

Statistics

Get Registry Statistics

GET /stats

Returns aggregate statistics about the registry.

curl "https://api.cseregistry.org/v1/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "registry_version": "1.0.0",
    "spec_version": "1.0.0",
    "last_updated": "2024-12-28T00:00:00Z",
    "total_signals": 1132,
    "total_mappings": 1308,
    "domains": 12,
    "categories": 12,
    "by_domain": {
      "CMMC": 134,
      "FEDRAMP": 145,
      "HITRUST": 126,
      // ...
    },
    "by_severity": {
      "critical": 89,
      "high": 423,
      "medium": 398,
      "low": 167,
      "info": 55
    }
  }
}

Error Responses

All endpoints return consistent error responses:

# 401 Unauthorized
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

# 404 Not Found
{
  "error": {
    "code": "not_found",
    "message": "Signal 'CSE-INVALID-001' not found"
  }
}

# 400 Bad Request
{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid domain: 'INVALID'",
    "details": {
      "parameter": "domain",
      "value": "INVALID",
      "valid_values": ["CMMC", "HIPAA", "SOC2", ...]
    }
  }
}

# 429 Rate Limited
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "reset_at": "2024-12-28T15:00:00Z"
    }
  }
}

Next Steps

Rate Limits

Usage limits and quotas

Examples

Code examples in multiple languages