Lists

A "list" is a curated bundle of STIGs that a user or organization tracks together (e.g. "All Windows STIGs for our Air Force ATO"). Most endpoints accept either a SAMS user token or an integration token scoped to lists:read; mutation endpoints require a SAMS user token.

List user/org lists

GET /api/v1/lists

Name
include
Type
string
Description
Pass slugs to include each list's STIG slugs in the response.

Response

{
  "lists": [
    {
      "id": "list-uuid",
      "name": "Critical Systems",
      "description": "STIGs for critical infrastructure",
      "tags": ["critical"],
      "color": "#FF5733",
      "icon": "shield",
      "visibility": "shared",
      "stigCount": 8,
      "stigSlugs": ["rhel-08", "windows-server-2022"],
      "createdById": "user-uuid",
      "createdByEmail": "ada@example.com",
      "organizationId": "org-uuid",
      "createdAt": "2026-05-15T10:30:00Z",
      "updatedAt": "2026-05-20T14:22:00Z"
    }
  ]
}

SAMS tokens see the user's own lists plus any SHARED lists in their org. Integration tokens see only the lists they have been explicitly assigned to.

Create a list

POST /api/v1/lists

Name
name
Type
string
Description
List 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.
Name
icon
Type
string
Description
Icon key (free-form string).
Name
visibility
Type
string
Description
PRIVATE (default) or SHARED.

Returns 201 with the new list. 400 if name is missing.

Get a list

GET /api/v1/lists/{id}

Returns the list record (without the STIG findings — use the STIGs sub-resource for that).

Returns 404 if not found or the caller has no access.

Update a list

PATCH /api/v1/lists/{id}

Body accepts any subset of name, description, tags, color, icon, visibility. Returns the updated list.

Delete a list

DELETE /api/v1/lists/{id}

Soft-deletes the list. Items are recoverable for 30 days, after which the /api/cron/purge-deleted-lists job hard-deletes them. Only the creator can delete.

Response

{
  "success": true,
  "message": "List deleted. It can be recovered within 30 days."
}

Duplicate a list

POST /api/v1/lists/{id}/duplicate

Creates a private copy of the list (and its STIG memberships) owned by the caller. The new list is always created with PRIVATE visibility regardless of the source.

Returns 201 with the new list.

Export a list

GET /api/v1/lists/{id}/export

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

{
  "list": {
    "id": "list-uuid",
    "name": "Critical Systems",
    "description": "..."
  },
  "stigs": [
    {
      "slug": "rhel-08",
      "title": "RHEL 8 STIG",
      "version": "1.5.0",
      "status": "Accepted",
      "statusDate": "2024-11-15",
      "findingCount": 342,
      "catI": 45,
      "catII": 182,
      "catIII": 115,
      "addedAt": "2026-05-16T08:15:00Z"
    }
  ]
}

List STIGs in a list

GET /api/v1/lists/{id}/stigs

Name
id
Type
string
Description
List ID.
Name
include
Type
string
Description
Pass findings to include each STIG's full finding records.
Name
severity
Type
string
Description
Comma-separated severity filter applied to the included findings: high, medium, low. STIGs with no matching findings are dropped from the result when this filter is set.
Name
page
Type
integer
Description
Page number (default: 1).
Name
limit
Type
integer
Description
Items per page (default: 50, max: 100).

Response

{
  "list": {
    "id": "list-uuid",
    "name": "Critical Systems",
    "stigCount": 8
  },
  "stigs": [
    {
      "slug": "rhel-08",
      "title": "RHEL 8 STIG",
      "version": "1.5.0",
      "status": "Accepted",
      "statusDate": "2024-11-15",
      "findingCount": 342,
      "catI": 45,
      "catII": 182,
      "catIII": 115,
      "addedAt": "2026-05-16T08:15:00Z",
      "notes": "Critical system",
      "findings": [
        {
          "groupId": "V-214010",
          "ruleId": "SV-214010r814063_rule",
          "ruleSeverity": "high",
          "ruleTitle": "The Audit daemon must...",
          "vulnDiscussion": "...",
          "fixText": "...",
          "checkContent": "..."
        }
      ]
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 8, "totalPages": 1 }
}

Add STIGs to a list

POST /api/v1/lists/{id}/stigs

Name
slugs
Type
array
Description
Array of STIG slugs to add. Duplicates are silently ignored.

Response

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

Remove STIGs from a list

DELETE /api/v1/lists/{id}/stigs

Name
slugs
Type
array
Description
Array of STIG slugs to remove.

Response

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

Update a STIG entry's metadata

PUT /api/v1/lists/{id}/stigs/{stigSlug}

Name
notes
Type
string
Description
Free-form notes for this STIG within this list.
Name
position
Type
integer
Description
Display position (used for manual ordering in the UI).

Response

{
  "stigSlug": "rhel-08",
  "notes": "Critical system",
  "position": 1,
  "addedAt": "2026-05-16T08:15:00Z"
}

Returns 404 if the list or STIG entry is not found.