API Documentation

RESTful API for accessing OSA security patterns, NIST 800-53 Rev 5 controls, and compliance framework mappings. Public data endpoints require no authentication. Key management endpoints require a session or API key.

OpenAPI Spec (YAML) Try it Live Manage API Keys

Base URL


https://www.opensecurityarchitecture.org/api/v1

Format: All responses are JSON. CORS enabled for cross-origin access.

Headers: Rate limit info in X-RateLimit-Limit and X-RateLimit-Remaining.

Rate Limits

Tier	Limit	Scope
Anonymous	10 req/min	Per IP address
Signed in	100 req/min	Per user account
API key	100 req/min	Per key (customisable)

Create a free API key for higher limits and programmatic access.

Authentication

Public data endpoints (patterns, controls, frameworks) require no authentication. Key management endpoints require either a browser session (OAuth) or an API key.

API Key Authentication

Pass your API key in the X-API-Key header:

curl -H "X-API-Key: osa_your_key_here" \
  https://www.opensecurityarchitecture.org/api/v1/patterns

Create and manage API keys from your API Keys dashboard (requires sign-in).

Keys use the prefix osa_ followed by 44 hex characters. The full key is shown once at creation — store it securely.

Maximum 5 active keys per account. Keys can be revoked at any time.

Patterns

GET /api/v1/patterns

List all security patterns with optional filtering and pagination.

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status: published, draft
`family`	string	Filter by NIST control family (e.g. AC, SC)
`search`	string	Search title, description, and ID

GET /api/v1/patterns/:id

Get full detail for a specific pattern including controls, threats, examples, and references.

Parameter	Type	Description
`fields`	string	Optional. controls or threats to return only that section

Example:

GET /api/v1/patterns/SP-029?fields=threats

Controls

GET /api/v1/controls

List all 315 NIST 800-53 Rev 5 controls with optional filtering.

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`family`	string	NIST family code (e.g. AC, IA, SC, SR)
`baseline`	string	Filter by NIST baseline: low, moderate, high
`search`	string	Search name, ID, family name, and description

GET /api/v1/controls/:id

Get full control detail including compliance mappings and which patterns use it.

Parameter	Type	Description
`fields`	string	Optional. patterns for reverse lookup, mappings for compliance only

Example:

GET /api/v1/controls/AC-02?fields=patterns

Compliance Frameworks

GET /api/v1/frameworks

List all 87 supported compliance frameworks with mapping statistics.

GET /api/v1/frameworks/:id

Get framework detail. Use fields=mappings for paginated control-to-framework mappings.

Available framework IDs:

iso_27001_2022iso_27002_2022cobit_2019cis_controls_v8nist_csf_2soc2_tscpci_dss_v4csa_ccm_v4csa_aicmfinos_ccciso_42001_2023iec_62443nis2pra_op_resiliencemas_trmapra_cps_234asd_e8bsi_grundschutzanssifinma_circularosfi_b13gdprdorabio2rbi_csffisclgpd_bcbhkma_tme1mlps_2dnb_good_practicecraswift_cscfsama_csfnca_eccuae_iacbb_tmqatar_niacbuaecbe_csfsa_js2cbn_csfbog_cisdpopiabom_ctrmiosco_cyberbcbs_239cpmi_pfmiffiec_isnydfs_500hipaa_srecb_croeeba_ictsebi_cscrfbot_cybercmmc_2nerc_cipnrc_73_54tsa_psdieee_1686ferc_cipdoe_c2m2api_1164awiaiaea_nsspci_ptsfips_140cbesttiber_eupci_hsmcommon_criteriaisae_3402solvency_iilloyds_msnaic_dspra_ss1_23fca_sysc_13hitrust_csffda_21_cfr_11fda_cyberiso_27799nhs_dsptowasp_masvs_v2ccss_v9micabasel_sco60bsscsec_custody_digital

Example:

GET /api/v1/frameworks/pci_dss_v4?fields=mappings&per_page=50

Follows

Follow patterns and frameworks to track updates. Requires authentication (browser session or API key).

Patterns

GET /api/v1/patterns/follows

List all patterns the authenticated user is following. Returns pattern IDs and follow timestamps.

POST /api/v1/patterns/:id/follow

Follow a pattern. Idempotent — following an already-followed pattern succeeds silently.

DELETE /api/v1/patterns/:id/follow

Unfollow a pattern. Idempotent — unfollowing an unfollowed pattern succeeds silently.

GET /api/v1/patterns/:id/followers

Public endpoint returning the follower count for a pattern. Cached for 5 minutes.

Frameworks

GET /api/v1/frameworks/follows

List all frameworks the authenticated user is following.

POST /api/v1/frameworks/:id/follow

Follow a framework. Idempotent.

DELETE /api/v1/frameworks/:id/follow

Unfollow a framework. Idempotent.

GET /api/v1/frameworks/:id/followers

Public endpoint returning the follower count for a framework. Cached for 5 minutes.

Key Management

These endpoints require authentication (browser session or API key).

GET /api/v1/keys

List your API keys (name, prefix, tier, rate limit, timestamps). The full key is never returned.

POST /api/v1/keys

Create a new API key. Maximum 5 active keys per account.

Request:

POST /api/v1/keys
Content-Type: application/json
Cookie: session=...

{
  "name": "My Integration"
}

Response (201):

{
  "key": "osa_abc123...",
  "data": {
    "id": "2fd2564e0e21...",
    "name": "My Integration",
    "prefix": "osa_abc1",
    "tier": "free",
    "rate_limit": 100,
    "created_at": "2026-02-12T09:00:00Z"
  }
}

The full key is returned only once at creation. Store it securely — it cannot be retrieved later.

DELETE /api/v1/keys/:id

Revoke an API key. Revoked keys are immediately rejected on authenticated endpoints. Returns 204 on success.

Response Format

List Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 44,
    "total_pages": 3
  }
}

Detail Response

{
  "data": {
    "id": "SP-029",
    "title": "Zero Trust Architecture",
    "description": "...",
    "controls": [...],
    "threats": [...]
  }
}

Error Response

{
  "error": "Pattern SP-999 not found"
}

Rate Limited

HTTP 429
Retry-After: 60
X-RateLimit-Limit: 10

{
  "error": "Rate limit exceeded (10/min for anonymous access). Sign in or use an API key for higher limits."
}

Quick Start

# List all patterns
curl https://www.opensecurityarchitecture.org/api/v1/patterns

# Get Zero Trust pattern with threats
curl https://www.opensecurityarchitecture.org/api/v1/patterns/SP-029?fields=threats

# List controls in the Access Control family
curl https://www.opensecurityarchitecture.org/api/v1/controls?family=AC

# Get PCI DSS v4 mappings
curl https://www.opensecurityarchitecture.org/api/v1/frameworks/pci_dss_v4?fields=mappings

# Search patterns
curl "https://www.opensecurityarchitecture.org/api/v1/patterns?search=authentication"

# Use an API key for authenticated endpoints
curl -H "X-API-Key: osa_your_key_here" \
  https://www.opensecurityarchitecture.org/api/v1/keys