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	60 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	Keyword search. Every word must match. Results are ranked and carry a `score`

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

GET /api/v1/patterns/:id/crosswalk

One call for the join that otherwise takes a pattern call, a framework call and one call per control: each control with its emphasis, the threats it mitigates in this pattern, and its clauses in the frameworks you name. An empty clause list means OSA records no mapping, and the response names those controls under unmapped. For a framework compared with a published crosswalk, unmapped_checked lists the ones with no clause there either. A control withdrawn in SP 800-53 Rev 5 is marked withdrawn, with the controls it moved into. pattern.control_counts gives the totals for the whole pattern, so a filtered response shows how many controls it left out.

Parameter	Type	Description
`framework`	string	Optional. Up to five framework IDs, comma-separated
`emphasis`	string	Optional. critical, important or standard, comma-separated

Example:

GET /api/v1/patterns/SP-023/crosswalk?framework=iec_62443,cra&emphasis=critical

IDs are accepted in either form: SP-023 or sp-023, SC-07 or sc-7, iec_62443 or iec-62443.

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: 42
X-RateLimit-Limit: 60

{
  "error": "Rate limit exceeded (60/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