Control Collections

Build reusable bundles of controls from any supported framework. A collection is private to its creator by default; setting visibility to SHARED exposes it to every member of the creator's organization. All endpoints require a SAMS token.

List control collections

GET /api/v1/control-collections

Returns the caller's own collections plus any SHARED collections in their organization. Soft-deleted collections are excluded.

Response

{
  "total": 3,
  "collections": [
    {
      "id": "col-uuid",
      "name": "FedRAMP Moderate baseline",
      "description": "Core security controls for FedRAMP Moderate",
      "tags": ["fedramp", "moderate"],
      "color": "#FF5733",
      "visibility": "SHARED",
      "controlCount": 325,
      "createdById": "user-uuid",
      "createdAt": "2026-05-15T10:30:00Z",
      "updatedAt": "2026-05-20T14:22:00Z"
    }
  ]
}

Create a control collection

POST /api/v1/control-collections

Name
name
Type
string
Description
Collection name.
Name
description
Type
string
Description
Free-form description.
Name
tags
Type
array
Description
Array of string tags.
Name
color
Type
string
Description
Hex color (e.g. #FF5733).
Name
visibility
Type
string
Description
PRIVATE (default) or SHARED.

Returns 201 with the new collection record. 400 if name is missing.

Get a control collection

GET /api/v1/control-collections/{id}

Returns the collection plus every control in it.

Response

{
  "id": "col-uuid",
  "name": "FedRAMP Moderate baseline",
  "visibility": "shared",
  "createdById": "user-uuid",
  "createdAt": "2026-05-15T10:30:00Z",
  "updatedAt": "2026-05-20T14:22:00Z",
  "controls": [
    {
      "controlId": "AC-2",
      "framework": "nist-800-53",
      "notes": "Critical control",
      "position": 1,
      "addedAt": "2026-05-16T08:15:00Z"
    }
  ]
}

Returns 404 if the collection does not exist or the caller has no access.

Update a control collection

PATCH /api/v1/control-collections/{id}

Body accepts any subset of name, description, tags, color, visibility. Only the creator can update.

Returns 200 with { success: true, id, name }. 403 if the caller is not the creator, 404 if not found.

Delete a control collection

DELETE /api/v1/control-collections/{id}

Soft-deletes the collection (the row is kept with a deletedAt timestamp). Only the creator can delete.

Returns 200 with { success: true }. 403 if not creator, 404 if not found.

List controls in a collection

GET /api/v1/control-collections/{id}/controls

Name
id
Type
string
Description
Collection ID.
Name
framework
Type
string
Description
Filter to a single framework.

Each control is returned with its membership metadata (notes, position, addedAt) joined to the framework record (identifier, title, family, statement).

Response

{
  "collection": { "id": "col-uuid", "name": "FedRAMP Moderate baseline" },
  "total": 325,
  "controls": [
    {
      "controlId": "AC-2",
      "framework": "nist-800-53",
      "notes": "Critical control",
      "position": 1,
      "addedAt": "2026-05-16T08:15:00Z",
      "identifier": "AC-2",
      "title": "Account Management",
      "family": "Access Control",
      "statement": "..."
    }
  ]
}

Add controls to a collection

POST /api/v1/control-collections/{id}/controls

Name
controls
Type
array
Description
Array of { controlId, framework, notes? }. Duplicates are silently skipped.

The creator can always add controls; if the collection is SHARED, any member of the creator's organization can add as well.

Response

{ "success": true, "added": 5, "total": 47 }

Remove controls from a collection

DELETE /api/v1/control-collections/{id}/controls

Name
controls
Type
array
Description
Array of { controlId, framework } to remove.

Only the creator can remove items.

Response

{ "success": true, "removed": 3 }

Export a control collection

GET /api/v1/control-collections/{id}/export

Name
id
Type
string
Description
Collection ID.
Name
format
Type
string
Description
Export format: json (default) or csv.

{
  "collection": { "id": "col-uuid", "name": "FedRAMP Moderate baseline" },
  "total": 325,
  "controls": [
    {
      "controlId": "AC-2",
      "framework": "nist-800-53",
      "identifier": "AC-2",
      "title": "Account Management",
      "family": "Access Control",
      "statement": "...",
      "notes": "Critical control"
    }
  ]
}

Returns 404 if not found or caller has no access; 400 for an invalid format.