openapi: 3.2.0 info: title: Vulcan API version: 2.4.1 description: | REST API for Vulcan — STIG-ready security guidance authoring platform. All endpoints require session-based authentication via cookie unless noted otherwise. Mutation endpoints return a canonical `{toast: {title, message, variant}}` object. contact: name: MITRE SAF Team url: https://github.com/mitre/vulcan license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: / description: Same-origin (session cookie auth) security: - cookieAuth: [] - tokenAuth: [] tags: - name: Projects description: Project CRUD, export, import, and member management - name: Components description: Component CRUD, spreadsheet import, export, and locking - name: Rules description: Rule CRUD, revert, section locks, and satisfaction relationships - name: Reviews description: Review lifecycle — create, triage, adjudicate, withdraw, admin actions - name: Reactions description: Thumbs up/down reactions on comment reviews - name: Memberships description: Project and component membership management - name: Search description: Global search across projects, components, rules, SRGs, and STIGs - name: Users description: User management and admin operations - name: Benchmarks description: SRG and STIG upload, listing, export, and deletion - name: Auth description: Session authentication — login, logout, current user identity - name: Personal Access Tokens description: Personal Access Token CRUD and admin revocation - name: System description: Version and health check endpoints paths: /api/auth/me: get: operationId: getAuthMe tags: - Auth summary: Current authenticated user identity description: Returns the authenticated user's identity, admin status, and provider. Used by the SPA on every page load to determine auth state, populate the navbar, and guard routes. Returns 401 when not authenticated. responses: '200': description: Authenticated user identity content: application/json: schema: $ref: '#/components/schemas/CurrentUserResponse' examples: regular_user: summary: Non-admin local user value: id: 42 name: Jane Doe email: jane@example.com admin: false provider: null admin_user: summary: Admin user via OIDC value: id: 1 name: Admin email: admin@example.com admin: true provider: oidc '401': $ref: '#/components/responses/Unauthorized' 4XX: $ref: '#/components/responses/ErrorResponse' /api/auth/login: post: operationId: postAuthLogin tags: - Auth security: [] summary: Authenticate with email and password description: Creates a session for local (email/password) authentication. Returns the authenticated user identity on success. Sets a session cookie for subsequent requests. OIDC and LDAP providers use their own OAuth callback flows. requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email description: User's login email address. example: jane@example.com password: type: string format: password description: User's password. example: •••••••••••••••• examples: login: summary: Local login value: email: jane@example.com password: S3cure!#Pass001 responses: '200': description: Authentication successful — session created content: application/json: schema: $ref: '#/components/schemas/CurrentUserResponse' examples: success: summary: Successful login value: id: 42 name: Jane Doe email: jane@example.com admin: false provider: null '401': description: Invalid email or password, or the account is temporarily locked after too many failed attempts (RFC 9457 problem details). content: application/problem+json: schema: type: object additionalProperties: false required: - type - title - status - detail properties: type: type: string description: Stable machine identifier for the error class. example: /docs/api/errors#invalid_credentials title: type: string description: Short human summary of the error class. example: Invalid credentials status: type: integer description: HTTP status code, repeated in the body. example: 401 detail: type: string description: Occurrence-specific human explanation. example: The email or password is incorrect. examples: invalid_credentials: summary: Bad credentials value: type: /docs/api/errors#invalid_credentials title: Invalid credentials status: 401 detail: The email or password is incorrect. account_locked: summary: Account locked after too many failed attempts value: type: /docs/api/errors#account_locked title: Account locked status: 401 detail: This account is temporarily locked due to too many failed sign-in attempts. Please try again later or reset your password. 4XX: $ref: '#/components/responses/ErrorResponse' /api/auth/logout: delete: operationId: deleteAuthLogout tags: - Auth summary: Sign out and destroy session description: Destroys the current session. Subsequent requests require re-authentication. Returns a confirmation message. responses: '200': description: Session destroyed content: application/json: schema: type: object required: - message properties: message: type: string description: Confirmation message. example: Signed out successfully examples: success: summary: Signed out value: message: Signed out successfully '401': $ref: '#/components/responses/Unauthorized' 4XX: $ref: '#/components/responses/ErrorResponse' /api/navigation: get: operationId: getNavigation tags: - System summary: App shell navigation data description: Returns navbar links, pending access request notifications, and locked user alerts for the authenticated user. Used by the SPA app shell on every page load after authentication. responses: '200': description: Navigation data for app shell content: application/json: schema: $ref: '#/components/schemas/NavigationResponse' examples: admin: summary: Admin user with pending requests value: nav_links: - icon: folder2-open name: Projects link: /projects - icon: patch-check-fill name: Released Components link: /components access_requests: - id: 1 user: id: 42 name: Jane Doe email: jane@example.com project: id: 7 name: RHEL 9 STIG locked_users: - id: 99 name: Locked User email: locked@example.com regular: summary: Non-admin user value: nav_links: - icon: folder2-open name: Projects link: /projects access_requests: [] locked_users: [] '401': $ref: '#/components/responses/Unauthorized' 4XX: $ref: '#/components/responses/ErrorResponse' /api/settings: get: operationId: getSettings tags: - System security: [] summary: Public pre-auth UI configuration description: 'Returns application settings needed before authentication: banner, consent modal, auth provider flags, password policy, and registration status. No authentication required — the login page and consent banner need this data before the user signs in.' responses: '200': description: Public settings for SPA pre-auth UI content: application/json: schema: $ref: '#/components/schemas/SettingsResponse' examples: default: summary: Typical deployment value: banner: enabled: true text: UNCLASSIFIED background_color: '#007a33' text_color: '#ffffff' consent: enabled: false version: 1 title: Terms of Use content: '' ttl: 0 local_login: enabled: true user_registration: enabled: true ldap: enabled: false title: null oidc: enabled: false title: null smtp: enabled: false password: min_length: 15 min_uppercase: 2 min_lowercase: 2 min_number: 2 min_special: 2 lockout: enabled: true maximum_attempts: 3 last_attempt_warning: true 4XX: $ref: '#/components/responses/ErrorResponse' /api/version: get: operationId: getVersion tags: - System security: [] summary: Application version and metadata description: Returns the application name, version, Rails version, Ruby version, and environment. No authentication required — used by monitoring tools, deployment verification scripts, and the frontend health check. responses: '200': description: Version and runtime metadata content: application/json: schema: $ref: '#/components/schemas/VersionResponse' examples: production: summary: Typical production response value: name: Vulcan version: 2.4.1 rails: 8.1.3.1 ruby: 3.4.10 environment: production 4XX: $ref: '#/components/responses/ErrorResponse' /api/search/global: get: operationId: globalSearch tags: - Search summary: Search across all resource types description: Searches projects, components, rules, SRGs, and STIGs by name or title. Results are grouped by type and limited per group. Project results cover everything the caller can discover (memberships plus discoverable projects); component and rule content is served only from the caller's memberships and released components; SRG/STIG results and the srg_rules requirement catalog are instance-global. The rules group covers both document kinds — stig rules and authored SRG requirements — and can be scoped to a specific component via the component_id parameter. Requires authentication — returns 401 if not signed in. parameters: - $ref: '#/components/parameters/SearchQuery' - name: limit in: query description: Maximum results per resource type. schema: type: integer minimum: 1 maximum: 20 default: 5 example: 5 - name: component_id in: query description: Scope rule search to a specific component. schema: type: integer example: 29 responses: '200': description: Search results grouped by type content: application/json: schema: $ref: '#/components/schemas/GlobalSearchResponse' examples: results: summary: Search for "container" value: projects: - id: 4 name: Container Platform components: - id: 29 name: Container SRG rules: [] stig_rules: [] srg_rules: [] srgs: - id: 1 title: Container Platform Security Requirements Guide stigs: [] '401': $ref: '#/components/responses/Unauthorized' 4XX: $ref: '#/components/responses/ErrorResponse' /api/users/search: get: operationId: searchUsers tags: - Search summary: Search users by name or email description: Searches user accounts by name or email address. Used by the membership assignment UI to find users to add to projects. Requires authentication. parameters: - $ref: '#/components/parameters/SearchQuery' - name: membership_type in: query required: true description: Type of resource to search members for. schema: type: string enum: - Project - Component example: Project - name: membership_id in: query required: true description: ID of the project or component to search members for. schema: type: integer example: 1 - name: scope in: query required: false description: Search scope. Default searches non-members (for "add member" flow, admin only). "members" searches existing members (for PoC selection, any member). schema: type: string enum: - members example: members - name: limit in: query required: false description: Maximum number of results (1-25, default 10). schema: type: integer minimum: 1 maximum: 25 example: 10 responses: '200': description: Matching users content: application/json: schema: type: object required: - users additionalProperties: false properties: users: type: array description: Matching users (id, name, email only — minimal shape for dropdowns). items: type: object additionalProperties: false required: - id - name - email properties: id: type: integer description: User ID. example: 42 name: type: - string - 'null' description: Display name. example: Jane Doe email: type: string format: email description: Email address. example: jane.doe@example.org examples: results: summary: Search for "jane" value: users: - id: 42 name: Jane Doe email: jane.doe@example.org 4XX: $ref: '#/components/responses/ErrorResponse' /api/projects: get: operationId: listApiProjects tags: - Projects summary: List projects with pagination, search, and sorting description: Paginated project listing for SPA consumption. Supports substring search over name and description, whitelist-validated sorting, and pagy-backed pagination (default 25 per page, maximum 100). Unknown sort fields are silently ignored. Requires authentication. Returns 400 when the requested page is out of range. Timestamps on this endpoint are ISO 8601 (render_as_json path), unlike the string-rendered project pages. parameters: - name: q in: query required: false description: Case-insensitive substring filter matched against project name and description. schema: type: string example: Photon - name: sort in: query required: false description: Sort field. Unknown fields are silently ignored. schema: type: string enum: - name - created_at - updated_at example: name - name: order in: query required: false description: Sort direction. Defaults to asc when sort is applied. schema: type: string enum: - asc - desc example: asc - name: page in: query required: false description: Page number (1-based). Out-of-range pages return 400. schema: type: integer example: 1 - name: per_page in: query required: false description: Records per page (default 25, capped at 100). schema: type: integer example: 25 responses: '200': description: Paginated project rows content: application/json: schema: type: object required: - rows - pagination additionalProperties: false properties: rows: type: array description: Projects on the current page. items: $ref: '#/components/schemas/ProjectSummary' pagination: $ref: '#/components/schemas/PaginationMeta' examples: first_page: summary: First page of projects value: rows: - id: 34 name: Photon 3 description: null visibility: discoverable memberships_count: 2 admin_name: Demo Admin admin_email: admin@example.org created_at: '2026-05-30T14:06:03.797Z' updated_at: '2026-05-30T14:06:28.292Z' pagination: page: 1 per_page: 25 total: 1 '400': description: Requested page is out of range (RFC 9457 problem details) content: application/problem+json: schema: type: object additionalProperties: false required: - type - title - status - detail properties: type: type: string description: Stable machine identifier for the error class. example: /docs/api/errors#page_out_of_range title: type: string description: Short human summary of the error class. example: Page out of range status: type: integer description: HTTP status code, repeated in the body. example: 400 detail: type: string description: Error message naming the valid page range. example: Page 9999 is out of range (1..2) examples: page_out_of_range: summary: Page beyond the last available page value: type: /docs/api/errors#page_out_of_range title: Page out of range status: 400 detail: Page 9999 is out of range (1..2) '401': $ref: '#/components/responses/Unauthorized' /api/srgs/latest: get: operationId: latestSrgs tags: - Benchmarks summary: List the latest release of each SRG description: Returns one row per SRG — its numerically highest V{major}R{minor} release — for dropdown population. Public reference data, no authentication required. The q parameter filters SRGs by case-insensitive substring with abbreviation expansion (GPOS matches General Purpose Operating System); queries shorter than 2 characters return no rows. security: [] parameters: - name: q in: query required: false description: SRG filter — case-insensitive substring matched against name, title, and srg_id, with abbreviation expansion (minimum 2 characters). schema: type: string example: GPOS responses: '200': description: Latest release of each SRG, ordered by title content: application/json: schema: $ref: '#/components/schemas/BenchmarkLatestResponse' examples: latest: summary: Latest SRGs value: rows: - id: 42 srg_id: General_Purpose_Operating_System title: General Purpose Operating System Security Requirements Guide version: V3R3 name: General Purpose Operating System - Ver 3, Rel 3 - id: 43 srg_id: Web_Server_SRG title: Web Server Security Requirements Guide version: V4R4 name: Web Server SRG - Ver 4, Rel 4 /api/srgs/{id}/stats: get: operationId: srgStats tags: - Benchmarks summary: Get rule counts and component usage for an SRG description: Returns the SRG's rule count, severity breakdown, and which components are based on it. Usage is scoped to components the caller can see (member projects or released) — the count and list use the same scope, so hidden usage is never revealed. Requires authentication. parameters: - name: id in: path required: true description: Numeric ID of the SRG. schema: type: integer example: 3 responses: '200': description: SRG stats with caller-scoped usage content: application/json: schema: $ref: '#/components/schemas/BenchmarkStatsResponse' examples: stats: summary: SRG stats value: rule_count: 250 severity_counts: high: 30 medium: 200 low: 20 usage: count: 2 components: - id: 38 name: RHEL 9 Hardened Baseline project_id: 7 project_name: RHEL Hardening - id: 41 name: Photon OS 5 Baseline project_id: 9 project_name: Photon OS 5 Hardening '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /api/stigs/latest: get: operationId: latestStigs tags: - Benchmarks summary: List the latest release of each STIG description: Returns one row per STIG — its numerically highest V{major}R{minor} release — for dropdown population. Public reference data, no authentication required. The q parameter filters STIGs by case-insensitive substring with abbreviation expansion (RHEL matches Red Hat Enterprise Linux); queries shorter than 2 characters return no rows. security: [] parameters: - name: q in: query required: false description: STIG filter — case-insensitive substring matched against name, title, and stig_id, with abbreviation expansion (minimum 2 characters). schema: type: string example: RHEL responses: '200': description: Latest release of each STIG, ordered by title content: application/json: schema: $ref: '#/components/schemas/BenchmarkLatestResponse' examples: latest: summary: Latest STIGs value: rows: - id: 7 stig_id: RHEL_9_STIG title: Red Hat Enterprise Linux 9 Security Technical Implementation Guide version: V2R7 name: RHEL 9 STIG - Ver 2, Rel 7 /api/stigs/{id}/stats: get: operationId: stigStats tags: - Benchmarks summary: Get rule counts for a STIG description: Returns the STIG's rule count and severity breakdown. Pure reference data — no usage section (components are based on SRGs, not STIGs) — and public like the rest of the STIG catalog. security: [] parameters: - name: id in: path required: true description: Numeric ID of the STIG. schema: type: integer example: 4 responses: '200': description: STIG rule counts and severity breakdown content: application/json: schema: $ref: '#/components/schemas/BenchmarkStatsResponse' examples: stats: summary: STIG stats value: rule_count: 380 severity_counts: high: 40 medium: 300 low: 40 '404': $ref: '#/components/responses/NotFound' /api/components/latest: get: operationId: latestComponents tags: - Benchmarks summary: List the latest released component per prefix description: Returns one released component per prefix — the numerically highest version/release pair — for dropdown population. A component is a STIG in progress; released ones are instance-wide reference data for any authenticated user. Unreleased drafts never appear. The q parameter filters components by case-insensitive substring with abbreviation expansion (RHEL matches Red Hat Enterprise Linux); queries shorter than 2 characters return no rows. parameters: - name: q in: query required: false description: Component filter — case-insensitive substring matched against name, prefix, and title, with abbreviation expansion (minimum 2 characters). schema: type: string example: RHEL-09 responses: '200': description: Latest released component per prefix, ordered by prefix content: application/json: schema: $ref: '#/components/schemas/ComponentLatestResponse' examples: latest: summary: Latest released components value: rows: - id: 38 prefix: RHEL-09 name: RHEL 9 Hardened Baseline title: Red Hat Enterprise Linux 9 version: 2 release: 1 '401': $ref: '#/components/responses/Unauthorized' /api/components/{id}/summary: get: operationId: componentSummary tags: - Components summary: Get a lightweight component summary description: 'Returns the component header — identity, counts, SRG info, the caller''s effective permissions, and the serialized comment-phase state machine — without the heavy rules/reviews/histories arrays. Access matches the component show rules: released components are readable by any authenticated user; unreleased ones require viewer permission.' parameters: - name: id in: path required: true description: Numeric ID of the component. schema: type: integer example: 38 responses: '200': description: Component summary with phase state content: application/json: schema: $ref: '#/components/schemas/ComponentSummaryResponse' examples: open_period: summary: Component in an open comment period value: id: 38 name: RHEL 9 Hardened Baseline prefix: RHEL-09 document_type: stig title: Red Hat Enterprise Linux 9 version: 2 release: 1 released: false project_id: 7 component_id: null security_requirements_guide_id: 3 based_on_title: General Purpose Operating System Security Requirements Guide based_on_version: V3R3 rules_count: 203 memberships_count: 4 severity_counts: high: 20 medium: 173 low: 10 pending_comment_count: 5 effective_permissions: viewer updated_at: '2026-07-10T14:07:37.142Z' comment_phase: open closed_reason: null comment_period_starts_at: '2026-07-01T00:00:00.000Z' comment_period_ends_at: '2026-07-15T00:00:00.000Z' accepting_new_comments: true triaging_active: true frozen_for_writes: false comment_period_days_remaining: 5 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /api/components/{id}/stats: get: operationId: componentStats tags: - Components summary: Get rule statistics for a component description: 'Returns rule counts by status and severity plus completion and lock percentages, computed as SQL aggregates. Access matches the component show rules: released components are readable by any authenticated user; unreleased ones require viewer permission.' parameters: - name: id in: path required: true description: Numeric ID of the component. schema: type: integer example: 38 responses: '200': description: Component rule statistics content: application/json: schema: $ref: '#/components/schemas/ComponentStatsResponse' examples: stats: summary: Component stats value: document_type: stig rules_by_status: not_yet_determined: 50 applicable_configurable: 120 applicable_inherently_meets: 15 applicable_does_not_meet: 8 not_applicable: 10 rules_by_severity: high: 20 medium: 173 low: 10 rule_count: 203 completion_pct: 75.4 lock_pct: 12.3 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /api/components/{id}/workflow_state: get: operationId: componentWorkflowState tags: - Components summary: Get workflow readiness for a component description: 'Returns where the component stands across the authoring, lock, review, comment, triage, and export stages — SQL-aggregated counts plus the comment-phase write-guard booleans. Access matches the component show rules: released components are readable by any authenticated user; unreleased ones require viewer permission.' parameters: - name: id in: path required: true description: Numeric ID of the component. schema: type: integer example: 38 responses: '200': description: Component workflow state content: application/json: schema: $ref: '#/components/schemas/ComponentWorkflowStateResponse' examples: in_progress: summary: Component mid-authoring with an open comment period value: document_type: stig authoring: rules_total: 203 rules_determined: 153 locks: locked: 25 total: 203 all_locked: false reviews: under_review: 4 comment: phase: open accepting_new_comments: true triaging_active: true frozen_for_writes: false pending_comments: 3 triage: pending: 3 awaiting_adjudication: 1 export: released: false releasable: false '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /api/components/{id}/triage_summary: get: operationId: componentTriageSummary tags: - Components summary: Get triage summary for a component description: 'Returns top-level comment counts per triage status plus the adjudication percentage — rule-attached and component-attached comments both count. Access matches the component show rules: released components are readable by any authenticated user; unreleased ones require viewer permission.' parameters: - name: id in: path required: true description: Numeric ID of the component. schema: type: integer example: 38 responses: '200': description: Component triage summary content: application/json: schema: $ref: '#/components/schemas/TriageSummaryResponse' examples: summary: summary: Component with comments in triage value: by_triage_status: pending: 3 concur: 1 concur_with_comment: 0 non_concur: 0 duplicate: 0 informational: 1 needs_clarification: 0 withdrawn: 0 addressed_by: 0 total: 5 adjudicated: 1 adjudication_pct: 20 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /api/projects/{id}/stats: get: operationId: projectStats tags: - Projects summary: Get rule statistics for a project description: Returns rule statistics aggregated across every component in the project plus a per-component breakdown, computed from grouped SQL queries. Requires viewer permission on the project. parameters: - name: id in: path required: true description: Numeric ID of the project. schema: type: integer example: 7 responses: '200': description: Project rule statistics with per-component breakdown content: application/json: schema: $ref: '#/components/schemas/ProjectStatsResponse' examples: stats: summary: Project with two components value: aggregate: rules_by_status_by_type: stig: not_yet_determined: 51 applicable_configurable: 121 applicable_inherently_meets: 15 applicable_does_not_meet: 8 not_applicable: 10 srg: not_yet_determined: 2 applicable: 1 not_applicable: 0 rules_by_severity: high: 21 medium: 176 low: 11 rule_count: 208 completion_pct: 74.5 lock_pct: 12 components: - id: 38 name: RHEL 9 Hardened Baseline prefix: RHEL-09 document_type: stig rule_count: 203 completion_pct: 75.4 lock_pct: 12.3 - id: 41 name: Photon OS 5 Baseline prefix: PHTN-50 document_type: srg rule_count: 5 completion_pct: 40 lock_pct: 0 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /api/projects/{id}/triage_summary: get: operationId: projectTriageSummary tags: - Projects summary: Get triage summary for a project description: Returns triage metrics aggregated across all of the project's components — top-level comment counts per triage status plus the adjudication percentage. Requires viewer permission on the project. parameters: - name: id in: path required: true description: Numeric ID of the project. schema: type: integer example: 7 responses: '200': description: Project-wide triage summary content: application/json: schema: $ref: '#/components/schemas/TriageSummaryResponse' examples: summary: summary: Project with comments in triage value: by_triage_status: pending: 3 concur: 1 concur_with_comment: 0 non_concur: 0 duplicate: 0 informational: 1 needs_clarification: 0 withdrawn: 0 addressed_by: 0 total: 5 adjudicated: 1 adjudication_pct: 20 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /search/rules: get: operationId: searchRulesLegacy tags: - Search summary: Legacy requirement search by SRG version description: 'Searches requirement rows of both document kinds — stig rules and authored SRG requirements — by version identifier. Scoped to components the user can access: project or component membership, or released components; admins are unrestricted. Returns compact tuples [id, rule_id, component_id, prefix]. Requires authentication. This is a legacy search endpoint — prefer /api/search/global for new integrations.' parameters: - name: q in: query required: true description: SRG version identifier to search for. schema: type: string example: SRG-OS-000001-GPOS-00001 responses: '200': description: Matching rules as compact tuples content: application/json: schema: type: object required: - rules properties: rules: type: array description: Each item is a tuple [rule_id, rule_id_string, component_id, prefix]. items: type: array items: {} examples: results: summary: Rules matching SRG version value: rules: - - 1786 - '000001' - 1 - PHOS-03 - - 2500 - '000001' - 5 - CNTR-01 4XX: $ref: '#/components/responses/ErrorResponse' /search/components: get: operationId: searchComponentsLegacy tags: - Search summary: Legacy component search by SRG ID description: 'Searches components by the SRG identifier they are based on. Scoped to components the user can access: project or component membership, or released components; admins are unrestricted. Returns compact tuples [id, name]. This is a legacy search endpoint — prefer /api/search/global for new integrations.' parameters: - name: q in: query required: true description: SRG identifier to search for. schema: type: string example: Container_Platform_SRG responses: '200': description: Matching components as compact tuples content: application/json: schema: type: object required: - components additionalProperties: false properties: components: type: array description: Each item is a tuple [id, name]. items: type: array items: {} examples: results: summary: Components matching SRG value: components: - - 1 - Photon OS 3 - - 8 - Container Platform 4XX: $ref: '#/components/responses/ErrorResponse' /search/projects: get: operationId: searchProjectsLegacy tags: - Search summary: Legacy project search by SRG ID description: Searches projects that have components based on a given SRG. Returns compact tuples [id, name]. This is a legacy search endpoint — prefer /api/search/global for new integrations. parameters: - name: q in: query required: true description: SRG identifier to search for. schema: type: string example: Container_Platform_SRG responses: '200': description: Matching projects as compact tuples content: application/json: schema: type: object required: - projects additionalProperties: false properties: projects: type: array description: Each item is a tuple [id, name]. items: type: array items: {} examples: results: summary: Projects with matching SRG components value: projects: - - 4 - Container Platform 4XX: $ref: '#/components/responses/ErrorResponse' /projects: get: operationId: listProjects tags: - Projects summary: List accessible projects description: Returns all projects the current user can access, including owned projects, member projects, and discoverable projects. Includes membership counts and pending comment counts per project. Requires authentication. responses: '200': description: Projects list content: application/json: schema: type: array items: $ref: '#/components/schemas/ProjectIndexResponse' examples: projects: summary: Two accessible projects value: - id: 4 name: Container Platform memberships_count: 14 - id: 1 name: Photon 3 memberships_count: 14 4XX: $ref: '#/components/responses/ErrorResponse' post: operationId: createProject tags: - Projects summary: Create a new project description: Creates a new project with the given name and description. The creating user is automatically added as an admin member. Requires authentication. requestBody: required: true content: application/json: schema: type: object properties: project: description: The shared project input surface plus the create-only slack_channel_id convenience field, which merges into the metadata data hash as "Slack Channel ID" and wins over a same-key entry supplied in project_metadata_attributes. allOf: - $ref: '#/components/schemas/ProjectInput' - type: object properties: slack_channel_id: type: string description: Convenience field — stored as the metadata key "Slack Channel ID". Accepted at creation only; use project_metadata_attributes on update. example: C0123456789 examples: create: summary: Create a new project value: project: name: Red Hat Enterprise Linux 9 description: STIG development for RHEL 9 create_with_metadata: summary: Create with metadata in the same call value: project: name: Red Hat Enterprise Linux 9 description: STIG development for RHEL 9 visibility: discoverable project_metadata_attributes: data: POC Name: Jane Doe POC Email: jane@example.com responses: '200': description: Project created content: application/json: schema: $ref: '#/components/schemas/ProjectCreateResponse' examples: created: summary: Project created value: toast: title: Project created. message: - Successfully created project Red Hat Enterprise Linux 9. variant: success redirect_url: /projects/5 '422': $ref: '#/components/responses/UnprocessableEntity' 4XX: $ref: '#/components/responses/ErrorResponse' /projects/{projectId}: parameters: - $ref: '#/components/parameters/ProjectId' get: operationId: getProject tags: - Projects summary: Project detail with component list and stats description: Returns full project details including components, membership count, comment counts, and project metadata. Requires membership in the project or admin role. responses: '200': description: Project detail with components content: application/json: schema: $ref: '#/components/schemas/ProjectShowResponse' examples: project: summary: Photon 3 project detail value: id: 1 name: Photon 3 memberships_count: 16 pending_comment_count: 1 components: - id: 1 name: Photon OS 3 prefix: PHOS-03 4XX: $ref: '#/components/responses/ErrorResponse' patch: operationId: patchProject tags: - Projects summary: Partial update of project attributes description: Partial update — send only changed fields. Updates the project name, description, or visibility. Requires admin role on the project. Returns a canonical toast response. requestBody: required: true content: application/json: schema: type: object properties: project: $ref: '#/components/schemas/ProjectInput' examples: rename: summary: Rename a project value: project: name: Container Platform v2 responses: '200': description: Project updated content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: updated: summary: Project renamed value: toast: title: Project updated. message: - Successfully updated project. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' put: operationId: updateProject tags: - Projects summary: Full replacement of project attributes description: Full replacement — all fields required. Updates the project name, description, or visibility. Requires admin role on the project. Returns a canonical toast response. requestBody: required: true content: application/json: schema: type: object properties: project: $ref: '#/components/schemas/ProjectInput' examples: rename: summary: Rename a project value: project: name: Container Platform v2 responses: '200': description: Project updated content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: updated: summary: Project renamed value: toast: title: Project updated. message: - Successfully updated project. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteProject tags: - Projects summary: Delete a project and all its components description: Permanently deletes the project, all its components, rules, reviews, and memberships. Requires admin role on the project. This action cannot be undone. Returns 403 for non-admin users. responses: '200': description: Project deleted content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: deleted: summary: Project deleted value: toast: title: Project deleted. message: - Successfully deleted project. variant: success '403': $ref: '#/components/responses/Forbidden' 4XX: $ref: '#/components/responses/ErrorResponse' /projects/{projectId}/comments: parameters: - $ref: '#/components/parameters/ProjectId' get: operationId: getProjectComments tags: - Projects summary: Aggregated comments across all project components description: Returns paginated comments from all components in the project, with triage status counts. Different row shape from component comments — includes component_id/component_name but omits some triage attribution fields. Uses Project#paginated_comments (NOT CommentQueryService). parameters: - $ref: '#/components/parameters/TriageStatusFilter' - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/PerPageParam' - name: section in: query description: Filter by requirement section (fixtext, check_content, etc.). schema: type: string example: fixtext - name: component_id in: query required: false description: Filter to a specific component within the project. schema: type: integer - name: author_id in: query required: false description: Filter by comment author. schema: type: integer - name: q in: query required: false description: Text search within comment content. schema: type: string - name: resolved in: query required: false description: Filter by resolved state (true/false/all). schema: type: string enum: - 'true' - 'false' - all example: 'false' responses: '200': description: Paginated project comment rows with status counts content: application/json: schema: type: object required: - rows - pagination - status_counts properties: rows: type: array description: Comment rows with component context. items: type: object properties: id: type: integer rule_id: type: - integer - 'null' rule_displayed_name: type: - string - 'null' commentable_type: type: string component_id: type: - integer - 'null' component_name: type: - string - 'null' section: type: - string - 'null' author_name: type: - string - 'null' comment: type: string created_at: type: string triage_status: type: - string - 'null' triage_set_at: type: - string - 'null' adjudicated_at: type: - string - 'null' duplicate_of_review_id: type: - integer - 'null' triager_display_name: type: - string - 'null' triager_imported: type: boolean adjudicator_display_name: type: - string - 'null' adjudicator_imported: type: boolean responses_count: type: integer reactions: type: object properties: up: type: integer down: type: integer mine: type: - string - 'null' pagination: type: object required: - page - per_page - total properties: page: type: integer per_page: type: integer total: type: integer status_counts: type: object additionalProperties: type: integer examples: comments: summary: Project-wide comment queue value: rows: - id: 26 rule_displayed_name: PHOS-03-000038 component_id: 1 component_name: Photon OS 3 triage_status: pending comment: This requirement needs clarification. responses_count: 0 reactions: up: 0 down: 0 mine: null pagination: page: 1 per_page: 25 total: 3 status_counts: pending: 1 concur: 1 informational: 1 4XX: $ref: '#/components/responses/ErrorResponse' /projects/{projectId}/export/{type}: parameters: - $ref: '#/components/parameters/ProjectId' - name: type in: path required: true description: Export format. schema: type: string enum: - csv - xccdf - inspec - json_archive example: xccdf get: operationId: exportProject tags: - Projects summary: Export project data in the specified format description: Exports selected components from the project as CSV, XCCDF XML, InSpec profile, or JSON archive. Supports mode selection (working copy, vendor submission, published STIG) and optional SRG/membership inclusion. Returns a binary file download. Requires project membership. parameters: - name: component_ids in: query required: true description: Comma-separated IDs of components to include in the export. schema: type: string example: 29,30 - name: mode in: query description: Export mode controlling which fields and rules are included. schema: type: string enum: - working_copy - vendor_submission - published_stig example: working_copy - name: include_srg in: query description: Include the source SRG in the export package. schema: type: string enum: - 'true' - name: include_memberships in: query description: Include project membership data in the export. schema: type: string enum: - 'true' - 'false' - name: exclude_satisfied_by in: query description: Exclude rules that are satisfied by another rule. schema: type: string enum: - 'true' responses: '200': description: Binary file download (CSV, XML, ZIP, or JSON) content: text/csv: schema: type: string format: binary application/xml: schema: type: string format: binary application/zip: schema: type: string format: binary application/json: schema: type: string format: binary 4XX: $ref: '#/components/responses/ErrorResponse' /projects/create_from_backup: post: operationId: createFromBackup tags: - Projects summary: Create a new project from a JSON archive backup description: Creates a new project by restoring from a JSON archive (.zip). The archive must have been created by the json_archive export. Optionally override the project name. The archived project metadata (project.json) is restored onto the new project. The creating user becomes the project admin. Requires authentication. requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: JSON archive .zip file from a previous export. name: type: string description: Override project name. Uses the archived name if omitted. example: Restored Container Platform responses: '200': description: Dry-run returns preview (summary + warnings + project_defaults). Real create returns redirect URL + summary + toast. content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreateFromBackupDryRunResponse' - $ref: '#/components/schemas/CreateFromBackupResponse' examples: dry_run: summary: Preview of what would be imported value: summary: dry_run: true components_imported: 2 rules_imported: 264 component_details: - name: Photon OS 3 rule_count: 132 warnings: [] project_defaults: name: My Original Project description: A test project visibility: discoverable created: summary: Project created from archive value: redirect_url: /projects/123 summary: components_imported: 2 rules_imported: 264 toast: title: Project imported. message: - Project created from backup successfully. variant: success '422': description: Import or preview failed content: application/json: schema: type: object required: - toast properties: toast: $ref: '#/components/schemas/ToastObject' warnings: type: array items: type: string project_defaults: type: object properties: name: type: - string - 'null' description: type: - string - 'null' visibility: type: - string - 'null' 4XX: $ref: '#/components/responses/ErrorResponse' /projects/{projectId}/import_backup: parameters: - $ref: '#/components/parameters/ProjectId' post: operationId: importBackup tags: - Projects summary: Import a JSON archive backup description: Imports components, rules, reviews, and memberships from a JSON archive (.zip) into the project, replacing or augmenting existing content. Returns 200 with a toast + summary. Requires admin role on the project. The archive must have been created by the json_archive export format. requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: JSON archive .zip file from a previous export. responses: '200': description: Backup imported (default mode) or dry-run preview completed content: application/json: schema: $ref: '#/components/schemas/ImportBackupResponse' examples: imported: summary: Archive imported successfully value: toast: title: Backup restored. message: - Backup restored successfully. variant: success summary: components_imported: 2 rules_imported: 264 satisfactions_imported: 12 reviews_imported: 48 memberships_imported: 3 srgs_imported: 1 component_details: - name: Photon OS 3 rule_count: 132 srg_title: General Purpose Operating System SRG srg_version: V3R3 warnings: [] '422': description: Import failed (validation errors) content: application/json: schema: type: object required: - toast properties: toast: $ref: '#/components/schemas/ToastObject' warnings: type: array items: type: string 4XX: $ref: '#/components/responses/ErrorResponse' /projects/{projectId}/histories: parameters: - $ref: '#/components/parameters/ProjectId' get: operationId: getProjectHistories tags: - Projects summary: Audit history for the project description: Returns the 50 most recent audit trail entries for the project, including component and rule changes. Used by the project history sidebar. Requires project membership. responses: '200': description: Recent audit entries content: application/json: schema: type: array items: $ref: '#/components/schemas/AuditEntry' examples: history: summary: Recent project changes value: - id: 500 auditable_type: Component auditable_id: 38 action: update name: Demo Admin created_at: '2026-05-28T15:00:00Z' audited_changes: - field: released prev_value: false new_value: true 4XX: $ref: '#/components/responses/ErrorResponse' /components: get: operationId: listComponents tags: - Components summary: List released components description: Returns all released (published) components visible to the current user. Released components are read-only snapshots that have been through the DISA review process. Requires authentication. responses: '200': description: Released components content: application/json: schema: type: array items: $ref: '#/components/schemas/ComponentIndexResponse' examples: components: summary: Two released components value: - id: 29 name: Container SRG prefix: CNTR version: 1 release: 1 released: true - id: 30 name: Photon OS 3 prefix: PHOS-03 version: 1 release: 1 released: true 4XX: $ref: '#/components/responses/ErrorResponse' /projects/{projectId}/components: parameters: - $ref: '#/components/parameters/ProjectId' post: operationId: createComponent tags: - Components summary: Create or duplicate a component in a project description: Creates a new component in the project from one or more declared source SRGs, duplicates an existing component, or imports from an uploaded XCCDF/CSV file. Requires admin role on the project. The component is initialized with requirements from every declared source (full union by default, or the requirement_selections subset) — security_requirements_guide_id designates the primary. requestBody: required: true content: application/json: schema: type: object properties: component: $ref: '#/components/schemas/ComponentInput' examples: from_srg: summary: Create from an SRG baseline value: component: name: Container SRG prefix: CNTR title: Container Platform Security Technical Implementation Guide version: 1 release: 1 security_requirements_guide_id: 1 multi_source_srg: summary: Create a dual-home SRG component from two core sources value: component: name: Container Platform SRG prefix: CNTR title: Container Platform Security Requirements Guide version: 1 release: 1 document_type: srg security_requirements_guide_id: 1 declared_source_srg_ids: - 1 - 2 one_call_with_extras: summary: Create complete in one call — metadata, questions, advanced fields value: component: name: Container SRG prefix: CNTR title: Container Platform Security Technical Implementation Guide version: 1 release: 1 security_requirements_guide_id: 1 advanced_fields: true component_metadata_attributes: data: Vendor: Acme POC: Sam additional_questions_attributes: - name: Deployment environment question_type: dropdown options: - Cloud - On-prem multipart/form-data: schema: type: object properties: file: type: string format: binary description: XCCDF XML or CSV file to import as a component. responses: '200': description: Component created content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: created: summary: Component created from SRG value: toast: title: Component created. message: - Successfully created component Container SRG. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}: parameters: - $ref: '#/components/parameters/ComponentId' get: operationId: getComponent tags: - Components summary: Component detail with rules description: 'Returns full component details including all rules with their content fields, for either document kind. Members (any role) receive the editor view; a non-member receives the read-only show view for a RELEASED component (released components are never concealed, whatever the project''s visibility). An unreleased component answers a non-member per the disclosure policy: 403 with the project admins to ask when the project is discoverable, or the concealment 404 when it is hidden.' responses: '200': description: Component with rules — the editor view for members, the read-only show view otherwise. A null effective_permissions marks the show branch. The two shapes share their core fields, so they are documented as anyOf. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ComponentEditorResponse' - $ref: '#/components/schemas/ComponentShowResponse' examples: component: summary: Component editor view (project member) value: id: 1 name: Photon OS 3 prefix: PHOS-03 title: Photon OS 3 STIG Readiness Guide rules_count: 203 comment_phase: open version: 1 release: 1 released: false non_member_show: summary: Read-only show view (non-member, released component) value: id: 1 name: Photon OS 3 prefix: PHOS-03 title: Photon OS 3 STIG Readiness Guide released: true effective_permissions: null '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' 4XX: $ref: '#/components/responses/ErrorResponse' put: operationId: updateComponent tags: - Components summary: Update component attributes description: Updates component metadata (name, prefix, version, release, description). Requires admin role on the parent project. Does not modify rules — use the rule endpoints for rule content changes. requestBody: required: true content: application/json: schema: type: object properties: component: $ref: '#/components/schemas/ComponentUpdateInput' examples: update: summary: Update version and release value: component: version: 2 release: 1 responses: '200': description: Component updated content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: updated: summary: Component updated value: toast: title: Component updated. message: - Successfully updated component. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' patch: operationId: patchComponent tags: - Components summary: Partial update of component attributes description: Partial update — same behavior as PUT but only supplied fields are changed. Requires admin role on the parent project. requestBody: required: true content: application/json: schema: type: object properties: component: $ref: '#/components/schemas/ComponentUpdateInput' responses: '200': description: Component updated content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteComponent tags: - Components summary: Delete a component and all its rules description: Permanently deletes the component, all its rules, reviews, and associated data. Requires admin role on the parent project. This action cannot be undone. responses: '200': description: Component deleted content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: deleted: summary: Component deleted value: toast: title: Component deleted. message: - Successfully deleted component. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/comments: parameters: - $ref: '#/components/parameters/ComponentId' get: operationId: getComponentComments tags: - Components summary: Paginated triage table for component comments description: Returns paginated public comments on this component's rules, with triage status counts and filtering. Powers the triage page table and split-pane views. Supports filtering by status, section, rule, author, text search, and resolution state. Requires project membership. parameters: - $ref: '#/components/parameters/TriageStatusFilter' - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/PerPageParam' - name: section in: query description: Filter by requirement section (fixtext, check_content, etc.). schema: type: string example: fixtext - name: rule_id in: query description: Filter to comments on a specific rule. schema: type: integer example: 100 - name: author_id in: query description: Filter to comments by a specific author. schema: type: integer example: 42 - name: q in: query description: Full-text search across comment content. schema: type: string example: container image - name: resolved in: query required: false description: Filter by resolved state (true/false/all). schema: type: string enum: - 'true' - 'false' - all example: 'false' - name: commentable_type in: query required: false description: Restrict rows to comments on requirements ("rule") or on the component itself ("component"). Absent or any other value returns both. schema: type: string enum: - rule - component example: rule - name: include_rule_content in: query description: Include rule content fields for split-pane triage view. schema: type: string enum: - 'true' responses: '200': description: Paginated comment rows with status counts content: application/json: schema: $ref: '#/components/schemas/PaginatedComments' examples: comments: summary: Pending comments on Container SRG value: rows: - id: 44 commentable_type: BaseRule rule_displayed_name: CNTR-00-000050 section: fixtext author_name: John Osborne author_email: josborne@example.org comment: This requirement needs clarification... triage_status: pending created_at: '2026-05-19T16:15:00Z' responses_count: 0 reactions: up: 1 down: 0 pagination: page: 1 per_page: 25 total: 1 total_comments: 10 status_counts: pending: 10 concur: 2 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/export/{type}: parameters: - $ref: '#/components/parameters/ComponentId' - name: type in: path required: true description: Export format. schema: type: string enum: - csv - xccdf - inspec - json_archive - disposition_csv example: xccdf get: operationId: exportComponent tags: - Components summary: Export component in the specified format description: 'Downloads the component as CSV, XCCDF XML, InSpec profile, JSON archive, or disposition CSV. Supports mode selection (working_copy, vendor_submission, published_stig) via query param. The xccdf type is kind-routed by the component''s document type: SRG components export their authored requirements through the published_srg mode (only Applicable requirements publish); STIG components use published_stig. disposition_csv is for DISA comment triage matrix export. Requires project membership.' parameters: - name: mode in: query description: Export mode controlling which fields are included. The xccdf type ignores this parameter — its mode is derived from the component's document type (published_srg for SRG kind, published_stig for STIG). schema: type: string enum: - working_copy - vendor_submission - published_stig example: working_copy - name: triage_status in: query description: Filter disposition CSV by triage status. schema: type: string example: pending responses: '200': description: Binary file download content: text/csv: schema: type: string format: binary application/xml: schema: type: string format: binary application/zip: schema: type: string format: binary 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/lock: parameters: - $ref: '#/components/parameters/ComponentId' post: operationId: lockComponent tags: - Components summary: Lock all unlocked rules in a component description: Locks every currently-unlocked rule in the component, preventing further edits. Requires component-admin authority. Already-locked rules are unaffected. requestBody: required: true content: application/json: schema: type: object required: - review properties: review: description: The bulk-lock surface is action + comment only — one review row is generated per locked requirement carrying both, and the comment is required (each generated review validates comment presence). Other review keys (section, responding_to_review_id, component_id) are ignored. type: object required: - action - comment properties: action: type: string description: The review action recorded on every generated row. enum: - lock_control example: lock_control comment: type: string description: Audit trail comment explaining why the component was locked. example: Locking for DISA submission review. examples: lock: summary: Lock with audit comment value: review: action: lock_control comment: Locking for DISA submission review. responses: '200': description: Lockable rules locked. Rules with incomplete data are SKIPPED, not failed — Not Yet Determined without satisfactions, Does Not Meet without mitigations, Inherently Meets without an artifact description — and each skip is named in a warning line appended to the message (variant becomes warning). content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: locked: summary: All candidates locked value: toast: title: Locked 2 controls. message: - 'Locked: CNTR-00-000001, CNTR-00-000002' variant: success locked_with_skips: summary: Some rules skipped for incomplete data value: toast: title: Locked 1 control. message: - |- Locked: CNTR-00-000001 Not Yet Determined (skipped): CNTR-00-000002 variant: warning '422': description: Every candidate rule was skipped — nothing could be locked. content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: nothing_lockable: summary: All candidates skipped value: toast: title: No controls could be locked. message: - 'Not Yet Determined (skipped): CNTR-00-000001, CNTR-00-000002' variant: warning 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/lock_sections: parameters: - $ref: '#/components/parameters/ComponentId' patch: operationId: lockSections tags: - Components summary: Lock or unlock sections on every unlocked rule description: Locks (or unlocks) the named content sections across all unlocked requirement rows in the component — both document kinds. Section names come from the lockable-section vocabulary (Title, Severity, Status, Fix, Check, ...). Locked sections cannot be edited until unlocked. Requires reviewer role or higher on the component. Returns 422 when any section name is not in the vocabulary. requestBody: required: true content: application/json: schema: type: object required: - sections - locked properties: sections: type: array description: Section names to lock or unlock. items: type: string enum: - Title - Severity - Status - Fix - Check - Vulnerability Discussion - DISA Metadata - Vendor Comments - Artifact Description - XCCDF Metadata example: - Fix - Check locked: type: boolean description: True locks the named sections; false unlocks them. example: true comment: type: - string - 'null' description: Optional audit comment recorded on each changed rule. When blank, a generated comment naming the action and sections is recorded instead. example: Content freeze for the review window. examples: lock_fix_check: summary: Lock the Fix and Check sections value: sections: - Fix - Check locked: true comment: Content freeze for the review window. responses: '200': description: Section lock applied across all unlocked rules content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: locked: summary: Sections locked value: toast: title: Section lock applied message: - Locked 2 section(s) on 264 rule(s) variant: success '422': description: A section name is not in the lockable vocabulary content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: invalid_section: summary: Unknown section name value: toast: title: Invalid sections message: - 'Not recognized: fixtext' variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/histories: parameters: - $ref: '#/components/parameters/ComponentId' get: operationId: getComponentHistories tags: - Components summary: Audit history for the component description: Returns the 50 most recent audit trail entries for the component, including rule changes, review actions, and metadata updates. Used by the component history sidebar. Requires project membership. responses: '200': description: Recent audit entries content: application/json: schema: type: array items: $ref: '#/components/schemas/AuditEntry' examples: history: summary: Recent component changes value: - id: 600 auditable_type: Rule auditable_id: 812 action: update name: Demo Admin created_at: '2026-05-28T15:00:00Z' audited_changes: - field: status prev_value: Not Yet Determined new_value: Applicable - Configurable 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/rules: parameters: - $ref: '#/components/parameters/ComponentId' get: operationId: listComponentRules tags: - Rules summary: List all rules for a component description: Returns all rules in the component with full content fields (title, fixtext, check_content, vuln_discussion, etc.). Used by the component editor to populate the rule list. Requires project membership. responses: '200': description: All component rules content: application/json: schema: type: array description: 'Items are shaped by the component''s document_type: STIG rules or authored SRG requirements.' items: oneOf: - $ref: '#/components/schemas/RuleEditorResponse' - $ref: '#/components/schemas/AuthoredSrgRuleEditorResponse' examples: rules: summary: Two rules value: - id: 100 rule_id: CNTR-00-000050 title: Container images must be signed status: Applicable - Configurable locked: false satisfies: [] satisfied_by: [] - id: 101 rule_id: CNTR-00-000051 title: Container images must come from approved registries status: Applicable - Configurable locked: false satisfies: [] satisfied_by: [] 4XX: $ref: '#/components/responses/ErrorResponse' post: operationId: createRule tags: - Rules summary: Create a new requirement in a component description: 'Creates a requirement in one call, shaped by the component''s document_type — a STIG rule (seeded from the source SRG''s CCI-000366 baseline row; severity and weight are inherited from it) or an authored SRG requirement. Content fields apply at creation: provided values win over seeded defaults, and provided nested attributes replace the built defaults. Duplicate mode copies an existing requirement of THIS component. Requirement numbers are server-owned and assigned from the component''s sequence. Blank/content creation requires project admin; duplication requires author. Returns 422 when a STIG component''s source SRG has no CCI-000366 baseline row, or when provided content fails the kind''s validations.' requestBody: required: true content: application/json: schema: type: object properties: rule: description: Creation mode plus the one-call content surface (the same fields the update endpoint accepts; nested attributes carry no id at creation). allOf: - type: object properties: duplicate: type: boolean description: Duplicate an existing requirement instead of creating a blank one. example: false id: type: integer description: Source requirement id to duplicate (required when duplicate is true; must belong to this component). example: 100 - $ref: '#/components/schemas/RuleInput' examples: create: summary: Create a blank requirement value: rule: duplicate: false one_call_content: summary: Create a STIG rule with content in one call value: rule: duplicate: false title: The container platform must enforce approved authorizations. status: Applicable - Configurable vendor_comments: Met by the recommended runtime configuration. authored_srg: summary: Create an authored SRG requirement with content value: rule: duplicate: false title: The application must enforce approved authorizations for logical access. status: Applicable fixtext: Configure the application to enforce approved authorizations. duplicate: summary: Duplicate an existing requirement value: rule: duplicate: true id: 100 responses: '200': description: Rule created content: application/json: schema: $ref: '#/components/schemas/RuleCreateResponse' examples: created: summary: Control created value: toast: title: Control created. message: - Successfully created control. variant: success data: id: 5000 rule_id: '000204' title: New container security requirement status: Not Yet Determined locked: false satisfies: [] satisfied_by: [] links: GetCreatedRule: operationId: getRule parameters: ruleId: $response.body#/data/id description: Fetch the newly created rule. UpdateCreatedRule: operationId: updateRule parameters: ruleId: $response.body#/data/id description: Update the newly created rule. DeleteCreatedRule: operationId: deleteRule parameters: ruleId: $response.body#/data/id description: Delete the newly created rule. 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/rules_picker: parameters: - $ref: '#/components/parameters/ComponentId' get: operationId: getRulesPicker tags: - Rules summary: Lightweight rule list for picker UI description: 'Returns a compact list of requirements for dropdown/picker selection (e.g., the move-to-rule admin action or duplicate-of picker). Lighter than the full rules list — omits content fields. Rows are shaped by the component''s document_type: STIG rule objects carry the satisfaction relationships, authored SRG requirement objects omit them entirely. Requires project membership.' responses: '200': description: Requirements for picker selection content: application/json: schema: type: object required: - rules properties: rules: type: array description: All requirements in picker shape, one variant per document kind — the shapes are disjoint and never collapse into one list. items: oneOf: - $ref: '#/components/schemas/RulePickerResponse' - $ref: '#/components/schemas/AuthoredSrgRulePickerResponse' examples: stig_picker: summary: STIG rules for dropdown value: rules: - id: 100 rule_id: '000050' displayed_name: CNTR-00-000050 title: Container images must be signed locked: false satisfies: [] satisfied_by: [] - id: 101 rule_id: '000051' displayed_name: CNTR-00-000051 title: Container images must come from approved registries locked: true satisfies: [] satisfied_by: [] srg_picker: summary: Authored SRG requirements for dropdown value: rules: - id: 10633 rule_id: '000001' displayed_name: RCPK-00-000001 title: The container platform must enforce approved authorizations status: Applicable locked: false 4XX: $ref: '#/components/responses/ErrorResponse' /components/detect_srg: post: operationId: detectSrg tags: - Components summary: Detect which SRG a spreadsheet belongs to description: Analyzes an uploaded spreadsheet (CSV/XLSX) to determine which SRG its rule IDs match. Used by the component creation flow to auto-select the correct SRG when importing from a spreadsheet. Returns the matched SRG's id, srg_id, title, and version. Returns 422 if no file provided, no SRG IDs found, no matching SRG exists, or IDs map to multiple SRGs. requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: CSV or XLSX spreadsheet containing rule IDs. responses: '200': description: Matched SRG content: application/json: schema: type: object required: - id - srg_id - title - version additionalProperties: false properties: id: type: integer description: Database ID of the matched SRG. example: 1 srg_id: type: string description: DISA SRG identifier string. example: Container_Platform_SRG title: type: string description: Full title of the matched SRG. example: Container Platform Security Requirements Guide version: type: string description: Version string (e.g. V2R4). example: V2R4 examples: detected: summary: SRG detected from spreadsheet value: id: 1 srg_id: Container_Platform_SRG title: Container Platform Security Requirements Guide version: V2R4 '422': description: No file, no SRG IDs found, no match, or ambiguous match content: application/json: schema: type: object properties: error: type: string example: No SRG IDs found in spreadsheet 4XX: $ref: '#/components/responses/ErrorResponse' /components/history: get: operationId: getComponentHistory tags: - Components summary: Revision history for a named component across versions description: Traces the version history of a component by name within a project. Returns an ordered array alternating between milestone entries (marking a version point) and diff entries (showing rule-level changes between consecutive releases). Used by the DiffViewer feature. Requires project membership. Component objects use ComponentBlueprint default view (9 fields). parameters: - name: project_id in: query required: true description: ID of the project containing the component versions. schema: type: integer example: 1 - name: name in: query required: true description: Component name to trace across versions. schema: type: string example: Photon OS 3 responses: '200': description: 'Ordered revision history. The array alternates between two entry types: 1. Milestone entries: { component: ComponentSummary } — marks a version point 2. Diff entries: { base_component: ComponentSummary, diff_component: ComponentSummary, changes: { rule_id: HistoryChangeEntry } }' content: application/json: schema: type: array description: Mixed array of milestone and diff entries. Milestones have a 'component' key. Diff entries have 'base_component', 'diff_component', and 'changes' keys. items: type: object properties: component: description: Milestone entry — marks this version in the timeline. $ref: '#/components/schemas/ComponentSummary' base_component: description: Previous version in a diff pair. $ref: '#/components/schemas/ComponentSummary' diff_component: description: Current version in a diff pair. $ref: '#/components/schemas/ComponentSummary' changes: type: object description: Rule-level changes keyed by rule_id. Each value describes what changed between the base and diff versions. additionalProperties: $ref: '#/components/schemas/HistoryChangeEntry' examples: two_versions: summary: Two versions of Photon OS 3 with milestone + diff value: - component: id: 1 name: Photon OS 3 prefix: PHOS-03 version: 1 release: 1 - base_component: id: 1 name: Photon OS 3 prefix: PHOS-03 version: 1 release: 1 diff_component: id: 2 name: Photon OS 3 prefix: PHOS-03 version: 1 release: 2 changes: '000050': change: updated base: rule_id: '000050' title: Original title fix: Original fix text diff: rule_id: '000050' title: Updated title fix: Updated fix text - component: id: 2 name: Photon OS 3 prefix: PHOS-03 version: 1 release: 2 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/related: parameters: - $ref: '#/components/parameters/ComponentId' get: operationId: searchRelatedComponents tags: - Components summary: Find components sharing the same SRG baseline description: Returns other components that are based on the same SRG as this component. Used by the DiffViewer to find peer components for side-by-side comparison. Scoped to components the current user can access plus released components. Returns a hand-built hash (NOT ComponentBlueprint). responses: '200': description: Related components sharing the same SRG content: application/json: schema: type: array items: type: object properties: id: type: integer example: 4 name: type: string example: Photon OS 3 version: type: - integer - 'null' example: 1 prefix: type: string example: PHOS-03 release: type: - integer - 'null' example: 1 project_id: type: integer example: 3 project_name: type: string example: vSphere 7.0 examples: related: summary: Two peer components from different projects value: - id: 4 name: Photon OS 3 version: 1 prefix: PHOS-03 release: 1 project_id: 3 project_name: vSphere 7.0 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/find: parameters: - $ref: '#/components/parameters/ComponentId' post: operationId: findRulesInComponent tags: - Components summary: Search requirements within a component by text description: Full-text search across requirement titles, fix text, vendor comments, status justification, artifact description, vulnerability discussion, mitigations, and check content within a single component. The same field list applies to both document kinds; results are shaped by the component's document_type. Returns matching requirements in rule_id order. Used by the in-component search feature. requestBody: required: true content: application/json: schema: type: object required: - find properties: find: type: string description: Case-insensitive search term matched against all rule text fields. example: container image examples: search: summary: Search for container image references value: find: container image responses: '200': description: 'Matching requirements in rule_id order, shaped by the component''s document_type: STIG rule objects for stig components, authored SRG requirement objects for srg components.' content: application/json: schema: type: array items: oneOf: - $ref: '#/components/schemas/RuleEditorResponse' - $ref: '#/components/schemas/AuthoredSrgRuleEditorResponse' examples: results: summary: Two matching rules value: - id: 100 rule_id: CNTR-00-000050 title: Container images must be signed status: Applicable - Configurable locked: false satisfies: [] satisfied_by: [] - id: 101 rule_id: CNTR-00-000051 title: Container images must come from approved registries status: Applicable - Configurable locked: false satisfies: [] satisfied_by: [] 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/preview_spreadsheet_update: parameters: - $ref: '#/components/parameters/ComponentId' post: operationId: previewSpreadsheetUpdate tags: - Components summary: Preview changes from a spreadsheet import description: 'Parses an uploaded spreadsheet (CSV/XLSX) and returns a diff of what would change if applied, without modifying any data. Returns four arrays: updated (rules with changes), unchanged (no diff), skipped_locked (locked rules or inherited rules), and warnings (SRG IDs not found). Requires author role on the component.' requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: CSV or XLSX spreadsheet file containing rule updates. responses: '200': description: Preview of changes grouped by outcome content: application/json: schema: type: object required: - updated - unchanged - skipped_locked - warnings properties: updated: type: array description: Rules with detected changes. items: type: object properties: rule_id: type: string example: '000050' srg_id: type: - string - 'null' example: SRG-APP-000014-CTR-000035 changes: type: object description: Changed fields with [old_value, new_value] pairs. additionalProperties: type: array items: {} unchanged: type: array description: Rules with no differences from spreadsheet. items: type: object properties: rule_id: type: string srg_id: type: - string - 'null' reason: type: string example: no changes skipped_locked: type: array description: Rules skipped because they are locked or inherited. items: type: object properties: rule_id: type: string srg_id: type: - string - 'null' reason: type: string enum: - locked - inherited - section locked example: locked skipped_fields: type: array description: Fields that were locked (present only for section-locked skips). items: type: string warnings: type: array description: SRG IDs from the spreadsheet that were not found in the component. items: type: string example: - SRG ID SRG-APP-999999 not found in component examples: preview: summary: Mixed preview with updates, unchanged, and skipped rules value: updated: - rule_id: '000050' srg_id: SRG-APP-000014-CTR-000035 changes: fixtext: - Old fix text - Updated fix text unchanged: - rule_id: '000051' srg_id: SRG-APP-000023-CTR-000040 reason: no changes skipped_locked: - rule_id: '000001' srg_id: SRG-APP-000001-CTR-000001 reason: locked warnings: [] '422': description: No file provided or parse error content: application/json: schema: type: object properties: error: type: string description: Error message. examples: no_file: summary: No file uploaded value: error: No file was provided. Please upload a CSV or XLSX file. 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/apply_spreadsheet_update: parameters: - $ref: '#/components/parameters/ComponentId' patch: operationId: applySpreadsheetUpdate tags: - Components summary: Apply changes from a spreadsheet import description: Applies rule updates from an uploaded spreadsheet (CSV/XLSX) to the component. Requires admin role on the component. Use the preview endpoint first to review changes before applying. Creates audit trail entries for each modified rule. requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: CSV or XLSX spreadsheet file containing rule updates. responses: '200': description: Spreadsheet changes applied successfully content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: success: summary: Rules updated from spreadsheet value: toast: title: Spreadsheet applied. message: - Successfully updated 12 rules from spreadsheet. variant: success '422': description: No file provided or application error content: application/json: schema: type: object properties: error: type: string examples: no_file: summary: No file uploaded value: error: No file was provided. Please upload a CSV or XLSX file. 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/release: parameters: - $ref: '#/components/parameters/ComponentId' post: operationId: releaseComponent tags: - Components summary: Release an SRG component to the catalog description: 'Releases an SRG-kind component in one transaction: verifies every live requirement is decided (never Not Yet Determined) and locked, mints the final published identifiers, generates the published SRG XCCDF, creates the catalog SecurityRequirementsGuide entry with its columns derived from that document, copies the published requirements onto the entry, and flags the component released. The released entry behaves exactly like an uploaded SRG — new components can base on it immediately. Requires the author role on the component. STIG readiness components do not use this endpoint (their release is the released flag on component update).' responses: '200': description: Component released and attached to the catalog content: application/json: schema: $ref: '#/components/schemas/ComponentReleaseResponse' examples: released: summary: First release of a derived SRG value: toast: title: Component released. message: - Container Best Practice SRG - Ver 1, Rel 1 is now in the SRG catalog. variant: success catalog_srg: id: 42 srg_id: Container_Best_Practice_SRG version: V1R1 name: Container Best Practice SRG - Ver 1, Rel 1 changelog: version: V1R1 removals: [] text: |- Container Best Practice SRG V1R1 — Release Changelog No requirements were removed in this release. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': description: Release blocked — the component is not an SRG component, is already released, is missing its version/release pair or abbreviation, still has Not Yet Determined requirements, or has unlocked requirements. The toast messages carry every blocking reason. content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: undecided: summary: Undecided requirements block the release value: toast: title: Could not release component. message: - 'release is blocked: 3 live requirement(s) still Not Yet Determined — every requirement must be decided' variant: danger /components/bulk_export/{type}: parameters: - name: type in: path required: true description: Export format for the bulk download. schema: type: string enum: - csv - xccdf - inspec example: csv get: operationId: bulkExportComponents tags: - Components summary: Bulk export multiple released components description: Exports multiple released components as a single download in the specified format. Component IDs are passed as a comma-separated query parameter. Returns a binary file (zip for multiple components). Returns a JSON error toast if the export type is unsupported or no component IDs are provided. parameters: - name: component_ids in: query required: true description: Comma-separated list of released component IDs to export. schema: type: string example: 29,30,31 responses: '200': description: Binary file download content: application/zip: schema: type: string format: binary application/xml: schema: type: string format: binary '400': description: Invalid export type or no components selected content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: bad_type: summary: Unsupported export type value: toast: title: Export error. message: - 'Unsupported export type: pdf' variant: danger no_components: summary: No components selected value: toast: title: Export error. message: - No components selected for export. variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /api/components/compare: get: operationId: compareComponents tags: - Components summary: Side-by-side rule comparison between two peer components description: Compares rules between a base (older) and diff (newer) component sharing the same SRG. Returns a rule-by-rule diff keyed by field name, with metadata about both components. Used by the DiffViewer stepper in the component editor. Requires authentication and access to both components. parameters: - name: base_id in: query required: true description: ID of the base (older) component to compare from. schema: type: integer example: 29 - name: diff_id in: query required: true description: ID of the diff (newer) component to compare against. schema: type: integer example: 30 responses: '200': description: Rule-by-rule diff with metadata envelope content: application/json: schema: type: object required: - data - meta properties: data: type: object description: Diff keyed by rule_id. Each entry compares the inspec_control_file content between the base and diff components for that rule. additionalProperties: type: object properties: base: type: - string - 'null' description: InSpec control file content from the base component. Null if rule not present. diff: type: - string - 'null' description: InSpec control file content from the diff component. Null if rule not present. changed: type: boolean description: Whether the InSpec content differs between versions. meta: type: object description: Metadata about the compared components. properties: base_id: type: integer example: 29 diff_id: type: integer example: 30 rules_count: type: integer example: 264 examples: diff: summary: Two rules compared by generated InSpec control value: data: '000050': base: |- control 'CNTR-00-000050' do title 'Container images must be signed' end diff: |- control 'CNTR-00-000050' do title 'Container images must be signed and verified' end changed: true '000051': base: |- control 'CNTR-00-000051' do title 'Approved registries only' end diff: |- control 'CNTR-00-000051' do title 'Approved registries only' end changed: false meta: base_id: 29 diff_id: 30 rules_count: 264 4XX: $ref: '#/components/responses/ErrorResponse' /rules/{ruleId}: parameters: - $ref: '#/components/parameters/RuleId' get: operationId: getRule tags: - Rules summary: Rule detail description: Returns the full requirement editor payload for either document kind — checks, descriptions, and review history for both; satisfactions (satisfies/satisfied_by) appear on stig rules only, and authored SRG requirements omit those keys entirely. responses: '200': description: Rule data content: application/json: schema: description: 'Shaped by the parent component''s document_type: a STIG rule or an authored SRG requirement.' oneOf: - $ref: '#/components/schemas/RuleEditorResponse' - $ref: '#/components/schemas/AuthoredSrgRuleEditorResponse' links: UpdateThisRule: operationId: updateRule parameters: ruleId: $response.body#/id DeleteThisRule: operationId: deleteRule parameters: ruleId: $response.body#/id RevertThisRule: operationId: revertRule parameters: ruleId: $response.body#/id CreateReviewOnRule: operationId: createRuleReview parameters: ruleId: $response.body#/id 4XX: $ref: '#/components/responses/ErrorResponse' patch: operationId: patchRule tags: - Rules summary: Partial update of rule attributes description: Partial update — send only changed fields. Updates one or more rule fields. Requires author or admin role on the component. requestBody: required: true content: application/json: schema: type: object properties: rule: $ref: '#/components/schemas/RuleInput' examples: stig_update: summary: STIG rule status change value: rule: status: Applicable - Configurable vendor_comments: Met by the recommended runtime configuration. authored_srg_update: summary: Authored SRG requirement decided Not Applicable value: rule: status: Not Applicable status_justification: The platform provides no wireless interfaces to configure. nested_content: summary: Update check content and record an audit comment value: rule: audit_comment: Check procedure clarified per review feedback. checks_attributes: - id: 311 content: Review the container platform configuration to verify approved authorizations are enforced. responses: '200': description: Rule updated content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' put: operationId: updateRule tags: - Rules summary: Full replacement of rule attributes description: Full replacement — all fields required. Updates rule fields. Requires author or admin role on the component. requestBody: required: true content: application/json: schema: type: object properties: rule: $ref: '#/components/schemas/RuleInput' examples: stig_update: summary: STIG rule full update value: rule: status: Applicable - Configurable title: The container platform must enforce approved authorizations. fixtext: Configure the container platform to enforce approved authorizations. vendor_comments: Met by the recommended runtime configuration. authored_srg_update: summary: Authored SRG requirement update value: rule: status: Applicable title: The application must enforce approved authorizations for logical access. fixtext: Configure the application to enforce approved authorizations. responses: '200': description: Rule updated content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteRule tags: - Rules summary: Soft-delete a rule description: Marks the rule as deleted. Requires admin role on the component. responses: '200': description: Rule deleted content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' /rules/{ruleId}/revert: parameters: - $ref: '#/components/parameters/RuleId' post: operationId: revertRule tags: - Rules summary: Revert requirement fields to a previous audit version description: Restores the named audited fields to their prior values from the specified history entry. Applies to both document kinds — stig rules and authored SRG requirements. Requires author or admin role. requestBody: required: true content: application/json: schema: type: object properties: audit_id: type: integer description: The audit history entry to revert from. example: 4211 fields: type: array description: The audited field names to restore. items: type: string example: - title audit_comment: type: string description: Recorded on the audit trail with the revert. example: Restore the original wording responses: '200': description: Rule reverted content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' /rules/{ruleId}/section_locks: parameters: - $ref: '#/components/parameters/RuleId' patch: operationId: updateSectionLocks tags: - Rules summary: Lock or unlock a single section on a rule description: Locks or unlocks a single section (e.g., Fix, Check) on a rule. Requires reviewer role or higher on the parent component. Creates an audit entry. requestBody: required: true content: application/json: schema: type: object required: - section - locked properties: section: type: string description: Section name to lock or unlock, from the lockable-section vocabulary. enum: - Title - Severity - Status - Fix - Check - Vulnerability Discussion - DISA Metadata - Vendor Comments - Artifact Description - XCCDF Metadata example: Fix locked: type: boolean description: Whether to lock (true) or unlock (false). example: true comment: type: string description: Optional audit comment. example: Locking the Fix section for final review responses: '200': description: Section locks updated content: application/json: schema: $ref: '#/components/schemas/RuleSectionLockResponse' 4XX: $ref: '#/components/responses/ErrorResponse' /rules/{ruleId}/bulk_section_locks: parameters: - $ref: '#/components/parameters/RuleId' patch: operationId: bulkSectionLocks tags: - Rules summary: Bulk update locked sections description: Locks or unlocks multiple sections at once on a rule. Requires reviewer role or higher on the parent component. Creates an audit trail entry. requestBody: required: true content: application/json: schema: type: object required: - sections - locked properties: sections: type: array description: Section names to lock or unlock, from the lockable-section vocabulary. items: type: string enum: - Title - Severity - Status - Fix - Check - Vulnerability Discussion - DISA Metadata - Vendor Comments - Artifact Description - XCCDF Metadata example: - Fix - Check locked: type: boolean description: Whether to lock (true) or unlock (false) the sections. example: true comment: type: string description: Optional audit comment explaining the lock change. example: Locking the Fix and Check sections for review responses: '200': description: Section locks updated, returns updated rule + toast content: application/json: schema: $ref: '#/components/schemas/RuleSectionLockResponse' '422': description: Invalid section names content: application/json: schema: type: object required: - error properties: error: type: string description: Names every unrecognized section. example: 'Invalid sections: NotASection' 4XX: $ref: '#/components/responses/ErrorResponse' /rules/{ruleId}/search/related_rules: parameters: - $ref: '#/components/parameters/RuleId' get: operationId: getRelatedRules tags: - Rules summary: Find rules sharing the same SRG requirement description: Returns rules from other components and published STIGs that implement the same SRG requirement (matched by version/srg_id). Results are scoped to components the current user can access unless the user is an admin. The rules array is a mix of RuleEditorResponse (component rules) and StigRuleSummary (published STIG rules). The parents array is a mix of ComponentBlueprint :related and StigBlueprint :index for grouping. Stig rules only — the search keys off the stig rule's SRG-version linkage, so requests for an authored SRG requirement return 404 (no related-rules surface exists for that kind). responses: '200': description: Related rules with parent containers content: application/json: schema: type: object required: - rules - parents properties: rules: type: array description: Mixed array of component rules (RuleEditorResponse, 38 fields) and published STIG rules (StigRuleSummary, 16 fields). items: {} parents: type: array description: 'Mixed array of parent containers: ComponentBlueprint :related (with nested project) and StigBlueprint :index (with severity_counts).' items: {} examples: related: summary: Rules from another component and a published STIG value: rules: - id: 200 rule_id: SV-222387r960735_rule title: The application must limit logon sessions version: APSC-DV-000010 rule_severity: medium - id: 1800 rule_id: '000001' title: The operating system must provide automated mechanisms status: Not Yet Determined component_id: 1 parents: - id: 1 stig_id: Application_Security_Development_STIG name: Application Security Development STIG - Ver 6, Rel 4 title: Application Security and Development STIG - id: 1 name: Photon OS 3 prefix: PHOS-03 project: id: 1 name: Photon 3 '404': $ref: '#/components/responses/NotFound' 4XX: $ref: '#/components/responses/ErrorResponse' /rule_satisfactions: post: operationId: addSatisfaction tags: - Rules summary: Create a satisfaction relationship between two rules description: Links a child rule to a parent rule that satisfies it. Triggers ADNM status automation on the child. requestBody: required: true content: application/json: schema: type: object required: - rule_id - satisfied_by_rule_id properties: rule_id: type: integer description: The rule that is satisfied. Absence is a 400. example: 101 satisfied_by_rule_id: type: integer description: The rule that satisfies it. Absence is a 400. example: 102 responses: '200': description: Satisfaction created content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' /rule_satisfactions/{ruleId}: parameters: - $ref: '#/components/parameters/RuleId' delete: operationId: removeSatisfaction tags: - Rules summary: Remove a satisfaction relationship description: Removes the parent-child satisfaction link and reverts ADNM status on the child rule. requestBody: content: application/json: schema: type: object properties: rule_id: type: integer satisfied_by_rule_id: type: integer responses: '200': description: Satisfaction removed content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' /rules/{ruleId}/relocations: parameters: - $ref: '#/components/parameters/RuleId' post: operationId: createRequirementRelocation tags: - Rules summary: Propose relocating an authored SRG requirement description: Creates an OPEN relocation proposal for an authored requirement of an SRG component, naming the destination SRG's abbreviation. Requires author role on the component. One open proposal per requirement; a second returns 422. The proposal is a record, never a status change on the requirement — the destination SRG's authors concur or non-concur. requestBody: required: true content: application/json: schema: type: object required: - requirement_relocation properties: requirement_relocation: type: object required: - target_technology_token properties: target_technology_token: type: string description: The destination SRG's abbreviation — the short code its requirement IDs start with (CTR, GPOS, DB). example: CTR examples: mark: summary: Propose relocation to the Container SRG value: requirement_relocation: target_technology_token: CTR responses: '200': description: Relocation proposed content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: proposed: summary: Proposal created value: toast: title: Relocation proposed. message: - Proposed for the CTR SRG. variant: success '404': $ref: '#/components/responses/NotFound' '422': description: Duplicate open proposal or ineligible source content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: duplicate: summary: Already proposed value: toast: title: Could not propose the relocation. message: - Source rule already has a pending relocation variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /requirement_relocations: get: operationId: listRequirementRelocations tags: - Rules summary: List the open relocation-proposal backlog description: Returns relocation proposals, optionally filtered to one destination SRG's abbreviation — the standing per-SRG backlog and the creation/open-time prompt count both read this. Rows are scoped to projects the caller can see. Executed records are immutable history and never listed. parameters: - name: target_technology_token in: query required: false description: The destination SRG's abbreviation to filter by. schema: type: string example: CTR responses: '200': description: Open proposals (and retained declines), oldest first content: application/json: schema: type: array items: $ref: '#/components/schemas/RequirementRelocationSummary' examples: backlog: summary: One open proposal for the CTR SRG value: - id: 12 source_rule_id: 5137 target_technology_token: CTR created_at: 2026-07-20 15:36:06 UTC source_displayed_name: CNTR-00-000051 component_id: 42 component_name: Container Platform SRG requested_by_name: Jane Doe 4XX: $ref: '#/components/responses/ErrorResponse' /requirement_relocations/destinations: get: operationId: listRelocationDestinations tags: - Rules summary: List destination SRG options for the propose flow description: 'Serves the Destination SRG picker: one row per SRG abbreviation across the SRG components in projects the caller can see (member or discoverable). An open component wins its abbreviation''s row; released true marks the queued next-release case. Hidden projects'' SRGs never appear — proposing to them remains possible through the free abbreviation entry, which discloses nothing.' responses: '200': description: Destination options, ordered by abbreviation content: application/json: schema: type: array items: $ref: '#/components/schemas/RelocationDestination' examples: destinations: summary: One open component and one queued SRG value: - token: CTR name: Container Platform SRG released: false - token: GPOS name: General Purpose Operating System SRG released: true 4XX: $ref: '#/components/responses/ErrorResponse' /requirement_relocations/{id}: parameters: - name: id in: path required: true description: Numeric ID of the pending relocation record. schema: type: integer example: 12 delete: operationId: deleteRequirementRelocation tags: - Rules summary: Un-mark a requirement for relocation description: Destroys a PENDING relocation record, removing the move marker. Audited. Requires author role on the source component. Executed records are immutable — they answer 404 exactly like a record that never existed. responses: '200': description: Marker removed content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: unmarked: summary: Marker removed value: toast: title: Relocation marker removed. message: - The requirement is no longer marked for relocation. variant: success '404': $ref: '#/components/responses/NotFound' 4XX: $ref: '#/components/responses/ErrorResponse' /requirement_relocations/{id}/dry_run: parameters: - name: id in: path required: true description: Numeric ID of the open relocation proposal. schema: type: integer example: 12 post: operationId: dryRunRequirementRelocation tags: - Rules summary: Preview accepting a relocation with zero writes description: Returns exactly what accepting the proposal would do for this destination component — or every reason it cannot run — without writing anything. This preview is the adjudication review artifact. Requires author role on the DESTINATION component only. Adjudicated proposals (declined or executed) answer 404 like a record that never existed. requestBody: required: true content: application/json: schema: type: object required: - target_component_id properties: target_component_id: type: integer description: The destination SRG component. example: 42 examples: preview: summary: Preview a move into component 42 value: target_component_id: 42 responses: '200': description: The preview, valid or not content: application/json: schema: $ref: '#/components/schemas/RequirementRelocationDryRun' examples: valid: summary: Move can run value: valid: true errors: [] source_displayed_name: CNTR-00-000051 target_component_id: 42 target_component_name: Container Platform SRG would_create: title: The application must enforce approved authorizations status: Applicable derived_from_srg_rule_id: 5137 would_tombstone_source: true '404': $ref: '#/components/responses/NotFound' 4XX: $ref: '#/components/responses/ErrorResponse' /requirement_relocations/{id}/accept: parameters: - name: id in: path required: true description: Numeric ID of the open relocation proposal. schema: type: integer example: 12 post: operationId: acceptRequirementRelocation tags: - Rules summary: Concur with a relocation proposal — land the requirement description: 'Receiver-side adjudication (displayed as Concur): acceptance and landing are ONE transaction — creates the requirement in the destination component with content and core lineage carried over, tombstones the source row, and stamps the record executed with the accepting actor — atomically, or not at all. Requires author role on the DESTINATION component only; the proposal itself carries source consent. Audited. Adjudicated proposals (declined or executed) answer 404 like a record that never existed.' requestBody: required: true content: application/json: schema: type: object required: - target_component_id properties: target_component_id: type: integer description: The destination SRG component. example: 42 examples: accept: summary: Concur — land the move into component 42 value: target_component_id: 42 responses: '200': description: Proposal concurred with and requirement landed content: application/json: schema: $ref: '#/components/schemas/RequirementRelocationAcceptResponse' examples: accepted: summary: Move landed value: toast: title: Concurred. message: - Moved to Container Platform SRG — the source requirement is now history. variant: success landed_rule_id: 5137 '404': $ref: '#/components/responses/NotFound' '422': description: The move cannot run (validation errors from the preview) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: invalid: summary: Ineligible destination value: toast: title: Could not accept the proposal. message: - target component must be an SRG component variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /requirement_relocations/{id}/decline: parameters: - name: id in: path required: true description: Numeric ID of the open relocation proposal. schema: type: integer example: 12 post: operationId: declineRequirementRelocation tags: - Rules summary: Non-concur with a relocation proposal, with a rationale description: 'Receiver-side adjudication (displayed as Non-concur): declines the proposal with a REQUIRED rationale. The record is retained as terminal history — never destroyed — and the rationale surfaces to the source author in the backlog, so the refusal communicates back across the ownership boundary. Requires author role on the destination component named in the request, and that component must be an ELIGIBLE receiver — an unreleased SRG component, other than the source, that declares the source requirement''s core SRG (the same eligibility accept enforces). Audited. A declined source may be proposed again.' requestBody: required: true content: application/json: schema: type: object required: - target_component_id - requirement_relocation properties: target_component_id: type: integer description: The destination component the decliner adjudicates for — establishes receiver-side authority. example: 42 requirement_relocation: type: object required: - adjudication_rationale properties: adjudication_rationale: type: string description: Why the proposal is declined — shown to the source author. example: Covered by CNTR-00-000001 already. examples: decline: summary: Decline with the reason value: target_component_id: 42 requirement_relocation: adjudication_rationale: Covered by CNTR-00-000001 already. responses: '200': description: Proposal non-concurred with and retained with the rationale content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: declined: summary: Non-concur recorded value: toast: title: Non-concurred. message: - The source author can see your rationale in the backlog. variant: success '404': $ref: '#/components/responses/NotFound' '422': description: The rationale is missing, or the named component is not an eligible receiver content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: missing_rationale: summary: Rationale required value: toast: title: Could not decline the proposal. message: - Adjudication rationale can't be blank variant: danger ineligible_receiver: summary: Anchored to an ineligible component value: toast: title: Could not decline the proposal. message: - target component must be an SRG component variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /rules/{ruleId}/reviews: parameters: - $ref: '#/components/parameters/RuleId' post: operationId: createRuleReview tags: - Reviews summary: Create a review on a rule (comment, request_review, etc.) description: Posts a new comment or review action on the specified rule. Requires viewer role or above on the component. requestBody: required: true content: application/json: schema: type: object properties: review: $ref: '#/components/schemas/ReviewInput' responses: '200': description: Review created content: application/json: schema: $ref: '#/components/schemas/ToastResponse' '422': $ref: '#/components/responses/UnprocessableEntity' 4XX: $ref: '#/components/responses/ErrorResponse' /components/{componentId}/reviews: parameters: - $ref: '#/components/parameters/ComponentId' post: operationId: createComponentReview tags: - Reviews summary: Post a public comment on a component description: Creates a new comment-action review on the component (component-level comment) or on a specific rule within it. The component must have an open comment period (accepting_new_comments? check). Requires project membership with at least viewer role. requestBody: required: true content: application/json: schema: type: object properties: review: $ref: '#/components/schemas/ReviewInput' examples: component_comment: summary: Post a component-level comment value: review: action: comment comment: The overall approach to container isolation is sound. section: null threaded_reply: summary: Reply to an existing component-level comment value: review: action: comment comment: Agreed — the isolation model covers this case. section: null responding_to_review_id: 44 responses: '200': description: Comment created content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: created: summary: Comment posted value: toast: title: Comment posted. message: - Your comment has been submitted for review. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/bulk_triage: patch: operationId: bulkTriageReviews tags: - Reviews summary: Triage multiple reviews at once description: 'Applies the same triage status to all specified reviews in a single request. Parameters are FLAT (no wrapper object). All reviews must belong to the same component (enforced server-side). Terminal statuses (duplicate, informational, withdrawn, addressed_by) auto-adjudicate every selected review. Conditional requirements: non_concur requires response_comment; duplicate requires duplicate_of_review_id; addressed_by requires addressed_by_rule_id. The target is ONE shared value applied to every selected review — many comments duplicating one canonical thread, or addressed by one rule. A duplicate canonical that is itself among review_ids is rejected. Every per-comment validator runs per selected review (same-component canonical, no chained duplicates); any failing review rolls back the whole batch. Optionally creates a response comment on each triaged review. Requires author+ role on the component''s project.' requestBody: required: true content: application/json: schema: type: object required: - review_ids - triage_status properties: review_ids: type: array items: type: integer description: IDs of the reviews to triage. example: - 10 - 11 - 12 triage_status: type: string description: The triage decision applied to all selected reviews. Every value except "pending" is accepted; "pending" is rejected as a non-decision. enum: - concur - concur_with_comment - non_concur - needs_clarification - duplicate - informational - withdrawn - addressed_by example: concur duplicate_of_review_id: type: integer description: REQUIRED when triage_status is "duplicate" — the one canonical review every selected review duplicates. Must be a comment in the same component, must not itself be a duplicate, and must not appear in review_ids. example: 42 addressed_by_rule_id: type: integer description: REQUIRED when triage_status is "addressed_by" — the one rule that addresses every selected review. example: 7 response_comment: type: string description: REQUIRED when triage_status is "non_concur"; optional otherwise. Posted as a reply to each triaged review. example: Accepted — will update check_content in next release. examples: concur: summary: Accept several comments at once (flat body) value: review_ids: - 10 - 11 - 12 triage_status: concur duplicate: summary: Mark a group as duplicates of one canonical thread value: review_ids: - 10 - 11 - 12 triage_status: duplicate duplicate_of_review_id: 42 addressed_by: summary: Mark a group as addressed by one rule value: review_ids: - 10 - 11 - 12 triage_status: addressed_by addressed_by_rule_id: 7 responses: '200': description: All reviews triaged successfully content: application/json: schema: $ref: '#/components/schemas/BulkTriageResponse' examples: triaged: summary: Three reviews accepted value: reviews: - id: 10 action: comment comment: Original comment 1 triage_status: concur rule_id: 100 created_at: 2026-05-19 14:08:17 UTC reactions: up: 0 down: 0 mine: null response_reviews: [] '422': description: Validation error — invalid or "pending" triage status, reviews spanning components, a missing conditional target, a duplicate canonical among review_ids, a cross-component or chained-duplicate canonical, or any selected review failing its per-comment validators (the batch rolls back atomically). content: application/json: schema: $ref: '#/components/schemas/ToastResponse' /reviews/merge: patch: operationId: mergeReviews tags: - Reviews summary: Merge duplicate reviews into one survivor description: Combines multiple same-author reviews within one component into a designated survivor. Non-survivor reviews are marked as duplicates (triage_status=duplicate, duplicate_of_review_id=survivor). Requires admin role on the component's project. requestBody: required: true content: application/json: schema: type: object required: - review_ids - survivor_id properties: review_ids: type: array items: type: integer description: IDs of all reviews to merge (including the survivor). example: - 10 - 11 - 12 survivor_id: type: integer description: ID of the review that absorbs the others. example: 10 responses: '200': description: Reviews merged successfully content: application/json: schema: $ref: '#/components/schemas/MergeResponse' examples: merged: summary: Two duplicates merged into survivor value: survivor: id: 10 action: comment comment: The original comment triage_status: pending rule_id: 100 created_at: 2026-05-19 14:08:17 UTC reactions: up: 0 down: 0 mine: null duplicates: - id: 11 action: comment comment: Duplicate of 10 triage_status: duplicate duplicate_of_review_id: 10 rule_id: 100 created_at: 2026-05-19 14:10:00 UTC reactions: up: 0 down: 0 mine: null '422': description: Validation error (reviews from different components, different authors, etc.) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' /reviews/{reviewId}: parameters: - $ref: '#/components/parameters/ReviewId' put: operationId: updateReview tags: - Reviews summary: Update a review comment description: Edits the comment text of an existing review. Only the original author or an admin can update. requestBody: required: true content: application/json: schema: type: object required: - review properties: review: $ref: '#/components/schemas/ReviewUpdateInput' responses: '200': description: Review updated content: application/json: schema: $ref: '#/components/schemas/ReviewWrapper' links: GetReviewResponses: operationId: getReviewResponses parameters: reviewId: $response.body#/review/id TriageReview: operationId: triageReview parameters: reviewId: $response.body#/review/id WithdrawReview: operationId: withdrawReview parameters: reviewId: $response.body#/review/id 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/triage: parameters: - $ref: '#/components/parameters/ReviewId' patch: operationId: triageReview tags: - Reviews summary: Set triage status on a comment (concur, non_concur, etc.) description: 'Assigns a triage decision to the comment. Parameters are FLAT (no wrapper object). Terminal statuses (duplicate, informational, withdrawn, addressed_by) auto-adjudicate. Submitting "pending" is rejected — it is the initial state, not a decision. Conditional requirements: non_concur requires response_comment; duplicate requires duplicate_of_review_id; addressed_by requires addressed_by_rule_id. Requires author or admin role.' requestBody: required: true content: application/json: schema: type: object required: - triage_status properties: triage_status: type: string description: The triage decision. Every value except "pending" is accepted; "pending" is rejected as a non-decision. enum: - concur - concur_with_comment - non_concur - needs_clarification - duplicate - informational - withdrawn - addressed_by example: concur duplicate_of_review_id: type: integer description: REQUIRED when triage_status is "duplicate" — the canonical review this comment duplicates. example: 42 addressed_by_rule_id: type: integer description: REQUIRED when triage_status is "addressed_by" — the rule that addresses this comment. example: 7 response_comment: type: string description: REQUIRED when triage_status is "non_concur"; optional otherwise. Posted as a reply to the comment. example: Declining — the requirement text already covers this. examples: concur: summary: Simple concur (flat body) value: triage_status: concur non_concur: summary: Decline with the required response value: triage_status: non_concur response_comment: Declining — covered by the fix text. responses: '200': description: Triage status set content: application/json: schema: $ref: '#/components/schemas/TriageResponse' links: AdjudicateTriagedReview: operationId: adjudicateReview parameters: reviewId: $response.body#/review/id description: Close the review after triage is complete. ReopenTriagedReview: operationId: reopenReview parameters: reviewId: $response.body#/review/id 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/adjudicate: parameters: - $ref: '#/components/parameters/ReviewId' patch: operationId: adjudicateReview tags: - Reviews summary: Adjudicate (close) a triaged comment description: Marks the comment as adjudicated, finalizing the triage decision. Requires author or admin role. requestBody: content: application/json: schema: type: object properties: resolution_comment: type: string description: Optional final-resolution text. When supplied, a child Review (action=comment, threaded via responding_to_review_id with the parent's section) is created atomically with the adjudication and returned as response_review, so the resolution renders inline in the comment thread. example: Fix text updated in R2 — closing as concur. responses: '200': description: Review adjudicated content: application/json: schema: $ref: '#/components/schemas/TriageResponse' links: ReopenAdjudicatedReview: operationId: reopenReview parameters: reviewId: $response.body#/review/id 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/withdraw: parameters: - $ref: '#/components/parameters/ReviewId' patch: operationId: withdrawReview tags: - Reviews summary: Author withdraws their own comment description: Allows the comment author to retract their comment. Sets triage_status to withdrawn and auto-adjudicates. responses: '200': description: Review withdrawn content: application/json: schema: $ref: '#/components/schemas/ReviewWrapper' links: AdminRestoreWithdrawnReview: operationId: adminRestoreReview parameters: reviewId: $response.body#/review/id 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/admin_withdraw: parameters: - $ref: '#/components/parameters/ReviewId' patch: operationId: adminWithdrawReview tags: - Reviews summary: Admin force-withdraws a comment description: Admin-only force withdrawal that bypasses the frozen-for-writes check. Requires an audit comment explaining the action. requestBody: required: true content: application/json: schema: type: object required: - audit_comment properties: audit_comment: type: string maxLength: 4096 description: Operator-supplied reason for the force-withdrawal, recorded on the audit trail. Required — a blank comment returns 422. example: Removing PII discovered after the comment window closed. responses: '200': description: Review withdrawn by admin content: application/json: schema: $ref: '#/components/schemas/ReviewWrapper' links: AdminRestoreWithdrawnReview: operationId: adminRestoreReview parameters: reviewId: $response.body#/review/id 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/admin_restore: parameters: - $ref: '#/components/parameters/ReviewId' patch: operationId: adminRestoreReview tags: - Reviews summary: Admin restores an adjudicated comment to pending description: Inverse of admin_withdraw and any other adjudication — resets the comment to pending status so it can be re-triaged through the normal flow. Rejects comments that are not adjudicated (nothing to restore from). Requires admin role on the project and an audit comment explaining the action. requestBody: required: true content: application/json: schema: type: object required: - audit_comment properties: audit_comment: type: string maxLength: 4096 description: Operator-supplied reason for the restore, recorded on the audit trail. Required — a blank comment returns 422. example: Restoring — the wrong comment was force-withdrawn. responses: '200': description: Review restored content: application/json: schema: $ref: '#/components/schemas/ReviewWrapper' links: TriageRestoredReview: operationId: triageReview parameters: reviewId: $response.body#/review/id 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/move_to_rule: parameters: - $ref: '#/components/parameters/ReviewId' patch: operationId: moveReviewToRule tags: - Reviews summary: Admin moves a comment thread to a different rule description: Reassigns the comment and all its replies to a different requirement row in the same component. The target may be either document kind — a stig rule or an authored SRG requirement (the lookup spans both). Walks parent-first to satisfy validators and records an outbound audit entry on the source rule. Requires admin role. requestBody: required: true content: application/json: schema: type: object required: - rule_id - audit_comment properties: rule_id: type: integer description: Database id of the target requirement row (either kind), which must belong to the same component as the source rule. example: 15117 audit_comment: type: string maxLength: 4096 description: Operator-supplied reason for the move, recorded on the audit trail. Required — a blank comment returns 422. example: Comment applies to the account-management requirement. examples: move: summary: Move a thread to another requirement value: rule_id: 15117 audit_comment: Comment applies to the account-management requirement. responses: '200': description: Review moved — returns the updated review. content: application/json: schema: $ref: '#/components/schemas/ReviewWrapper' '404': $ref: '#/components/responses/NotFound' '422': description: Move refused — the target is the source rule itself, the target belongs to a different component, or the audit comment is blank. content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: same_rule: summary: Target is the source rule (no move performed) value: toast: title: Cannot move. message: - Target rule is the same as the source rule. variant: warning 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/admin_destroy: parameters: - $ref: '#/components/parameters/ReviewId' delete: operationId: adminDestroyReview tags: - Reviews summary: Admin permanently deletes a comment (irreversible) description: Hard-deletes a comment and all its replies. Requires an audit comment explaining the action — the pre-destroy snapshot plus that comment become the audit record. (The web UI additionally asks the admin to type the comment ID to confirm; the API has no confirmation field.) This action cannot be undone. requestBody: required: true content: application/json: schema: type: object required: - audit_comment properties: audit_comment: type: string maxLength: 4096 description: Operator-supplied reason for the hard-delete, recorded on the audit trail. Required — a blank comment returns 422. example: Legal hard-delete — comment contained PII. responses: '200': description: Review destroyed content: application/json: schema: $ref: '#/components/schemas/AdminDestroyResponse' 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/responses: parameters: - $ref: '#/components/parameters/ReviewId' get: operationId: getReviewResponses tags: - Reviews summary: List replies to a review description: Returns threaded replies to a parent review, ordered by creation time. Each reply is serialized via ReviewBlueprint with commenter attribution, reaction counts, and the current user's reaction. responses: '200': description: Reply thread content: application/json: schema: type: object required: - rows properties: rows: type: array description: Reply rows ordered by created_at. items: $ref: '#/components/schemas/ReviewSummary' 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/reactions: parameters: - $ref: '#/components/parameters/ReviewId' get: operationId: listReactions tags: - Reactions summary: List reactions on a review description: Returns the reacting users' display names, grouped by reaction kind (up/down), for the specified review. responses: '200': description: Reactions list content: application/json: schema: $ref: '#/components/schemas/ReactionsSummary' 4XX: $ref: '#/components/responses/ErrorResponse' post: operationId: createReaction tags: - Reactions summary: Add a reaction (up/down) to a comment review description: Toggles a thumbs-up or thumbs-down reaction. If the user already reacted with the same kind, the reaction is removed. requestBody: required: true content: application/json: schema: type: object required: - kind properties: kind: type: string enum: - up - down description: Reaction kind to toggle. Sent at the top level, not nested. example: up responses: '200': description: Reaction created content: application/json: schema: $ref: '#/components/schemas/ReactionToggleResponse' '422': $ref: '#/components/responses/UnprocessableEntity' 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/reopen: parameters: - $ref: '#/components/parameters/ReviewId' patch: operationId: reopenReview tags: - Reviews summary: Re-open an adjudicated review description: Reverts the adjudication on a closed review, clearing adjudicated_at and adjudicated_by_id so the triage decision can be revised. Requires author role or higher on the parent project. Returns 422 warning toast if the review has not been adjudicated or was withdrawn by the commenter. responses: '200': description: Review re-opened content: application/json: schema: $ref: '#/components/schemas/ReviewWrapper' links: TriageReopenedReview: operationId: triageReview parameters: reviewId: $response.body#/review/id UpdateReopenedReview: operationId: updateReview parameters: reviewId: $response.body#/review/id examples: reopened: summary: Successfully re-opened value: review: id: 44 action: comment comment: This requirement needs clarification. triage_status: pending adjudicated_at: null '422': description: Cannot re-open (not adjudicated or withdrawn) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' /reviews/{reviewId}/section: parameters: - $ref: '#/components/parameters/ReviewId' patch: operationId: updateReviewSection tags: - Reviews summary: Update the section field on a review description: 'Changes which requirement section (fixtext, check_content, vuln_discussion, etc.) a comment addresses. Idempotent — re-saving the same section returns the review with an `idempotent: true` flag. Requires author role or higher. An audit trail entry is created for non-idempotent changes.' requestBody: required: true content: application/json: schema: type: object required: - audit_comment properties: section: type: - string - 'null' description: Target section key from Review::SECTION_KEYS. Null for overall requirement. enum: - title - severity - status - fixtext - check_content - vuln_discussion - disa_metadata - vendor_comments - artifact_description - xccdf_metadata - null example: fixtext audit_comment: type: string maxLength: 4096 description: Reason for the section change (audit trail). Required — a blank comment returns 422. example: Commenter clarified this applies to the fix text. examples: change_section: summary: Move comment to vuln_discussion value: section: vuln_discussion audit_comment: Re-categorized after author clarification. responses: '200': description: Section updated (or idempotent no-op) content: application/json: schema: type: object required: - review properties: review: $ref: '#/components/schemas/ReviewSummary' idempotent: type: boolean description: Present and true when the section was already the requested value. examples: changed: summary: Section updated value: review: id: 44 action: comment comment: This requirement needs clarification... rule_id: 812 section: vuln_discussion triage_status: pending created_at: '2026-05-19T16:15:00Z' reactions: up: 1 down: 0 idempotent: summary: No change — same section value: review: id: 44 action: comment comment: This requirement needs clarification... rule_id: 812 section: fixtext triage_status: pending created_at: '2026-05-19T16:15:00Z' reactions: up: 1 down: 0 idempotent: true 4XX: $ref: '#/components/responses/ErrorResponse' /memberships: post: operationId: createMembership tags: - Memberships summary: Add a user to a project or component description: Creates a membership linking a user to a project or component with the specified role (viewer, author, reviewer, admin). Requires admin role on the target project. Duplicate memberships are rejected. requestBody: required: true content: application/json: schema: type: object properties: membership: $ref: '#/components/schemas/MembershipInput' examples: add_author: summary: Add a user as author value: membership: user_id: 42 membership_id: 4 membership_type: Project role: author responses: '200': description: Membership created content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: added: summary: User added to project value: toast: title: Member added. message: - Jane Doe added as author. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' /memberships/{membershipId}: parameters: - $ref: '#/components/parameters/MembershipId' patch: operationId: patchMembership tags: - Memberships summary: Partial update of membership role description: Partial update — send only the fields to change. Changes the role (viewer, author, reviewer, admin) for an existing membership. Requires admin role on the parent project. Cannot demote the last admin on a project. requestBody: required: true content: application/json: schema: type: object properties: membership: $ref: '#/components/schemas/MembershipUpdateInput' examples: promote: summary: Promote to reviewer value: membership: role: reviewer responses: '200': description: Membership updated content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: promoted: summary: Role changed value: toast: title: Role updated. message: - Jane Doe is now a reviewer. variant: success '422': description: Validation failed — e.g. downgrading the project's last admin content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: last_admin: summary: Last project admin cannot be downgraded value: toast: title: Could not update membership. message: - Role cannot be changed — this user is the last admin of project 'Photon OS 5'. Transfer the admin role to another member first. variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' put: operationId: updateMembership tags: - Memberships summary: Full replacement of membership role description: Full replacement — all fields required. Changes the role (viewer, author, reviewer, admin) for an existing membership. Requires admin role on the parent project. Cannot demote the last admin on a project. requestBody: required: true content: application/json: schema: type: object properties: membership: $ref: '#/components/schemas/MembershipUpdateInput' examples: promote: summary: Promote to reviewer value: membership: role: reviewer responses: '200': description: Membership updated content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: promoted: summary: Role changed value: toast: title: Role updated. message: - Jane Doe is now a reviewer. variant: success '422': description: Validation failed — e.g. downgrading the project's last admin content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: last_admin: summary: Last project admin cannot be downgraded value: toast: title: Could not update membership. message: - Role cannot be changed — this user is the last admin of project 'Photon OS 5'. Transfer the admin role to another member first. variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteMembership tags: - Memberships summary: Remove a user from a project or component description: Deletes the membership, revoking the user's access. Requires admin role on the parent project. Removed users lose authority over all project-scoped resources including their own pending comments. The last admin of a project cannot be removed — transfer the admin role first. responses: '200': description: Membership removed content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: removed: summary: User removed from project value: toast: title: Member removed. message: - Jane Doe removed from project. variant: success '422': description: Removal blocked — the project's last admin content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: last_admin: summary: Last project admin cannot be removed value: toast: title: Could not remove membership. message: - Cannot remove the last admin of project 'Photon OS 5'. Transfer the admin role to another member first. variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /srgs: get: operationId: listSrgs tags: - Benchmarks summary: List uploaded Security Requirements Guides description: Returns all uploaded SRGs sorted by title. Requires authentication. SRGs are the DISA baseline requirement documents that Components implement. Each SRG contains the rules that Component authors map their controls to. responses: '200': description: All SRGs content: application/json: schema: type: array items: $ref: '#/components/schemas/SrgSummary' examples: srgs: summary: Two SRGs value: - id: 1 srg_id: Container_Platform_SRG name: Container Platform SRG - Ver 2, Rel 4 title: Container Platform Security Requirements Guide version: V2R4 release_date: '2025-10-28' core: false severity_counts: high: 8 medium: 177 low: 3 - id: 2 srg_id: General_Purpose_Operating_System_SRG name: General Purpose Operating System - Ver 3, Rel 3 title: General Purpose Operating System SRG version: V3R3 release_date: '2025-06-15' core: false severity_counts: high: 15 medium: 150 low: 8 4XX: $ref: '#/components/responses/ErrorResponse' post: operationId: uploadSrg tags: - Benchmarks summary: Upload an SRG XCCDF XML file description: Parses and imports a DISA SRG from an XCCDF XML file. Requires admin role. Extracts all rules, CCIs, and metadata from the XML. Duplicate SRGs (same title + version) are rejected. requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: DISA XCCDF XML file (.xml) containing the SRG. responses: '200': description: SRG uploaded and parsed content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: created: summary: SRG imported value: toast: title: SRG created. message: - Successfully created SRG. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' /srgs/{id}: parameters: - $ref: '#/components/parameters/SrgId' get: operationId: getSrg tags: - Benchmarks summary: SRG detail with rules and metadata description: Returns full SRG details including title, version, release date, severity counts, and all embedded rules with DISA metadata and check content. Requires authentication. Used by the SRG detail page (BenchmarkViewer). responses: '200': description: SRG detail with nested rules content: application/json: schema: $ref: '#/components/schemas/SrgDetailResponse' examples: srg: summary: Container Platform SRG value: id: 1 srg_id: Container_Platform_SRG name: Container Platform SRG - Ver 2, Rel 4 title: Container Platform Security Requirements Guide version: V2R4 release_date: '2025-10-28' core: false severity_counts: high: 8 medium: 177 low: 3 srg_rules: - id: 1 rule_id: SV-233015r960759_rule title: The container platform must use TLS 1.2 or greater... version: SRG-APP-000014-CTR-000035 rule_severity: medium 4XX: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteSrg tags: - Benchmarks summary: Delete an uploaded SRG (admin only) description: Permanently deletes an SRG and all its embedded rules. Requires admin role. Components based on this SRG will lose their baseline reference. This action cannot be undone. responses: '200': description: SRG removed content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: removed: summary: SRG removed value: toast: title: SRG removed. message: - Successfully removed SRG. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' /srgs/{id}/export/{type}: parameters: - $ref: '#/components/parameters/SrgId' - name: type in: path required: true description: Export format. schema: type: string enum: - csv - xccdf example: xccdf get: operationId: exportSrg tags: - Benchmarks summary: Export SRG in the specified format description: Downloads the SRG as a CSV spreadsheet or XCCDF XML file. Requires authentication. CSV exports all rules in a flat table. XCCDF exports the original DISA XML format. responses: '200': description: Binary file download content: text/csv: schema: type: string format: binary application/xml: schema: type: string format: binary 4XX: $ref: '#/components/responses/ErrorResponse' /stigs: get: operationId: listStigs tags: - Benchmarks summary: List uploaded STIGs description: Returns all uploaded STIGs sorted by title. Requires authentication. STIGs are published security guidance that can be used as reference when authoring Components. responses: '200': description: All STIGs content: application/json: schema: type: array items: $ref: '#/components/schemas/StigSummary' examples: stigs: summary: Two STIGs value: - id: 1 stig_id: Application_Security_Development_STIG name: Application Security Development STIG - Ver 6, Rel 4 title: Application Security and Development Security Technical Implementation Guide version: V6R4 benchmark_date: '2025-10-01' severity_counts: high: 34 medium: 230 low: 22 - id: 2 stig_id: Crunchy_Data_PostgreSQL_STIG name: Crunchy Data PostgreSQL STIG - Ver 3, Rel 1 title: Crunchy Data PostgreSQL Security Technical Implementation Guide version: V3R1 benchmark_date: '2025-09-15' severity_counts: high: 10 medium: 85 low: 5 4XX: $ref: '#/components/responses/ErrorResponse' post: operationId: uploadStig tags: - Benchmarks summary: Upload a STIG XCCDF XML file description: Parses and imports a published STIG from an XCCDF XML file. Requires admin role. Extracts all rules, CCIs, and metadata. Duplicate STIGs (same title + version) are rejected. requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: DISA XCCDF XML file (.xml) containing the STIG. responses: '200': description: STIG uploaded and parsed content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: added: summary: STIG imported value: toast: title: STIG added. message: - Successfully added Application Security and Development Security Technical Implementation Guide. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' /stigs/{id}: parameters: - $ref: '#/components/parameters/StigId' get: operationId: getStig tags: - Benchmarks summary: STIG detail with rules and metadata description: Returns full STIG details including title, version, benchmark date, description, severity counts, and all embedded rules with DISA metadata and check content. Requires authentication. Used by the STIG detail page (BenchmarkViewer). responses: '200': description: STIG detail with nested rules content: application/json: schema: $ref: '#/components/schemas/StigDetailResponse' examples: stig: summary: Application Security Development STIG value: id: 1 stig_id: Application_Security_Development_STIG name: Application Security Development STIG - Ver 6, Rel 4 title: Application Security and Development Security Technical Implementation Guide version: V6R4 benchmark_date: '2025-10-01' severity_counts: high: 34 medium: 230 low: 22 description: This Security Technical Implementation Guide is published... stig_rules: - id: 660 rule_id: SV-222387r960735_rule title: The application must limit logon sessions... version: APSC-DV-000010 rule_severity: medium 4XX: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteStig tags: - Benchmarks summary: Delete an uploaded STIG (admin only) description: Permanently deletes a STIG and all its embedded rules. Requires admin role. This action cannot be undone. responses: '200': description: STIG removed content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: removed: summary: STIG removed value: toast: title: STIG removed. message: - Successfully removed Application Security and Development Security Technical Implementation Guide. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' /stigs/{id}/export/{type}: parameters: - $ref: '#/components/parameters/StigId' - name: type in: path required: true description: Export format. STIGs support CSV and XCCDF only (InSpec export is Components-only). schema: type: string enum: - csv - xccdf example: xccdf get: operationId: exportStig tags: - Benchmarks summary: Export STIG in the specified format description: Downloads the STIG as CSV or XCCDF XML. Requires authentication. CSV exports all rules in a flat table. XCCDF exports the original DISA XML format. responses: '200': description: Binary file download content: text/csv: schema: type: string format: binary application/xml: schema: type: string format: binary '400': description: Unsupported export type content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' /users: get: operationId: listUsers tags: - Users summary: List all users (admin only) description: Returns all user accounts sorted alphabetically. Includes login tracking fields (last_sign_in_at, failed_attempts, locked_at) for admin monitoring. Requires admin role — returns 403 for non-admin users. responses: '200': description: All user accounts content: application/json: schema: type: array items: $ref: '#/components/schemas/UserSummary' examples: users: summary: Two users value: - id: 1 name: Demo Admin email: admin@example.com provider: null admin: true last_sign_in_at: '2026-05-28T15:00:00Z' failed_attempts: 0 locked_at: null - id: 5 name: Bernice Deckow email: bernice.deckow@example.com provider: null admin: false last_sign_in_at: null failed_attempts: 0 locked_at: null '403': $ref: '#/components/responses/Forbidden' 4XX: $ref: '#/components/responses/ErrorResponse' put: operationId: updateProfile tags: - Users summary: Update the signed-in user's own profile description: 'Updates the current user''s profile (Devise registration update). Field-sensitivity policy: name and slack_user_id save without a password; changing the email — the login identifier — requires current_password (re-authentication for sensitive changes). When email confirmation is enabled, an email change is held in unconfirmed_email until the confirmation link is followed; otherwise it applies immediately. Provider-managed users (OIDC/LDAP) cannot change email here — the identity provider owns it and the parameter is ignored.' requestBody: required: true content: application/json: schema: type: object required: - user properties: user: type: object description: Profile fields to update. properties: name: type: string description: Display name. example: Jane Doe email: type: string format: email description: New login email. Requires current_password when it differs from the current address. Ignored for provider-managed users. example: jane@example.com slack_user_id: type: string description: Slack user ID for notifications. example: U123456 current_password: type: string description: The user's current password — required only when changing the email. example: MyCurrentP@ssw0rd! examples: rename: summary: Passwordless non-sensitive save value: user: name: Jane Doe slack_user_id: U123456 email_change: summary: Email change with re-authentication value: user: email: new-address@example.com current_password: MyCurrentP@ssw0rd! responses: '200': description: Profile updated content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: updated: summary: Successful update value: toast: title: Account updated. message: - Profile updated successfully. variant: success confirmation_pending: summary: Email change held for confirmation value: toast: title: Account updated. message: - A confirmation link has been sent to new-address@example.com. Please follow the link to verify your new email address. variant: success '422': description: Validation failed (e.g. email change without the current password) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: missing_password: summary: Email change without current password value: toast: title: Could not update profile. message: - Current password can't be blank variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteOwnAccount tags: - Auth summary: Delete the signed-in user's own account description: Permanently deletes the current user's account and signs them out. Local-credential users must re-authenticate with current_password (OWASP ASVS 3.7.1); provider-managed and SSO-created accounts are exempt — their identity provider owns re-authentication. Blocked with 422 when the user is the only system administrator or the only admin of any project (transfer the admin role first). Repeated wrong passwords count toward account lockout and return 423 once locked. requestBody: required: false content: application/json: schema: type: object properties: user: type: object properties: current_password: type: string format: password description: The user's current password. Required for local-credential accounts; ignored for provider-managed accounts. example: MyCurrentP@ssw0rd! examples: local_user: summary: Local-credential user re-authenticates value: user: current_password: MyCurrentP@ssw0rd! responses: '200': description: Account deleted and session ended content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: deleted: summary: Successful self-delete value: toast: title: Account deleted. message: - Account deleted successfully. variant: success '422': description: Wrong/missing password, or user is the only system administrator content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: wrong_password: summary: Re-authentication failed value: toast: title: Cannot delete account. message: - Incorrect password. Please enter your current password to delete your account. variant: danger last_admin: summary: Only system administrator value: toast: title: Cannot delete account. message: - You are the only administrator. Promote another user to admin before deleting your account. variant: danger sole_project_admin: summary: Only admin of a project value: toast: title: Cannot delete account. message: - 'You are the only admin of: ''Photon OS 5''. Transfer the admin role to another member of each project first.' variant: danger '423': description: Account locked by repeated failed re-authentication attempts content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: locked: summary: Locked mid-request value: toast: title: Cannot delete account. message: - Your account has been locked due to too many failed attempts. Please try again later. variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /users/{userId}: parameters: - $ref: '#/components/parameters/UserId' patch: operationId: patchUser tags: - Users summary: Partial update of user attributes (admin only) description: Partial update — send only changed fields. Updates a user's name, email, or admin status. Requires admin role. Prevents the last admin from demoting themselves. Sends a Slack notification when admin status changes (if Slack is configured). Returns both a toast and the updated user object. requestBody: required: true content: application/json: schema: type: object properties: user: type: object properties: name: type: string email: type: string format: email admin: type: boolean slack_user_id: type: string description: Slack member ID driving the user's Slack notifications. Send an empty string to clear it. Admin-made changes are audited. example: U0123456789 examples: promote: summary: Promote user to admin value: user: admin: true set_slack: summary: Set the user's Slack member ID value: user: name: Jane Doe email: jane.doe@example.org admin: false slack_user_id: U0123456789 responses: '200': description: User updated content: application/json: schema: $ref: '#/components/schemas/UserToastResponse' examples: updated: summary: User promoted to admin value: toast: title: User updated. message: - Successfully updated user. variant: success user: id: 42 name: Jane Doe email: jane.doe@example.org admin: true '422': description: Cannot remove last admin content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: last_admin: summary: Cannot demote last admin value: toast: title: Cannot remove admin. message: - You are the only admin. Promote another user first. variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' put: operationId: updateUser tags: - Users summary: Full replacement of user attributes (admin only) description: Full replacement — all fields required. Updates a user's name, email, or admin status. Requires admin role. Prevents the last admin from demoting themselves. Sends a Slack notification when admin status changes (if Slack is configured). Returns both a toast and the updated user object. requestBody: required: true content: application/json: schema: type: object properties: user: type: object properties: name: type: string email: type: string format: email admin: type: boolean slack_user_id: type: string description: Slack member ID driving the user's Slack notifications. Send an empty string to clear it. Admin-made changes are audited. example: U0123456789 examples: promote: summary: Promote user to admin value: user: admin: true set_slack: summary: Set the user's Slack member ID value: user: name: Jane Doe email: jane.doe@example.org admin: false slack_user_id: U0123456789 responses: '200': description: User updated content: application/json: schema: $ref: '#/components/schemas/UserToastResponse' examples: updated: summary: User promoted to admin value: toast: title: User updated. message: - Successfully updated user. variant: success user: id: 42 name: Jane Doe email: jane.doe@example.org admin: true '422': description: Cannot remove last admin content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: last_admin: summary: Cannot demote last admin value: toast: title: Cannot remove admin. message: - You are the only admin. Promote another user first. variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteUser tags: - Users summary: Delete a user (admin only) description: Permanently deletes a user account. Requires admin role. Cannot delete the last remaining site admin, nor a user who is the only admin of any project — transfer the admin role first. All project memberships and associated data are cleaned up via dependent destroy. responses: '200': description: User removed content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: removed: summary: User removed value: toast: title: User removed. message: - Successfully removed user. variant: success '422': description: Deletion blocked — the last site admin, or the only admin of one or more projects content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: last_site_admin: summary: Only site admin value: toast: title: Cannot delete user. message: - This is the only admin. Promote another user first. variant: danger sole_project_admin: summary: Only admin of a project value: toast: title: Cannot delete user. message: - 'This user is the only admin of: ''Photon OS 5''. Transfer the admin role to another member of each project first.' variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /users/{userId}/comments: parameters: - $ref: '#/components/parameters/UserId' get: operationId: getUserComments tags: - Users summary: My Comments page — user's comments across accessible projects description: Returns paginated comments authored by the specified user across all projects the requesting user can access. Scoped by project visibility, not identity — this is a filtered view, not a privacy boundary. Supports triage status filtering, project filtering, and pagination. parameters: - name: triage_status in: query required: false description: Filter the user's comments by triage disposition. Absent or "all" returns comments in any status — this page has no default filter. schema: type: string enum: - all - pending - concur - concur_with_comment - non_concur - duplicate - informational - needs_clarification - withdrawn - addressed_by default: all example: concur - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/PerPageParam' - name: project_id in: query required: false description: Filter comments to a specific project. schema: type: integer example: 3 responses: '200': description: Paginated user comments with project/component context content: application/json: schema: type: object required: - rows - pagination additionalProperties: false properties: rows: type: array description: Comment rows for the current page. items: $ref: '#/components/schemas/UserCommentRow' pagination: type: object required: - page - per_page - total additionalProperties: false properties: page: type: integer description: Current page number (1-based). example: 1 per_page: type: integer description: Number of comments per page. example: 25 total: type: integer description: Total number of matching comments. example: 12 examples: comments: summary: User's pending comments across projects value: rows: - id: 29 project_id: 3 project_name: vSphere 7.0 component_id: 4 component_name: Photon OS 3 rule_id: 2397 rule_displayed_name: PHOS-03-000039 commentable_type: BaseRule section: fixtext comment: 'vSphere 7.0: fix command targets ESXi 6.7 path.' created_at: 2026-05-19 14:08:18 UTC triage_status: pending responses_count: 0 reactions: up: 0 down: 0 mine: null pagination: page: 1 per_page: 25 total: 12 '404': $ref: '#/components/responses/NotFound' 4XX: $ref: '#/components/responses/ErrorResponse' /users/unlink_identity: post: operationId: unlinkIdentity tags: - Users summary: Unlink an OAuth provider from the current user description: Removes an OAuth provider link (GitHub, LDAP, OIDC) from the current user's account. Requires the user's current password to confirm. The user must have local login credentials before unlinking to avoid being locked out. Available from the user profile page. requestBody: required: true content: application/json: schema: type: object required: - current_password - provider properties: current_password: type: string description: Current password to confirm the action. example: MyCurrentP@ssw0rd! provider: type: string description: OAuth provider to unlink. enum: - github - ldap - oidc example: github examples: unlink_github: summary: Unlink GitHub provider value: current_password: MyCurrentP@ssw0rd! provider: github responses: '200': description: Provider unlinked content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: unlinked: summary: GitHub unlinked value: toast: title: Provider unlinked. message: - GitHub identity removed from your account. variant: success 4XX: $ref: '#/components/responses/ErrorResponse' /users/admin_create: post: operationId: adminCreateUser tags: - Users summary: Create a new user (admin only) description: 'Creates a new user account. Requires admin role. Three modes based on password and SMTP config: (1) password provided — user can sign in immediately, (2) no password + SMTP enabled — sends setup email via Devise, (3) no password + no SMTP — returns a reset URL the admin delivers manually. Skips email confirmation.' requestBody: required: true content: application/json: schema: type: object properties: user: type: object required: - email properties: name: type: string description: Display name for the new user. example: Jane Doe email: type: string format: email description: Login email address. Must be unique. example: jane.doe@example.org admin: type: boolean description: Whether to grant admin privileges. example: false slack_user_id: type: string description: Slack member ID driving the new user's Slack notifications. Optional; the user can change it later. Admin-made changes are audited. example: U0123456789 password: type: string description: Initial password. If omitted, a reset link is generated. example: SecureP@ssw0rd2026! examples: with_password: summary: Create with explicit password value: user: name: Jane Doe email: jane.doe@example.org admin: false password: SecureP@ssw0rd2026! without_password: summary: Create without password (reset link generated) value: user: name: Jane Doe email: jane.doe@example.org responses: '200': description: User created (response varies by mode) content: application/json: schema: $ref: '#/components/schemas/AdminCreateResponse' examples: with_password: summary: Created with provided password value: toast: title: User created. message: - User jane.doe@example.org created with the provided password. variant: success user: id: 42 name: Jane Doe email: jane.doe@example.org admin: false no_smtp: summary: Created without SMTP — reset URL returned value: toast: title: User created. message: - User jane.doe@example.org created. Deliver the reset link to the user. variant: success user: id: 42 name: Jane Doe email: jane.doe@example.org admin: false reset_url: https://vulcan.example.org/users/password/edit?reset_password_token=abc123 '422': description: Validation error (duplicate email, invalid fields) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: duplicate: summary: Email already taken value: toast: title: Could not create user. message: - Email has already been taken variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /users/{userId}/send_password_reset: parameters: - $ref: '#/components/parameters/UserId' post: operationId: sendPasswordReset tags: - Users summary: Send Devise password reset email (admin only) description: Triggers a Devise password reset email to the specified user. Requires admin role and SMTP to be configured. Returns 422 if SMTP is disabled — use the generate_reset_link endpoint instead. Returns 500 if email delivery fails. responses: '200': description: Reset email sent successfully content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: sent: summary: Email delivered value: toast: title: Reset email sent. message: - Password reset email sent to jane.doe@example.org. variant: success '422': description: SMTP not configured content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: no_smtp: summary: SMTP disabled value: toast: title: SMTP not configured. message: - Email delivery is not available. Use "Generate Reset Link" instead. variant: danger '500': description: Email delivery failed content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' /users/{userId}/generate_reset_link: parameters: - $ref: '#/components/parameters/UserId' post: operationId: generateResetLink tags: - Users summary: Generate a password reset URL without sending email (admin only) description: Generates a Devise reset token and returns the full reset URL. Does not send email — the admin copies the link and delivers it to the user through a secure channel. Requires admin role. Works regardless of SMTP config. responses: '200': description: Reset link generated content: application/json: schema: $ref: '#/components/schemas/ResetLinkResponse' examples: link: summary: Reset link generated value: toast: title: Reset link generated. message: - Reset link generated. Copy it and deliver to the user. variant: success reset_url: https://vulcan.example.org/users/password/edit?reset_password_token=abc123def456 4XX: $ref: '#/components/responses/ErrorResponse' /users/{userId}/set_password: parameters: - $ref: '#/components/parameters/UserId' post: operationId: setPassword tags: - Users summary: Directly set a user's password (admin only) description: Sets the password for a user account without requiring the old password. Requires admin role. The password must meet the configured minimum length (default 15 characters). Does not send any email notification. Used for urgent password resets when SMTP is unavailable. requestBody: required: true content: application/json: schema: type: object properties: user: type: object required: - password properties: password: type: string description: New password (must meet minimum length requirement). example: SecureP@ssw0rd2026! examples: set: summary: Set a new password value: user: password: SecureP@ssw0rd2026! responses: '200': description: Password updated content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: success: summary: Password set successfully value: toast: title: Password updated. message: - Password updated for jane.doe@example.org. variant: success '422': description: Blank password or Devise validation error content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: blank: summary: Empty password value: toast: title: Password required. message: - Password cannot be blank. variant: danger too_short: summary: Password too short value: toast: title: Could not set password. message: - Password is too short (minimum is 15 characters) variant: danger '500': description: Internal error during password update content: application/json: schema: $ref: '#/components/schemas/ToastResponse' 4XX: $ref: '#/components/responses/ErrorResponse' /users/{userId}/lock: parameters: - $ref: '#/components/parameters/UserId' post: operationId: lockUser tags: - Users summary: Lock a user account (admin only) description: Prevents the user from signing in. Requires admin role. Returns 422 if the admin attempts to lock their own account. Creates an audit trail entry recording who locked the account and when. responses: '200': description: Account locked successfully content: application/json: schema: $ref: '#/components/schemas/UserToastResponse' examples: locked: summary: Account locked value: toast: title: Account locked. message: - Account jane.doe@example.org locked. variant: success user: id: 42 name: Jane Doe email: jane.doe@example.org admin: false locked_at: '2026-05-28T15:00:00Z' '422': description: Cannot lock own account content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: self_lock: summary: Admin tried to lock themselves value: toast: title: Cannot lock yourself. message: - You cannot lock your own account. variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /users/{userId}/unlock: parameters: - $ref: '#/components/parameters/UserId' post: operationId: unlockUser tags: - Users summary: Unlock a locked user account (admin only) description: Restores sign-in access for a locked user account. Requires admin role. Clears failed_attempts counter and locked_at timestamp. Creates an audit trail entry recording who unlocked the account. responses: '200': description: Account unlocked content: application/json: schema: $ref: '#/components/schemas/UserToastResponse' examples: unlocked: summary: Account unlocked value: toast: title: Account unlocked. message: - Account jane.doe@example.org unlocked. variant: success user: id: 42 name: Jane Doe email: jane.doe@example.org admin: false locked_at: null 4XX: $ref: '#/components/responses/ErrorResponse' /users/edit: get: operationId: getProfile tags: - Auth summary: Get current user profile (Devise edit) description: Returns the authenticated user's profile as JSON. This is the Devise registration edit endpoint with JSON support. The SPA may prefer GET /api/auth/me which returns the same CurrentUserResponse shape. Requires authentication. responses: '200': description: Current user profile content: application/json: schema: $ref: '#/components/schemas/CurrentUserResponse' examples: profile: summary: User profile value: id: 42 name: Jane Doe email: jane@example.com admin: false provider: null 4XX: $ref: '#/components/responses/ErrorResponse' /users/password: post: operationId: requestPasswordReset tags: - Auth security: [] summary: Request password reset instructions description: Sends a password reset email to the given address. In paranoid mode (default), always returns success — even if the email is not registered — to prevent email enumeration. Blank email returns 422. requestBody: required: true content: application/json: schema: type: object required: - user properties: user: type: object required: - email properties: email: type: string format: email description: Email address of the account to reset. example: jane@example.com examples: reset_request: summary: Request password reset value: user: email: jane@example.com responses: '200': description: Instructions sent (or paranoid success) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: sent: summary: Reset instructions sent value: toast: title: Instructions sent. message: - If your email address exists in our database, you will receive a password recovery link at your email address in a few minutes. variant: success '422': description: Validation error (blank email) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: blank_email: summary: Email is blank value: toast: title: Could not send instructions. message: - Email can't be blank variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' put: operationId: executePasswordReset tags: - Auth security: [] summary: Reset password using token from email description: Resets the user's password using the token from the reset email. On success, signs the user in and returns a success toast. On failure (invalid token, mismatched passwords, complexity violation), returns 422 with error details. requestBody: required: true content: application/json: schema: type: object required: - user properties: user: type: object required: - reset_password_token - password - password_confirmation properties: reset_password_token: type: string description: Token from the password reset email link. example: abc123def456 password: type: string format: password description: New password (must meet complexity requirements). example: N3wS3cure!#Pass password_confirmation: type: string format: password description: Must match the new password. example: N3wS3cure!#Pass examples: reset: summary: Reset with valid token value: user: reset_password_token: abc123def456 password: N3wS3cure!#Pass password_confirmation: N3wS3cure!#Pass responses: '200': description: Password reset successfully — user signed in content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: reset: summary: Successful password reset value: toast: title: Password reset. message: - Your password has been changed successfully. You are now signed in. variant: success '422': description: Invalid token, expired token, or password validation failure content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: invalid_token: summary: Bad reset token value: toast: title: Could not reset password. message: - Reset password token is invalid variant: danger complexity: summary: Password complexity failure value: toast: title: Could not reset password. message: - Password must include at least 2 numbers variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /users/password/edit: get: operationId: validateResetToken tags: - Auth security: [] summary: Validate a password reset token description: Checks whether a password reset token is valid and not expired. The SPA calls this when the user follows the reset link to determine whether to show the reset form or an error message. Returns the minimum password length for client-side validation. parameters: - name: reset_password_token in: query required: true description: The raw reset token from the email link. schema: type: string example: abc123def456 responses: '200': description: Token is valid content: application/json: schema: type: object required: - valid - minimum_password_length properties: valid: type: boolean description: Whether the token is valid and not expired. example: true minimum_password_length: type: integer description: Minimum password length for client-side validation. example: 15 examples: valid: summary: Valid token value: valid: true minimum_password_length: 15 '422': description: Token is invalid, expired, or missing content: application/json: schema: type: object required: - valid - error properties: valid: type: boolean description: Always false for error responses. example: false error: type: string description: Human-readable error message. example: Reset token is invalid or has expired. examples: invalid: summary: Invalid token value: valid: false error: Reset token is invalid or has expired. missing: summary: No token provided value: valid: false error: No reset token provided. 4XX: $ref: '#/components/responses/ErrorResponse' /users/confirmation: post: operationId: resendConfirmation tags: - Auth security: [] summary: Resend email confirmation instructions description: Sends a new confirmation email to the given address. In paranoid mode (default), always returns success — even if the email is not registered or already confirmed — to prevent email enumeration. Blank email returns 422. requestBody: required: true content: application/json: schema: type: object required: - user properties: user: type: object required: - email properties: email: type: string format: email description: Email address to send confirmation to. example: jane@example.com examples: resend: summary: Resend confirmation value: user: email: jane@example.com responses: '200': description: Instructions sent (or paranoid success) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: sent: summary: Confirmation instructions sent value: toast: title: Instructions sent. message: - If your email address exists in our database, you will receive an email with instructions for how to confirm your email address in a few minutes. variant: success '422': description: Validation error (blank email) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: blank_email: summary: Email is blank value: toast: title: Could not send instructions. message: - Email can't be blank variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /users/unlock: post: operationId: requestUnlockInstructions tags: - Auth security: [] summary: Request account unlock instructions description: Sends unlock instructions email to the given address. In paranoid mode (default), always returns success — even if the email is not registered or the account is not locked — to prevent email enumeration. Blank email returns 422. Requires lockout to be enabled with an email-based unlock strategy (both or email). requestBody: required: true content: application/json: schema: type: object required: - user properties: user: type: object required: - email properties: email: type: string format: email description: Email address of the locked account. example: jane@example.com examples: unlock_request: summary: Request unlock value: user: email: jane@example.com responses: '200': description: Instructions sent (or paranoid success) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: sent: summary: Unlock instructions sent value: toast: title: Instructions sent. message: - If your email address exists in our database, you will receive an email with instructions for how to unlock your account in a few minutes. variant: success '422': description: Validation error (blank email) content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: blank_email: summary: Email is blank value: toast: title: Could not send instructions. message: - Email can't be blank variant: danger 4XX: $ref: '#/components/responses/ErrorResponse' /consent/acknowledge: post: operationId: acknowledgeConsent tags: - System summary: Acknowledge consent banner (AC-8) description: Records the user's acknowledgment of the system consent banner in the Rails session. Required by NIST AC-8 before interacting with the application. Does not require authentication — the consent modal appears before login. security: [] responses: '200': description: Consent acknowledged (timestamp stored in session) /projects/{projectId}/project_access_requests: post: operationId: createProjectAccessRequest tags: - Projects summary: Request access to a project description: Creates an access request for the current user on the specified project. Project admins are notified via email (if SMTP is enabled). Returns JSON with toast and the new request ID, or an HTML redirect for browser requests. Returns 422 if the user has already requested access. parameters: - name: projectId in: path required: true description: Numeric ID of the project to request access to. schema: type: integer example: 7 responses: '200': description: Access request created successfully content: application/json: schema: $ref: '#/components/schemas/AccessRequestToastResponse' examples: submitted: summary: Access request submitted value: toast: title: Access request submitted. message: - Your request for access has been sent. variant: success id: 42 '422': description: Validation error — the user has already requested access content: application/json: schema: $ref: '#/components/schemas/ToastResponse' examples: duplicate_request: summary: Duplicate access request value: toast: title: Could not request access. message: - User has already requested access to this project variant: danger /projects/{projectId}/project_access_requests/{requestId}: delete: operationId: destroyProjectAccessRequest tags: - Projects summary: Deny or cancel a project access request description: Admins can deny a pending access request; the requesting user can cancel their own request. If SMTP is enabled, a rejection email is sent when an admin denies. Returns JSON with toast and destroyed request ID, or HTML redirect for browser requests. parameters: - name: projectId in: path required: true description: Numeric ID of the project. schema: type: integer example: 7 - name: requestId in: path required: true description: Numeric ID of the access request. schema: type: integer example: 42 responses: '200': description: Access request destroyed successfully content: application/json: schema: $ref: '#/components/schemas/AccessRequestToastResponse' examples: denied: summary: Admin denied access request value: toast: title: Access request denied. message: - Successfully denied Jane Doe's request to access project. variant: success id: 42 cancelled: summary: Requester cancelled their own request value: toast: title: Access request cancelled. message: - Your request to access Photon OS 5 has been cancelled. variant: success id: 42 '422': description: Validation error content: application/json: schema: type: object properties: error: type: string example: Request could not be destroyed. /projects/{projectId}/triage_response_templates: get: operationId: listTriageResponseTemplates tags: - Projects summary: List triage response templates for a project description: Returns all response templates for the specified project, ordered by name. Viewer+ role required. Templates are reusable canned responses that triagers can insert into the response textarea when making triage decisions. parameters: - name: projectId in: path required: true description: Numeric ID of the project. schema: type: integer example: 42 responses: '200': description: List of templates content: application/json: schema: type: object required: - triage_response_templates properties: triage_response_templates: type: array items: $ref: '#/components/schemas/TriageResponseTemplate' examples: with_templates: summary: Project with templates value: triage_response_templates: - id: 1 name: Accept - standard body: Concur with the finding as written. created_by_id: 42 created_at: '2026-06-01T10:00:00Z' empty: summary: No templates yet value: triage_response_templates: [] 4XX: $ref: '#/components/responses/ErrorResponse' post: operationId: createTriageResponseTemplate tags: - Projects summary: Create a triage response template description: Creates a new reusable response template for the project. Admin role required. Template names must be unique within the project (case-insensitive). parameters: - name: projectId in: path required: true description: Numeric ID of the project. schema: type: integer example: 42 requestBody: required: true content: application/json: schema: type: object required: - triage_response_template properties: triage_response_template: type: object required: - name - body properties: name: type: string description: Short display name (max 200 chars). example: Decline - needs evidence body: type: string description: Markdown response text. example: Unable to incorporate without supporting evidence. examples: basic: summary: Create a template value: triage_response_template: name: Decline - needs evidence body: Unable to incorporate without supporting evidence. responses: '201': description: Template created content: application/json: schema: type: object properties: triage_response_template: $ref: '#/components/schemas/TriageResponseTemplate' examples: created: summary: Newly created template value: triage_response_template: id: 3 name: Decline - needs evidence body: Unable to incorporate without supporting evidence. created_by_id: 42 created_at: '2026-06-03T01:00:00Z' 4XX: $ref: '#/components/responses/ErrorResponse' /projects/{projectId}/triage_response_templates/{id}: patch: operationId: updateTriageResponseTemplate tags: - Projects summary: Update a triage response template description: Updates an existing response template. Admin role required. Name uniqueness is enforced within the project. parameters: - name: projectId in: path required: true description: Numeric ID of the project. schema: type: integer example: 42 - name: id in: path required: true description: Numeric ID of the template. schema: type: integer example: 1 requestBody: required: true content: application/json: schema: type: object required: - triage_response_template properties: triage_response_template: type: object properties: name: type: string example: Accept - updated body: type: string example: Updated response text. responses: '200': description: Template updated content: application/json: schema: type: object properties: triage_response_template: $ref: '#/components/schemas/TriageResponseTemplate' 4XX: $ref: '#/components/responses/ErrorResponse' put: operationId: replaceTriageResponseTemplate tags: - Projects summary: Replace a triage response template description: Full replacement of an existing template. Same behavior as PATCH. Admin role required. parameters: - name: projectId in: path required: true description: Numeric ID of the project. schema: type: integer example: 42 - name: id in: path required: true description: Numeric ID of the template. schema: type: integer example: 1 requestBody: required: true content: application/json: schema: type: object required: - triage_response_template properties: triage_response_template: type: object required: - name - body properties: name: type: string example: Accept - standard body: type: string example: Concur with the finding as written. responses: '200': description: Template replaced content: application/json: schema: type: object properties: triage_response_template: $ref: '#/components/schemas/TriageResponseTemplate' 4XX: $ref: '#/components/responses/ErrorResponse' delete: operationId: deleteTriageResponseTemplate tags: - Projects summary: Delete a triage response template description: Permanently deletes a response template. Admin role required. Returns 204 No Content on success. parameters: - name: projectId in: path required: true description: Numeric ID of the project. schema: type: integer example: 42 - name: id in: path required: true description: Numeric ID of the template. schema: type: integer example: 1 responses: '204': description: Template deleted 4XX: $ref: '#/components/responses/ErrorResponse' /personal_access_tokens: get: operationId: listPersonalAccessTokens tags: - Personal Access Tokens summary: List current user's API tokens description: Returns all personal access tokens for the authenticated user, ordered by creation date (newest first). Admins can pass user_id to list another user's tokens. Token digests are never exposed. Session auth only — token-authenticated requests receive 403. security: - cookieAuth: [] parameters: - name: user_id in: query required: false description: Admin-only. List tokens for this user instead of the current user. schema: type: integer example: 42 responses: '200': description: Token list content: application/json: schema: type: object required: - personal_access_tokens additionalProperties: false properties: personal_access_tokens: type: array items: description: 'Shaped by the caller: the owner''s own tokens, or — when an administrator passes user_id — that user''s tokens with the owner identity attached.' oneOf: - $ref: '#/components/schemas/PersonalAccessTokenSummary' - $ref: '#/components/schemas/PersonalAccessTokenAdminSummary' examples: with_tokens: summary: User has two active tokens value: personal_access_tokens: - id: 1 name: CI Pipeline token_prefix: vulcan_a scopes: - read - write expires_at: '2026-08-30' last_used_at: 2026-05-30 14:22:01 UTC revoked_at: null allowed_ips: null created_at: 2026-05-30 10:00:00 UTC '403': description: Token-authenticated request rejected — token management requires a session (RFC 9457 problem details) content: application/problem+json: schema: type: object additionalProperties: false required: - type - title - status - detail properties: type: type: string description: Stable machine identifier for the error class. example: /docs/api/errors#session_authentication_required title: type: string description: Short human summary of the error class. example: Session authentication required status: type: integer description: HTTP status code, repeated in the body. example: 403 detail: type: string description: Occurrence-specific human explanation. example: Token management requires a signed-in browser session; API tokens cannot create or revoke tokens. examples: session_required: summary: API token used against token management value: type: /docs/api/errors#session_authentication_required title: Session authentication required status: 403 detail: Token management requires a signed-in browser session; API tokens cannot create or revoke tokens. '404': $ref: '#/components/responses/NotFound' 4XX: $ref: '#/components/responses/ErrorResponse' post: operationId: createPersonalAccessToken tags: - Personal Access Tokens summary: Create a new API token description: 'Creates a personal access token ON THE SIGNED-IN ACCOUNT. The raw token is returned ONCE in the response — it is never stored or retrievable after this. Requires current password for session hijack protection. Session auth only. Max 20 active tokens per user, max 365-day lifetime. Ownership can never be redirected: a token authenticates AS its owner, so no caller — administrators included — may mint one on another user''s account, and any user_id supplied in the body is ignored. Administrators oversee other users'' tokens by listing (GET with user_id) and revoking them; account recovery goes through a password reset, where the user re-authenticates.' security: - cookieAuth: [] requestBody: required: true content: application/json: schema: type: object required: - personal_access_token properties: personal_access_token: type: object required: - name - scopes - current_password properties: name: type: string example: CI Pipeline scopes: type: array items: type: string enum: - read - write - admin example: - read - write expires_at: type: string format: date example: '2026-08-30' allowed_ips: type: array items: type: string example: - 10.0.0.0/8 current_password: type: string description: Required for session hijack protection. responses: '201': description: Token created — raw token shown once content: application/json: schema: $ref: '#/components/schemas/PersonalAccessTokenCreateResponse' links: RevokeCreatedToken: operationId: revokePersonalAccessToken parameters: tokenId: $response.body#/personal_access_token/id description: Revoke the newly created token. '401': $ref: '#/components/responses/Unauthorized' '422': description: Validation failed. Toast JSON for domain validation (invalid scopes, max tokens reached, etc.); RFC 9457 problem details when the current password re-verification fails — token creation re-verifies the signed-in user's password before minting a credential, and 422 (not 401) says the authenticated caller's input was wrong. content: application/json: schema: $ref: '#/components/schemas/ToastResponse' application/problem+json: schema: type: object additionalProperties: false required: - type - title - status - detail properties: type: type: string description: Stable machine identifier for the error class. example: /docs/api/errors#incorrect_password title: type: string description: Short human summary of the error class. example: Incorrect password status: type: integer description: HTTP status code, repeated in the body. example: 422 detail: type: string description: Occurrence-specific human explanation. example: Creating or managing API tokens re-verifies your identity, and the current password provided does not match. examples: incorrect_password: summary: Password re-verification failed value: type: /docs/api/errors#incorrect_password title: Incorrect password status: 422 detail: Creating or managing API tokens re-verifies your identity, and the current password provided does not match. 4XX: $ref: '#/components/responses/ErrorResponse' /personal_access_tokens/{tokenId}: parameters: - name: tokenId in: path required: true description: Numeric ID of the personal access token. schema: type: integer example: 1 delete: operationId: revokePersonalAccessToken tags: - Personal Access Tokens summary: Revoke an API token description: Soft-deletes the token by setting revoked_at. The token immediately stops working for API authentication. Audit trail is preserved. Session auth only — users can only revoke their own tokens. security: - cookieAuth: [] responses: '200': description: Token revoked content: application/json: schema: $ref: '#/components/schemas/ToastResponse' '404': $ref: '#/components/responses/NotFound' 4XX: $ref: '#/components/responses/ErrorResponse' /personal_access_tokens/{tokenId}/admin_revoke: parameters: - name: tokenId in: path required: true description: Numeric ID of the personal access token to admin-revoke. schema: type: integer example: 1 delete: operationId: adminRevokePersonalAccessToken tags: - Personal Access Tokens summary: Admin revoke any user's token description: Admin-only endpoint. Revokes any user's token with a required audit comment explaining the reason (e.g. compromised credentials). The audit comment is recorded in the audit trail. Session auth only. security: - cookieAuth: [] requestBody: required: true content: application/json: schema: type: object required: - audit_comment properties: audit_comment: type: string description: Reason for admin revocation (recorded in audit trail). example: Compromised credentials reported by user. responses: '200': description: Token revoked by admin content: application/json: schema: $ref: '#/components/schemas/ToastResponse' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' 4XX: $ref: '#/components/responses/ErrorResponse' components: securitySchemes: cookieAuth: type: apiKey in: cookie name: _vulcan_session tokenAuth: type: http scheme: token description: 'Personal access token authentication. Send via Authorization header: `Authorization: Token vulcan_xxx`. Tokens are SHA-256 hashed server-side (never stored in plaintext). Scopes: read (GET), write (mutations), admin (everything). Create tokens via Settings → API Tokens in the web UI.' schemas: CurrentUserResponse: description: Authenticated user identity for SPA route guards and UI state. type: object required: - id - email - admin properties: id: type: integer description: Unique user identifier. example: 42 name: type: - string - 'null' description: Display name. Null for users who haven't set one. example: Jane Doe email: type: string format: email description: Login email address. example: jane@example.com admin: type: boolean description: Whether the user has admin privileges. example: false provider: type: - string - 'null' description: Authentication provider (local, github, ldap, oidc). Null for local. example: null NavigationResponse: description: App shell navigation data for SPA navbar. Includes static nav links, pending access request notifications, and locked user alerts. type: object required: - nav_links - access_requests - locked_users properties: nav_links: type: array description: Primary navigation links for the sidebar/navbar. Every entry is a top-level link; the documentation entry points at the docs site served by the application. items: type: object properties: icon: type: string description: Bootstrap icon name. example: folder2-open name: type: string description: Display label. example: Projects link: type: string description: URL path. example: /projects access_requests: type: array description: Pending project access requests visible to the current user. Empty for non-admin users. items: type: object properties: id: type: integer description: Access request ID. example: 1 user: type: object description: Requesting user summary. properties: id: type: integer example: 42 name: type: string example: Jane Doe email: type: string format: email example: jane@example.com project: type: object description: Target project summary. properties: id: type: integer example: 7 name: type: string example: RHEL 9 STIG locked_users: type: array description: Locked user accounts (admin-only, lockout enabled). Empty for non-admin or when lockout disabled. items: type: object properties: id: type: integer example: 42 name: type: string example: Locked User email: type: string format: email example: locked@example.com SettingsResponse: description: Public application settings for pre-auth SPA UI. type: object required: - banner - consent - local_login - user_registration - ldap - oidc - smtp - password - lockout properties: banner: type: object description: Classification banner configuration. properties: enabled: type: boolean example: true text: type: string example: UNCLASSIFIED background_color: type: string example: '#007a33' text_color: type: string example: '#ffffff' consent: type: object description: Consent/terms-of-use modal configuration. properties: enabled: type: boolean example: false version: type: integer description: Consent version number. Incrementing re-prompts all users. example: 1 title: type: string example: Terms of Use content: type: string example: '' ttl: type: integer description: Time-to-live in seconds. 0 means consent never expires. example: 0 local_login: type: object description: Local email/password login availability. properties: enabled: type: boolean example: true user_registration: type: object description: Self-service registration availability. properties: enabled: type: boolean example: true ldap: type: object description: LDAP authentication provider. properties: enabled: type: boolean example: false title: type: - string - 'null' description: Display name for the LDAP login button. example: null oidc: type: object description: OpenID Connect authentication provider. properties: enabled: type: boolean example: false title: type: - string - 'null' description: Display name for the OIDC login button. example: null smtp: type: object description: Whether outbound email is available. properties: enabled: type: boolean example: false password: type: object description: Password complexity policy for client-side validation. properties: min_length: type: integer example: 15 min_uppercase: type: integer example: 2 min_lowercase: type: integer example: 2 min_number: type: integer example: 2 min_special: type: integer example: 2 lockout: type: object description: Account lockout policy. properties: enabled: type: boolean example: true maximum_attempts: type: integer example: 3 last_attempt_warning: type: boolean example: true VersionResponse: description: Application version and runtime information. No authentication required. type: object required: - name - version - rails - ruby - environment additionalProperties: false properties: name: type: string description: Application name. example: Vulcan version: type: string description: Current Vulcan application version. example: 2.4.1 rails: type: string description: Rails framework version running the application. example: 8.1.3.1 ruby: type: string description: Ruby interpreter version running the application. example: 3.4.10 environment: type: string description: Current Rails environment. enum: - development - test - production example: development GlobalSearchResponse: description: Results from a global search across projects, components, rules, SRGs, STIGs, and their rules. Serialized by Api::SearchController#global. Each sub-array uses controller-specific inline hashes, NOT Blueprints. type: object required: - projects - components - rules - srgs - stigs - stig_rules - srg_rules properties: projects: type: array description: Projects matching the search query (from user's available_projects). items: type: object properties: id: type: integer description: Unique project identifier. example: 1 name: type: string description: Project name. example: Photon 3 description: type: - string - 'null' description: Project description. example: null components_count: type: integer description: Number of components in the project. example: 1 components: type: array description: Components matching the search query, scoped to what the caller can access — project or component membership, or released components; admins unrestricted. items: type: object properties: id: type: integer description: Unique component identifier. example: 1 name: type: string description: Component name. example: Photon OS 3 version: type: - integer - 'null' description: Component version number. example: 1 release: type: - integer - 'null' description: Component release number. example: 1 project_id: type: integer description: ID of the parent project. example: 1 project_name: type: - string - 'null' description: Name of the parent project. example: Photon 3 metadata: type: - object - 'null' description: Component metadata key-value pairs (from component_metadata.data). example: null rules: type: array description: 'Requirement rows of both document kinds — stig rules and authored SRG requirements — matching the search query, scoped to what the caller can access: project or component membership, or released components; admins unrestricted.' items: type: object properties: id: type: integer description: Unique rule identifier. example: 1786 rule_id: type: string description: Six-digit zero-padded rule number. example: '000001' title: type: - string - 'null' description: Title of the security control. example: The operating system must provide automated mechanisms for supporting account management functions. status: type: - string - 'null' description: Current applicability status of the rule. example: Not Yet Determined component_id: type: integer description: ID of the component this rule belongs to. example: 1 component_prefix: type: - string - 'null' description: Prefix of the parent component. example: PHOS-03 snippet: type: - string - 'null' description: Text excerpt from the matched field showing the search hit in context. example: '[Vuln discussion] ...provide automated mechanisms for supporting...' matched_field: type: - string - 'null' description: Name of the field where the search term was found. example: title comment_count: type: integer description: Number of comments on this rule. example: 0 parent_rule_id: type: - integer - 'null' description: ID of the parent rule (via satisfies relationship). Null if no parent; always null for authored SRG requirements (satisfies is stig-only). example: null parent_display_name: type: - string - 'null' description: Display name of the parent rule. Null if no parent; always null for authored SRG requirements. example: null srgs: type: array description: Security Requirements Guides matching the search query. items: type: object properties: id: type: integer description: Unique SRG identifier. example: 1 srg_id: type: string description: DISA SRG identifier. example: Container_Platform_SRG name: type: - string - 'null' description: SRG name. example: Container Platform SRG - Ver 2, Rel 4 title: type: - string - 'null' description: Full SRG title. example: Container Platform Security Requirements Guide version: type: - string - 'null' description: Version string. example: V2R4 stigs: type: array description: Published STIGs matching the search query. items: type: object properties: id: type: integer description: Unique STIG identifier. example: 1 stig_id: type: - string - 'null' description: DISA STIG identifier. example: Application_Security_Development_STIG name: type: - string - 'null' description: STIG name. example: Application Security Development STIG - Ver 6, Rel 4 title: type: - string - 'null' description: Full STIG title. example: Application Security and Development Security Technical Implementation Guide version: type: - string - 'null' description: Version string. example: V6R4 description: type: - string - 'null' description: STIG description. example: null stig_rules: type: array description: Individual rules from published STIGs matching the search query. items: type: object properties: id: type: integer description: Unique STIG rule identifier. example: 600 rule_id: type: string description: DISA rule identifier. example: SV-222396r857506_rule vuln_id: type: - string - 'null' description: Vulnerability identifier (V-number). example: V-222396 title: type: string description: Requirement title. example: The application must enforce approved authorizations. fixtext: type: - string - 'null' description: Fix text. example: Configure the application to enforce approved authorizations. ident: type: - string - 'null' description: CCI identifiers. example: CCI-000213 stig_id: type: integer description: ID of the parent STIG. example: 1 stig_name: type: - string - 'null' description: Name of the parent STIG. example: Application Security Development STIG - Ver 6, Rel 4 srg_rules: type: array description: Requirements from the published SRG catalog matching the search query. Component-authored requirements are project content and never appear here. items: type: object properties: id: type: integer description: Unique SRG rule identifier. example: 500 rule_id: type: string description: DISA rule identifier. example: SV-222396r857506_rule title: type: string description: Requirement title. example: The application must enforce approved authorizations. fixtext: type: - string - 'null' description: Fix text. example: Configure the application to enforce approved authorizations. ident: type: - string - 'null' description: CCI identifiers. example: CCI-000213 srg_id: type: integer description: ID of the parent SRG. example: 1 srg_name: type: - string - 'null' description: Name of the parent SRG. example: Container Platform SRG - Ver 2, Rel 4 ProjectSummary: description: Base project fields shared by all views. Serialized by ProjectBlueprint (default view). View-specific schemas (ProjectShowResponse, ProjectIndexResponse) extend this with additional fields. type: object required: - id - name properties: id: type: integer description: Unique project identifier. example: 1 name: type: string description: Human-readable project name. example: Photon 3 description: type: - string - 'null' description: Optional longer description of the project purpose and scope. example: null visibility: type: - string - 'null' description: Project visibility setting controlling discoverability by non-members. enum: - discoverable - hidden - null example: hidden memberships_count: type: integer description: Number of members in this project. example: 14 admin_name: type: - string - 'null' description: Display name of the project's point of contact / admin. example: Demo Admin admin_email: type: - string - 'null' format: email description: Email address of the project's point of contact / admin. example: admin@example.org created_at: type: string description: Timestamp when the project was created. Format is "YYYY-MM-DD HH:MM:SS UTC" (Blueprinter default). example: 2026-05-19 14:07:37 UTC updated_at: type: string description: Timestamp when the project was last modified. Format is "YYYY-MM-DD HH:MM:SS UTC" (Blueprinter default). example: 2026-05-19 14:08:17 UTC PaginationMeta: description: Pagination metadata for paginated list endpoints (pagy-backed). Shared by every endpoint returning the canonical { rows, pagination } envelope. type: object required: - page - per_page - total additionalProperties: false properties: page: type: integer description: Current page number (1-based). example: 1 per_page: type: integer description: Records per page (default 25, maximum 100). example: 25 total: type: integer description: Total number of records across all pages. example: 47 BenchmarkLatestResponse: description: Latest-version benchmark listing for dropdown population. One row per benchmark, ranked by numeric V{major}R{minor} version (V10R1 above V4R4). SRG rows carry srg_id; STIG rows carry stig_id. type: object required: - rows additionalProperties: false properties: rows: type: array description: One entry per benchmark, ordered by title. items: type: object required: - id - title - version - name additionalProperties: false properties: id: type: integer description: Unique benchmark record identifier. example: 42 srg_id: type: string description: The SRG's stable benchmark identifier across releases. Present only in /api/srgs/latest responses. example: General_Purpose_Operating_System stig_id: type: string description: The STIG's stable benchmark identifier across releases. Present only in /api/stigs/latest responses. example: RHEL_9_STIG title: type: string description: Full benchmark title. example: General Purpose Operating System Security Requirements Guide version: type: string description: DISA version string in V{major}R{minor} format. example: V3R3 name: type: - string - 'null' description: Human-friendly display name with version and release. example: General Purpose Operating System - Ver 3, Rel 3 BenchmarkStatsResponse: description: Aggregate stats for a benchmark. SRG responses include a usage section — which components are based on the SRG, scoped to components the caller can see (member projects or released). STIG responses carry counts only. type: object required: - rule_count - severity_counts additionalProperties: false properties: rule_count: type: integer description: Total number of rules in the benchmark. example: 250 severity_counts: type: object description: Rule counts grouped by severity (SQL aggregate). required: - high - medium - low additionalProperties: false properties: high: type: integer description: Count of CAT I (high severity) rules. example: 30 medium: type: integer description: Count of CAT II (medium severity) rules. example: 200 low: type: integer description: Count of CAT III (low severity) rules. example: 20 usage: type: object description: Components based on this SRG, scoped to the caller's visibility (member projects or released). Present only on SRG stats responses. required: - count - components additionalProperties: false properties: count: type: integer description: Number of caller-visible components based on this SRG. example: 2 components: type: array description: Caller-visible components, ordered by prefix. items: type: object required: - id - name - project_id - project_name additionalProperties: false properties: id: type: integer description: Component identifier. example: 38 name: type: string description: Component name. example: RHEL 9 Hardened Baseline project_id: type: integer description: Owning project identifier. example: 7 project_name: type: string description: Owning project name. example: Photon OS 5 Hardening ComponentLatestResponse: description: Latest released component per prefix for dropdown population. A component is a STIG in progress — released ones are instance-wide reference data. Ranking is numeric on the integer version/release pair; unreleased drafts never appear. type: object required: - rows additionalProperties: false properties: rows: type: array description: One entry per prefix, ordered by prefix. items: type: object required: - id - prefix - name additionalProperties: false properties: id: type: integer description: Unique component identifier. example: 38 prefix: type: string description: STIG ID prefix — the component's identity across releases. example: RHEL-09 name: type: string description: Component name. example: RHEL 9 Hardened Baseline title: type: - string - 'null' description: Component title. Null when not set. example: Red Hat Enterprise Linux 9 version: type: - integer - 'null' description: Component version number. example: 2 release: type: - integer - 'null' description: Component release number within the version. example: 1 ComponentSummaryResponse: description: 'Lightweight component header for SPA triage/settings routes: identity, counts, SRG info, the caller''s effective permissions, and the serialized comment-phase state machine. Never includes the rules/reviews/histories arrays — fetch the full component for those. The phase booleans mirror the server''s write-guards, so clients can predict rejections without reimplementing phase logic.' type: object required: - id - name - prefix - document_type - title - released - project_id - rules_count - severity_counts - comment_phase - accepting_new_comments - triaging_active - frozen_for_writes additionalProperties: false properties: id: type: integer description: Unique component identifier. example: 38 name: type: string description: Component name. example: RHEL 9 Hardened Baseline prefix: type: string description: STIG ID prefix. example: RHEL-09 document_type: type: string description: Authoring profile of the component (stig or srg). Immutable after creation. enum: - stig - srg example: stig title: type: string description: Component title. example: Red Hat Enterprise Linux 9 version: type: - integer - 'null' description: Component version number. example: 2 release: type: - integer - 'null' description: Component release number within the version. example: 1 released: type: boolean description: Whether the component has been released. example: false project_id: type: integer description: Owning project identifier. example: 7 component_id: type: - integer - 'null' description: Parent component identifier when this is an overlay. Null otherwise. example: null security_requirements_guide_id: type: integer description: Identifier of the SRG this component is based on. example: 3 based_on_title: type: string description: Title of the SRG this component is based on. example: General Purpose Operating System Security Requirements Guide based_on_version: type: string description: Version of the SRG this component is based on. example: V3R3 rules_count: type: integer description: Number of requirement rows in the component — rules for stig-kind components, authored requirements for srg-kind components. example: 203 memberships_count: type: integer description: Number of direct component memberships. example: 4 severity_counts: type: object description: Rule counts grouped by severity. required: - high - medium - low additionalProperties: false properties: high: type: integer description: Count of CAT I (high severity) rules. example: 20 medium: type: integer description: Count of CAT II (medium severity) rules. example: 173 low: type: integer description: Count of CAT III (low severity) rules. example: 10 pending_comment_count: type: integer description: Number of pending top-level comments awaiting triage. example: 5 effective_permissions: type: - string - 'null' description: The caller's effective role on this component (admin, author, reviewer, viewer). Null when the caller has no membership-derived permissions (e.g., reading a released component as a non-member). example: viewer updated_at: type: string format: date-time description: Last update timestamp. example: '2026-07-10T14:07:37.142Z' comment_phase: type: string enum: - open - closed description: Public comment period phase. example: open closed_reason: type: - string - 'null' enum: - adjudicating - finalized - null description: Why the comment period is closed. Null while open or when unset. example: null comment_period_starts_at: type: - string - 'null' format: date-time description: Comment period start timestamp. Null when not scheduled. example: '2026-07-01T00:00:00.000Z' comment_period_ends_at: type: - string - 'null' format: date-time description: Comment period end timestamp. Null when not scheduled. example: '2026-07-15T00:00:00.000Z' accepting_new_comments: type: boolean description: Server write-guard — whether new comments are accepted (phase is open). example: true triaging_active: type: boolean description: Server write-guard — whether triage continues (open, or closed while adjudicating). example: true frozen_for_writes: type: boolean description: Server write-guard — whether the component is read-only (closed and finalized). example: false comment_period_days_remaining: type: - integer - 'null' description: Days until the comment period ends. Null when comments are not being accepted, no end date is set, or the end date has passed. example: 5 RulesByStatus: description: Rule counts grouped into the five canonical DISA status buckets (SQL aggregate). type: object required: - not_yet_determined - applicable_configurable - applicable_inherently_meets - applicable_does_not_meet - not_applicable additionalProperties: false properties: not_yet_determined: type: integer description: Rules with status Not Yet Determined. example: 50 applicable_configurable: type: integer description: Rules with status Applicable - Configurable. example: 120 applicable_inherently_meets: type: integer description: Rules with status Applicable - Inherently Meets. example: 15 applicable_does_not_meet: type: integer description: Rules with status Applicable - Does Not Meet. example: 8 not_applicable: type: integer description: Rules with status Not Applicable. example: 10 SrgRulesByStatus: description: Requirement counts for an SRG-kind component, grouped into the three-value SRG authoring vocabulary. Disjoint from the five-bucket STIG shape — the two never collapse into one list. type: object required: - not_yet_determined - applicable - not_applicable additionalProperties: false properties: not_yet_determined: type: integer description: Authored requirements with status Not Yet Determined. example: 12 applicable: type: integer description: Authored requirements with status Applicable. example: 180 not_applicable: type: integer description: Authored requirements with status Not Applicable. example: 3 SeverityBuckets: description: Rule counts grouped by severity (SQL aggregate). type: object required: - high - medium - low additionalProperties: false properties: high: type: integer description: Count of CAT I (high severity) rules. example: 20 medium: type: integer description: Count of CAT II (medium severity) rules. example: 173 low: type: integer description: Count of CAT III (low severity) rules. example: 10 ComponentStatsResponse: description: 'Rule statistics for one component: counts by status and severity plus completion and lock percentages. Percentages are null when the component has no rules — never a fabricated 0.0.' type: object required: - document_type - rules_by_status - rules_by_severity - rule_count - completion_pct - lock_pct additionalProperties: false properties: document_type: type: string description: Authoring profile of the component — tells clients which rules_by_status branch to expect. enum: - stig - srg example: stig rules_by_status: description: 'Status buckets shaped by the component''s document_type: the five STIG buckets or the three SRG buckets. The two branch shapes are disjoint; the component''s document_type tells clients which to expect.' oneOf: - $ref: '#/components/schemas/RulesByStatus' - $ref: '#/components/schemas/SrgRulesByStatus' rules_by_severity: $ref: '#/components/schemas/SeverityBuckets' rule_count: type: integer description: Total number of rules in the component. example: 203 completion_pct: type: - number - 'null' description: Percentage of rules with a determined status (anything other than Not Yet Determined), rounded to one decimal. Null when there are no rules. example: 75.4 lock_pct: type: - number - 'null' description: Percentage of locked rules, rounded to one decimal. Null when there are no rules. example: 12.3 ComponentWorkflowStateResponse: description: Workflow readiness for a component across the authoring, lock, review, comment, triage, and export stages. Counts are SQL aggregates; the comment booleans mirror the server's write-guards. type: object required: - document_type - authoring - locks - reviews - comment - triage - export additionalProperties: false properties: document_type: type: string description: Authoring profile of the component. enum: - stig - srg example: stig authoring: type: object description: Rule authoring progress. required: - rules_total - rules_determined additionalProperties: false properties: rules_total: type: integer description: Total rules in the component. example: 203 rules_determined: type: integer description: Rules with a determined status (not Not Yet Determined). example: 153 locks: type: object description: Rule lock progress toward release. required: - locked - total - all_locked additionalProperties: false properties: locked: type: integer description: Number of locked rules. example: 25 total: type: integer description: Total rules in the component. example: 203 all_locked: type: boolean description: True when every rule is locked and at least one rule exists — the precondition for release. example: false reviews: type: object description: Open review-request workload. required: - under_review additionalProperties: false properties: under_review: type: integer description: Rules currently under review (review requested). example: 4 comment: type: object description: Public comment period state (server write-guards). required: - phase - accepting_new_comments - triaging_active - frozen_for_writes - pending_comments additionalProperties: false properties: phase: type: string enum: - open - closed description: Public comment period phase. example: open accepting_new_comments: type: boolean description: Whether new comments are accepted (phase is open). example: true triaging_active: type: boolean description: Whether triage continues (open, or closed while adjudicating). example: true frozen_for_writes: type: boolean description: Whether the component is read-only (closed and finalized). example: false pending_comments: type: integer description: Top-level comments awaiting triage — rule-attached and component-attached both count. example: 3 triage: type: object description: Triage and adjudication workload. required: - pending - awaiting_adjudication additionalProperties: false properties: pending: type: integer description: Top-level comments awaiting triage. example: 3 awaiting_adjudication: type: integer description: Comments triaged concur/concur_with_comment/non_concur but not yet adjudicated. example: 1 export: type: object description: Release/export readiness. required: - released - releasable additionalProperties: false properties: released: type: boolean description: Whether the component has been released. example: false releasable: type: boolean description: Whether the component can be released (all rules locked, not already released). example: false TriageSummaryResponse: description: Triage aggregates over top-level comments — rule-attached and component-attached both count. Served for a single component or aggregated across a project's components. adjudication_pct is null when there are no top-level comments. type: object required: - by_triage_status - total - adjudicated - adjudication_pct additionalProperties: false properties: by_triage_status: type: object description: Count of top-level comments per triage status (every status key present). required: - pending - concur - concur_with_comment - non_concur - duplicate - informational - needs_clarification - withdrawn - addressed_by additionalProperties: false properties: pending: type: integer description: Comments awaiting triage. example: 3 concur: type: integer description: Comments triaged as concur. example: 1 concur_with_comment: type: integer description: Comments triaged as concur with comment. example: 0 non_concur: type: integer description: Comments triaged as non-concur. example: 0 duplicate: type: integer description: Comments marked duplicate of another comment. example: 0 informational: type: integer description: Comments triaged as informational. example: 1 needs_clarification: type: integer description: Comments needing clarification from the author. example: 0 withdrawn: type: integer description: Comments withdrawn by their author. example: 0 addressed_by: type: integer description: Comments addressed by another rule. example: 0 total: type: integer description: Total top-level comments. example: 5 adjudicated: type: integer description: Top-level comments with an adjudication timestamp. example: 1 adjudication_pct: type: - number - 'null' description: Percentage of top-level comments adjudicated, rounded to one decimal. Null when there are no top-level comments. example: 20 ProjectAggregateStats: description: Project-wide requirement statistics aggregated across every component. Per-document-type status sections never collapse into each other; rule_count, completion and lock percentages are type-agnostic. type: object required: - rules_by_status_by_type - rules_by_severity - rule_count - completion_pct - lock_pct additionalProperties: false properties: rules_by_status_by_type: type: object description: Per-document-type status sections. required: - stig - srg additionalProperties: false properties: stig: $ref: '#/components/schemas/RulesByStatus' srg: $ref: '#/components/schemas/SrgRulesByStatus' rules_by_severity: $ref: '#/components/schemas/SeverityBuckets' rule_count: type: integer description: Total live requirements across all components, every document kind. example: 207 completion_pct: type: - number - 'null' description: Percentage of determined requirements (anything other than Not Yet Determined) across all kinds. Null when the project has no requirements. example: 75.4 lock_pct: type: - number - 'null' description: Percentage of locked requirements across all kinds. Null when empty. example: 12.3 ProjectStatsResponse: description: 'Project-level rule statistics: totals aggregated across every component plus a per-component breakdown. Percentages are null when a denominator is zero.' type: object required: - aggregate - components additionalProperties: false properties: aggregate: $ref: '#/components/schemas/ProjectAggregateStats' components: type: array description: Per-component breakdown, ordered by prefix. items: type: object required: - id - name - prefix - document_type - rule_count - completion_pct - lock_pct additionalProperties: false properties: id: type: integer description: Component identifier. example: 38 name: type: string description: Component name. example: RHEL 9 Hardened Baseline prefix: type: string description: STIG ID prefix. example: RHEL-09 document_type: type: string description: Authoring profile of the component — each row carries its own kind. enum: - stig - srg example: stig rule_count: type: integer description: Rules in this component. example: 203 completion_pct: type: - number - 'null' description: Percentage of determined rules. Null when the component has no rules. example: 75.4 lock_pct: type: - number - 'null' description: Percentage of locked rules. Null when the component has no rules. example: 12.3 MembershipSummary: description: Project or component membership linking a user to a role. type: object required: - id - user_id - role - membership_type - membership_id additionalProperties: false properties: id: type: integer description: Unique membership identifier. example: 15 user_id: type: integer description: ID of the member user. example: 42 role: type: string description: Access level for this membership. enum: - viewer - author - reviewer - admin example: author membership_type: type: string description: Type of resource this membership belongs to. enum: - Project - Component example: Project membership_id: type: integer description: ID of the project or component this membership belongs to. example: 4 name: type: - string - 'null' description: Display name of the member (delegated from User). example: Jane Doe email: type: - string - 'null' format: email description: Email address of the member (delegated from User). example: jane.doe@example.org ProjectIndexResponse: description: Project listing entry with per-user computed fields (admin, is_member, access_request_id). type: object required: - id - name additionalProperties: false properties: id: type: integer description: Unique project identifier. example: 4 name: type: string description: Project name. example: Container Platform description: type: - string - 'null' description: Project description. example: STIG for container orchestration platforms visibility: type: string description: Project visibility level. enum: - discoverable - hidden example: discoverable memberships_count: type: integer description: Number of members in this project. example: 14 admin_name: type: - string - 'null' description: Name of the project's point of contact. example: Demo Admin admin_email: type: - string - 'null' format: email description: Email of the project's point of contact. example: admin@example.org created_at: type: string description: When the project was created. Format is "YYYY-MM-DD HH:MM:SS UTC" (Blueprinter default). example: 2026-05-19 14:07:37 UTC updated_at: type: string description: When the project was last modified. Format is "YYYY-MM-DD HH:MM:SS UTC" (Blueprinter default). example: 2026-05-19 14:08:17 UTC memberships: type: array description: Project members with roles. items: $ref: '#/components/schemas/MembershipSummary' admin: type: boolean description: Whether the current user is an admin on this project. example: true is_member: type: boolean description: Whether the current user is a member of this project. example: true access_request_id: type: - integer - 'null' description: ID of the current user's pending access request, if any. example: null pending_comment_count: type: integer description: Number of pending (untriaged) comments across all components. example: 10 total_comment_count: type: integer description: Total comment count across all components. example: 108 pending_comment_link: type: - string - 'null' description: Deep-link to the triage page for pending comments. Null if no comments exist. example: /components/29/triage ProjectInput: description: Input fields for creating or updating a Vulcan project. type: object required: - name properties: name: type: string description: Human-readable project name. example: Container Platform description: type: string description: Optional longer description of the project purpose and scope. example: STIG for container orchestration platforms. visibility: type: string description: Project visibility setting controlling discoverability by non-members. enum: - discoverable - hidden example: discoverable project_metadata_attributes: type: object description: Project metadata as a nested-attributes object — the one metadata shape, accepted at creation and update alike. The data hash holds free-form string keys (points of contact, Slack channel, and so on). properties: data: type: object description: Free-form metadata keys and values. additionalProperties: type: string example: POC Name: Jane Doe POC Email: jane@example.com Slack Channel ID: C0123456789 ToastObject: description: 'The inner toast notification object with title, message array, and variant. This is the reusable shape — ToastResponse wraps it as { toast: ToastObject }. Use this via $ref when composing multi-key responses (toast + user, toast + reset_url, etc.).' type: object required: - title - message - variant additionalProperties: false properties: title: type: string description: Short human-readable summary of the outcome. example: User updated. message: type: array description: Detail lines providing additional context about the operation result. items: type: string example: - Successfully updated user. variant: type: string description: Bootstrap alert variant controlling how the toast is styled in the UI. enum: - success - danger - warning - info example: success ProjectCreateResponse: description: Response from project creation. Success includes a toast notification and a redirect URL to the new project page. Error includes only the toast (no redirect_url). type: object required: - toast properties: toast: $ref: '#/components/schemas/ToastObject' redirect_url: type: string description: Relative URL to the newly created project page. Present on success, absent on error. example: /projects/1 ProjectDetails: description: Project-wide requirement statistics with per-document-type sections. The stig and srg sections never collapse into each other; top-level numbers (total, lck, nur, ur) are type-agnostic. type: object required: - stig - srg - nur - ur - lck - total additionalProperties: false properties: stig: type: object description: STIG-kind requirement counts in the five DISA buckets. required: - ac - aim - adnm - na - nyd - total additionalProperties: false properties: ac: type: integer description: Applicable - Configurable. example: 120 aim: type: integer description: Applicable - Inherently Meets. example: 15 adnm: type: integer description: Applicable - Does Not Meet. example: 8 na: type: integer description: Not Applicable. example: 10 nyd: type: integer description: Not Yet Determined. example: 50 total: type: integer description: Total STIG-kind requirements. example: 203 srg: type: object description: SRG-kind requirement counts in the three-value vocabulary. required: - applicable - na - nyd - total additionalProperties: false properties: applicable: type: integer description: Applicable. example: 180 na: type: integer description: Not Applicable. example: 3 nyd: type: integer description: Not Yet Determined. example: 12 total: type: integer description: Total SRG-kind requirements. example: 195 nur: type: integer description: Unlocked requirements not under review (all kinds). example: 40 ur: type: integer description: Unlocked requirements under review (all kinds). example: 5 lck: type: integer description: Locked requirements (all kinds). example: 158 total: type: integer description: Total live requirements across every document kind. example: 398 ComponentSummary: description: Base component fields shared by all views. Serialized by ComponentBlueprint (default view). View-specific schemas (ComponentEditorResponse, ComponentIndexResponse) extend this with additional fields. type: object required: - id - name - prefix properties: id: type: integer description: Unique component identifier. example: 1 name: type: string description: Human-readable component name. example: Photon OS 3 prefix: type: string description: Short alphanumeric prefix used to construct rule IDs (e.g. PHOS-03 in PHOS-03-000010). example: PHOS-03 document_type: type: string description: 'Authoring profile of the component: stig components author STIG requirements, srg components author SRG requirements. Immutable after creation.' enum: - stig - srg example: stig version: type: - integer - 'null' description: Version number of the component. Null if not yet set. example: 1 release: type: - integer - 'null' description: Release number of the component. Null if not yet set. example: 1 based_on_title: type: - string - 'null' description: Title of the SRG this component is based on. Null if the SRG has no title or component has no SRG. example: VMware vSphere 7.0 STIG Readiness Guide based_on_version: type: - string - 'null' description: Version of the SRG this component is based on. Null if no SRG. example: '1' severity_counts: type: object description: Count of rules at each severity level within this component. properties: high: type: integer example: 20 medium: type: integer example: 173 low: type: integer example: 10 example: high: 20 medium: 173 low: 10 pending_comment_count: type: integer description: Number of pending (untriaged) top-level comments on this component. Pre-batched via Component.pending_comment_counts. example: 3 ComponentIndexResponse: description: Component listing entry for project pages. Serialized by ComponentBlueprint :index view. Extends ComponentSummary (default fields) with index-specific fields. allOf: - $ref: '#/components/schemas/ComponentSummary' - type: object properties: updated_at: type: string description: Timestamp when the component was last modified. Format is "YYYY-MM-DD HH:MM:SS UTC" (Blueprinter default). example: 2026-05-29 15:36:06 UTC released: type: boolean description: Whether this component has been marked as released (finalized). example: true rules_count: type: integer description: Number of requirement rows (security controls) in this component — rules for stig-kind components, authored requirements for srg-kind components. example: 203 component_id: type: - integer - 'null' description: ID of the source component if this is an overlay. Null for original components. example: null ProjectShowResponse: description: Full project detail for the project show page. Serialized by ProjectBlueprint :show view. 18 total fields including nested components, memberships, users, access_requests. allOf: - $ref: '#/components/schemas/ProjectSummary' - type: object properties: effective_permissions: type: - string - 'null' description: Current user's role on this project (admin, reviewer, author, viewer). Null when the user is not a member. System admins always get 'admin'. enum: - admin - reviewer - author - viewer - null example: admin pending_comment_count: type: integer description: Aggregate pending comment count across all components. example: 1 details: description: Project-wide requirement statistics. Per-document-type sections (stig with the five DISA buckets, srg with the three SRG buckets) never collapse into each other; total, lock, and review-state numbers are type-agnostic and span every kind. oneOf: - $ref: '#/components/schemas/ProjectDetails' - type: 'null' histories: type: array description: Recent audit trail entries (last 50). items: type: object metadata: type: - object - 'null' description: Project metadata key-value pairs. example: null memberships: type: array description: Project members with roles. items: $ref: '#/components/schemas/MembershipSummary' components: type: array description: Components in this project (ComponentBlueprint :index view). items: $ref: '#/components/schemas/ComponentIndexResponse' available_components: type: array description: Components available to add (from other projects the user can access). items: $ref: '#/components/schemas/ComponentIndexResponse' users: type: array description: All users associated with this project. items: type: object properties: id: type: integer name: type: - string - 'null' email: type: string format: email access_requests: type: array description: Pending access requests from non-member users. items: type: object properties: id: type: integer description: Access request ID. user: type: object properties: id: type: integer name: type: - string - 'null' email: type: string format: email project_id: type: integer ToastResponse: description: Canonical mutation response returned by all POST/PUT/PATCH/DELETE endpoints that return only a toast notification (no additional data). type: object required: - toast additionalProperties: false properties: toast: $ref: '#/components/schemas/ToastObject' ImportSummary: description: Summary of what was imported (or would be imported in dry_run mode) from a JSON archive backup. Returned by JsonArchiveImporter. type: object properties: dry_run: type: boolean description: Whether this was a preview (true) or real import (false). Only present in dry_run responses. example: true components_imported: type: integer description: Number of components imported. example: 2 rules_imported: type: integer description: Total rules imported across all components. example: 264 satisfactions_imported: type: integer description: Number of rule satisfaction relationships imported. example: 12 reviews_imported: type: integer description: Number of review records imported. example: 48 memberships_imported: type: integer description: Number of project memberships imported. example: 3 srgs_imported: type: integer description: Number of SRGs auto-imported from the archive. example: 1 srg_details: type: array description: Details of SRGs found in the archive (dry_run only). items: type: object properties: title: type: string version: type: string component_details: type: array description: Per-component breakdown of what was imported. items: type: object properties: name: type: string example: Photon OS 3 rule_count: type: integer example: 132 srg_title: type: - string - 'null' example: General Purpose Operating System SRG srg_version: type: - string - 'null' example: V3R3 CreateFromBackupDryRunResponse: description: Response from a dry-run preview of creating a project from backup. Returns import summary, warnings, and extracted project defaults. type: object required: - summary - warnings - project_defaults properties: summary: $ref: '#/components/schemas/ImportSummary' warnings: type: array description: Non-fatal warnings found during preview. items: type: string example: [] project_defaults: type: object description: Default values extracted from the archive for pre-filling the create form. properties: name: type: - string - 'null' description: Original project name from the archive. example: My Original Project description: type: - string - 'null' description: Original project description. example: A test project visibility: type: - string - 'null' description: Original project visibility setting. example: discoverable CreateFromBackupResponse: description: Response from actually creating a project from a backup archive. Returns redirect URL, import summary, and toast notification. type: object required: - redirect_url - summary - toast properties: redirect_url: type: string description: URL to redirect to after successful project creation. example: /projects/123 summary: $ref: '#/components/schemas/ImportSummary' toast: $ref: '#/components/schemas/ToastObject' ImportBackupResponse: description: Response from importing a JSON archive backup into an existing project. Includes the toast notification, import summary, and any warnings. type: object required: - toast - summary - warnings properties: toast: $ref: '#/components/schemas/ToastObject' summary: $ref: '#/components/schemas/ImportSummary' warnings: type: array description: Non-fatal warnings encountered during import. items: type: string example: [] AuditEntry: description: 'A single audit trail entry recording a change to an auditable record. Serialized by VulcanAudit#format. Note: the field is "name" (username), NOT "user_id" — VulcanAudit#format does not expose user IDs.' type: object required: - id - action - auditable_type - auditable_id - created_at - audited_changes additionalProperties: false properties: id: type: integer description: Unique audit entry identifier. example: 224 action: type: string description: Type of change that was made. enum: - create - update - destroy example: update auditable_type: type: string description: Rails model class name of the audited record. example: Component auditable_id: type: integer description: Primary key of the audited record. example: 1 name: type: - string - 'null' description: Display name of the user who made the change. Null for system-initiated changes or seed data. example: Demo Admin audited_name: type: - string - 'null' description: Display name of the audited record's owner. Null when not applicable. example: null comment: type: - string - 'null' description: Audit comment text (e.g. reason for admin action). Null for most changes. example: null created_at: type: string description: Timestamp when the audit entry was recorded. example: 2026-05-19 14:07:49 UTC audited_changes: type: array description: Array of changed attributes with before/after values. Each entry has a field name, previous value, and new value. items: type: object required: - field properties: field: type: string description: Name of the changed attribute. For AdditionalAnswer changes, this is the question name rather than the column name. example: released prev_value: description: Previous value before the change. Null for create actions. example: false new_value: description: New value after the change. example: true ComponentInput: description: Input fields for creating or updating a component within a project. type: object required: - name - prefix - title - security_requirements_guide_id properties: security_requirements_guide_id: type: integer description: 'The PRIMARY source SRG (based_on). Always a declared source: it joins the declared source set automatically even when declared_source_srg_ids omits it. STIG-kind components derive from non-core SRGs, SRG-kind components from core SRGs.' example: 1 declared_source_srg_ids: type: array description: The full declared source-SRG set for multi-parent derivation. Every listed SRG becomes a declared parent and contributes its requirements at creation (full union by default). Eligibility is enforced per document_type — non-core SRGs for stig, core SRGs for srg. Omit for the classic single-source create. items: type: integer example: - 1 - 2 requirement_selections: type: object description: Selective-import filter. Keys are declared source SRG ids, values the requirement versions to import from that source. When present, only the listed requirements are imported and a declared source absent from the map contributes none; when omitted, creation imports the full union of every declared source. additionalProperties: type: array items: type: string example: '1': - SRG-OS-000001 - SRG-OS-000002 '2': - SRG-APP-000101 name: type: string description: Human-readable component name. example: Container SRG prefix: type: string description: Short alphanumeric prefix used to construct rule IDs (e.g. CNTR in CNTR-00-000050). example: CNTR document_type: type: string description: 'Authoring profile for the new component: stig authors STIG requirements from a source SRG; srg authors SRG requirements. Defaults to stig; immutable after creation.' enum: - stig - srg example: stig version: type: integer description: Version number of the component. example: 1 release: type: integer description: Release number of the component. example: 1 title: type: string description: Full official title of the component. example: Container Platform Security Technical Implementation Guide description: type: string description: Optional longer description of the component scope and purpose. example: STIG guidance for container orchestration platform deployments. advanced_fields: type: boolean description: Whether the editor shows the advanced field set for this component. example: false additional_questions_attributes: type: array description: Nested additional-question definitions — the same shape the update path accepts, minus id/_destroy (meaningless at creation and not accepted). On the duplicate path, provided questions REPLACE the ones copied from the source component. items: type: object properties: name: type: string example: Deployment environment question_type: type: string enum: - dropdown - freeform - url example: dropdown options: type: array description: Choice list — required when question_type is dropdown. items: type: string example: - Cloud - On-prem component_metadata_attributes: type: object description: Nested metadata payload; data is a free-form string map — the same shape the update path accepts. On the duplicate path, provided metadata replaces the copied record. The slack_channel_id convenience field merges into this map as "Slack Channel ID" and wins over a same-key entry. properties: data: type: object additionalProperties: type: string example: Vendor: Acme POC: Sam slack_channel_id: type: string description: Convenience field — stored as the metadata key "Slack Channel ID". Accepted at creation only; use component_metadata_attributes on update. example: C0123456789 RuleSummary: description: Base rule fields shared by all views. Serialized by RuleBlueprint (default view / navigator). View-specific schemas (RuleEditorResponse, RulePickerResponse) extend this with additional fields. type: object required: - id - rule_id - locked properties: id: type: integer description: Unique rule identifier. example: 1786 rule_id: type: string description: Six-digit zero-padded rule number combined with the component prefix to form the displayed ID (e.g. PHOS-03-000001). example: '000001' title: type: - string - 'null' description: Title of the security control. Null if not yet authored. example: The operating system must provide automated mechanisms for supporting account management functions. version: type: - string - 'null' description: SRG requirement version identifier mapping this rule to its SRG source. example: SRG-OS-000001-GPOS-00001 status: type: - string - 'null' description: Current applicability status of the rule. Null if not yet determined. enum: - Not Yet Determined - Applicable - Configurable - Applicable - Inherently Meets - Applicable - Does Not Meet - Not Applicable - null example: Not Yet Determined rule_severity: type: - string - 'null' description: DISA severity level of the rule. enum: - low - medium - high - null example: medium locked: type: boolean description: Whether the rule is locked from further edits pending review. example: true review_requestor_id: type: - integer - 'null' description: ID of the user who requested review for this rule. Null if no review requested. example: null changes_requested: type: boolean description: Whether changes have been requested on this rule during review. example: false comment_summary: type: object description: Per-rule comment counts. Computed in-memory from eager-loaded reviews. required: - open - total properties: open: type: integer description: Comments not yet adjudicated (pending, triaged, needs_clarification) including replies under open parents. example: 0 total: type: integer description: Total comment count across all statuses. example: 0 DisaRuleDescription: description: DISA rule description fields — vulnerability discussion, mitigations, and related metadata. type: object required: - id additionalProperties: false properties: id: type: integer description: Unique description record identifier. example: 300 vuln_discussion: type: - string - 'null' description: Vulnerability discussion explaining why this requirement matters. example: Without verification, containers may execute untrusted code... false_positives: type: - string - 'null' description: Known false positive scenarios for this check. example: null false_negatives: type: - string - 'null' description: Known false negative scenarios for this check. example: null documentable: type: - boolean - 'null' description: Whether this requirement is documentable. example: false mitigations: type: - string - 'null' description: Available mitigations if the requirement cannot be met directly. example: null severity_override_guidance: type: - string - 'null' description: Guidance for when severity may be overridden by the assessor. example: null potential_impacts: type: - string - 'null' description: Potential impacts of non-compliance. example: null third_party_tools: type: - string - 'null' description: Third-party tools that can assist with compliance checking. example: null mitigation_control: type: - string - 'null' description: Compensating controls that mitigate the risk. example: null responsibility: type: - string - 'null' description: Who is responsible for implementing this requirement. example: null ia_controls: type: - string - 'null' description: Information assurance controls associated with this requirement. example: null mitigations_available: type: - string - 'null' description: Whether mitigations are available for this requirement. example: null poam_available: type: - string - 'null' description: Whether a Plan of Action and Milestones is available. example: null poam: type: - string - 'null' description: Plan of Action and Milestones content. example: null _destroy: type: boolean description: Nested attributes destroy flag (always false in read responses). example: false CheckSummary: description: STIG check content — how to verify a security requirement is met. type: object required: - id additionalProperties: false properties: id: type: integer description: Unique check identifier. example: 200 system: type: - string - 'null' description: Check system identifier (e.g., C-OVAL for automated checks). example: C-56947r840354_chk content_ref_name: type: - string - 'null' description: Reference name for the check content. example: M content_ref_href: type: - string - 'null' description: URL reference for the check content. example: DPMS_XCCDF-Container_Platform_SRG.xml content: type: - string - 'null' description: The check procedure text — steps to verify compliance. example: Verify the container platform restricts access to container images... _destroy: type: boolean description: Nested attributes destroy flag (always false in read responses). example: false SatisfactionSummary: description: Rule satisfaction relationship — this rule satisfies (implements) an SRG requirement. type: object required: - id - rule_id additionalProperties: false properties: id: type: integer description: Unique satisfaction record identifier. example: 50 rule_id: type: integer description: ID of the rule that is satisfied. example: 100 srg_id: type: - string - 'null' description: SRG requirement version identifier (from the SRG rule's version field). example: CNTR-00-000050 SatisfiedBySummary: description: Satisfied-by relationship — extends SatisfactionSummary with the parent rule's fix text. type: object required: - id - rule_id additionalProperties: false properties: id: type: integer description: Unique satisfaction record identifier. example: 50 rule_id: type: integer description: ID of the parent rule that satisfies this one. example: 100 srg_id: type: - string - 'null' description: SRG requirement version identifier. example: CNTR-00-000050 fixtext: type: - string - 'null' description: Fix text from the parent rule (inherited content). example: Configure the container platform to restrict access... RuleDescriptionSummary: description: Rule description record — the HTML/text description block for a rule. type: object required: - id additionalProperties: false properties: id: type: integer description: Unique description record identifier. example: 400 description: type: - string - 'null' description: The rule description text (may contain HTML from XCCDF source). example: Without verification, containers may execute untrusted code. _destroy: type: boolean description: Nested attributes destroy flag (always false in read responses). example: false ReviewSummary: description: A review action recorded on a rule. Serialized by ReviewBlueprint (default view). The user_id field is intentionally excluded as a public-comment correlation guard. type: object required: - id - action - comment - rule_id - created_at - triage_status - reactions additionalProperties: false properties: id: type: integer description: Unique review identifier. example: 1 action: type: string description: The type of review action that was performed. enum: - comment - request_review - revoke_review_request - approve - lock example: comment comment: type: string description: The comment text accompanying this review action. example: The check says "verify that TLS 1.2 or greater is being used" but does not specify HOW to verify. created_at: type: string description: Timestamp when the review was created. Format is "YYYY-MM-DD HH:MM:SS UTC" (Blueprinter default). example: 2026-05-19 14:08:17 UTC triage_status: type: - string - 'null' description: Current triage disposition of the comment. enum: - pending - concur - concur_with_comment - non_concur - duplicate - informational - needs_clarification - withdrawn - addressed_by - null example: pending triage_set_at: type: - string - 'null' description: Timestamp when the triage status was last changed. Null if still pending. example: null adjudicated_at: type: - string - 'null' description: Timestamp when the comment reached a terminal triage state. Null if not yet adjudicated. example: null rule_id: type: - integer - 'null' description: ID of the rule this review is attached to. Null for component-scoped reviews. example: 2976 section: type: - string - 'null' description: Rule section the comment applies to (e.g. fixtext, check_content, vuln_discussion). Null for general comments. example: check_content responding_to_review_id: type: - integer - 'null' description: ID of the parent review if this is a threaded reply. Null for top-level reviews. example: null duplicate_of_review_id: type: - integer - 'null' description: ID of the review this is marked as a duplicate of. Null if not a duplicate. example: null addressed_by_rule_id: type: - integer - 'null' description: ID of the rule that addresses this comment. Set when triage_status is addressed_by. Null otherwise. example: null triage_set_by_id: type: - integer - 'null' description: ID of the user who last changed the triage status. Null if still pending. example: null name: type: - string - 'null' description: Display name of the review author (delegated from User). example: Demo Viewer author_name: type: - string - 'null' description: Display name of the review author (explicit field, same value as name). example: Demo Viewer triager_display_name: type: - string - 'null' description: Display name of the user who triaged this comment. Null if not yet triaged. Uses ImportedAttribution resolution (DB user name → imported name → imported email). example: null triager_imported: type: boolean description: Whether the triager attribution came from an import (no matching DB user). example: false adjudicator_display_name: type: - string - 'null' description: Display name of the user who adjudicated this comment. Null if not yet adjudicated. example: null adjudicator_imported: type: boolean description: Whether the adjudicator attribution came from an import. example: false commenter_display_name: type: - string - 'null' description: Display name of the comment author. Uses ImportedAttribution resolution. example: Demo Viewer commenter_imported: type: boolean description: Whether the commenter attribution came from an import. example: false commentable_type: type: - string - 'null' description: Polymorphic type — BaseRule for rule-scoped, Component for component-scoped. example: BaseRule responses_count: type: integer description: Number of direct replies to this review. example: 0 rule_displayed_name: type: - string - 'null' description: Human-readable rule label (PREFIX-RULE_ID). Populated when the serializer is called with rule_names option. Null otherwise. example: PHOS-03-000001 author_email: type: - string - 'null' format: email description: Author's email. Only present when include_email option is true (admin-tier surfaces). Null or absent for public endpoints. example: null commenter_email: type: - string - 'null' format: email description: Commenter's email (same as author_email but follows the commenter attribution naming convention). Only present when include_email option is true. Null for imported reviews with no matching DB user. example: null reactions: type: object description: Aggregate reaction counts and current user's reaction for this review. required: - up - down properties: up: type: integer description: Number of upvote reactions. example: 1 down: type: integer description: Number of downvote reactions. example: 0 mine: type: - string - 'null' description: The current user's reaction type (up or down). Null if no active reaction. example: null AdditionalAnswerSummary: description: Answer to an additional question on a component rule. type: object required: - id - additional_question_id additionalProperties: false properties: id: type: integer description: Unique answer identifier. example: 10 additional_question_id: type: integer description: ID of the question this answers. example: 3 answer: type: - string - 'null' description: The answer text provided by the author. example: Yes, this applies to all container runtime environments. SrgRuleSummary: description: SRG rule — the original SRG requirement that a component rule implements. type: object required: - id - rule_id - title additionalProperties: false properties: id: type: integer description: Unique SRG rule identifier. example: 500 rule_id: type: string description: DISA rule identifier (e.g., SV-222xxx_rule). example: SV-222396r857506_rule title: type: string description: Requirement title. example: The container platform must enforce approved authorizations for access. version: type: - string - 'null' description: SRG version identifier. example: CNTR-00-000050 rule_severity: type: - string - 'null' description: Severity level. enum: - low - medium - high example: medium rule_weight: type: - string - 'null' description: Rule weight for scoring. example: '10.0' ident: type: - string - 'null' description: CCI identifiers (comma-separated). example: CCI-000213 ident_system: type: - string - 'null' description: Identifier system URI. example: http://cyber.mil/cci fixtext: type: - string - 'null' description: Fix text describing how to remediate. example: Configure the container platform to enforce approved authorizations... fixtext_fixref: type: - string - 'null' description: Fix reference identifier. example: F-25073r857505_fix fix_id: type: - string - 'null' description: Fix identifier. example: F-25073r857505_fix inspec_control_body: type: - string - 'null' description: InSpec control Ruby source code. example: null inspec_control_file: type: - string - 'null' description: InSpec control file path. example: null inspec_control_body_lang: type: - string - 'null' description: Language of the InSpec control body (usually ruby). example: null inspec_control_file_lang: type: - string - 'null' description: Language of the InSpec control file. example: null vuln_id: type: - string - 'null' description: Vulnerability identifier (V-number). example: V-222396 legacy_ids: type: - string - 'null' description: Legacy rule identifiers from previous STIG versions (comma-separated string). example: SV-42474, V-32157 rule_descriptions_attributes: type: array description: Rule description records. items: $ref: '#/components/schemas/RuleDescriptionSummary' disa_rule_descriptions_attributes: type: array description: DISA rule description records (vuln discussion, mitigations, etc.). items: $ref: '#/components/schemas/DisaRuleDescription' checks_attributes: type: array description: Check content records. items: $ref: '#/components/schemas/CheckSummary' RuleEditorResponse: description: Full rule for the editing form. Serialized by RuleBlueprint :editor view. Includes viewer fields (text content, nested associations) plus editor-only fields (InSpec, reviews, additional answers, SRG source data). 38 total fields. Used by GET /rules/:id, GET /components/:id/rules, and nested inside ComponentEditorResponse. allOf: - $ref: '#/components/schemas/RuleSummary' - type: object required: - satisfies - satisfied_by properties: rule_weight: type: - string - 'null' description: Rule weight for DISA scoring. example: '10.0' fixtext: type: - string - 'null' description: Remediation instructions. example: Configure the operating system to provide automated mechanisms... fixtext_fixref: type: - string - 'null' description: Fix reference identifier. example: F-3716r557030_fix ident: type: - string - 'null' description: CCI identifiers (comma-separated). example: CCI-000015 ident_system: type: - string - 'null' description: Identifier system URI. example: http://cyber.mil/cci vendor_comments: type: - string - 'null' description: Vendor-provided implementation notes. example: null vuln_id: type: - string - 'null' description: Vulnerability identifier (V-number). example: null legacy_ids: type: - string - 'null' description: Legacy rule identifiers (comma-separated string). example: V-56571, SV-70831 component_id: type: integer description: ID of the component this rule belongs to. example: 1 status_justification: type: - string - 'null' description: Justification text for NA or DNM status. example: null artifact_description: type: - string - 'null' description: Description of compliance evidence artifacts. example: null locked_fields: type: object description: Map of section names to locked state. Empty object means no sections locked. additionalProperties: type: boolean example: {} nist_control_family: type: - string - 'null' description: NIST SP 800-53 control family mapping. example: AC-2 (1) srg_id: type: - string - 'null' description: SRG requirement version this rule implements. example: SRG-OS-000001-GPOS-00001 inspec_control_body: type: - string - 'null' description: InSpec control Ruby source code. example: null inspec_control_file: type: - string - 'null' description: InSpec control file path. example: null inspec_control_body_lang: type: - string - 'null' description: Language of the InSpec control body. example: ruby inspec_control_file_lang: type: - string - 'null' description: Language of the InSpec control file. example: ruby fix_id: type: - string - 'null' description: Fix identifier. example: F-3716r557030_fix disa_rule_descriptions_attributes: type: array description: DISA rule description records. items: $ref: '#/components/schemas/DisaRuleDescription' checks_attributes: type: array description: Check content records. items: $ref: '#/components/schemas/CheckSummary' satisfies: type: array description: Rules that this rule satisfies (child-to-parent relationships). items: $ref: '#/components/schemas/SatisfactionSummary' satisfied_by: type: array description: Rules that satisfy this rule (parent-to-child relationships). items: $ref: '#/components/schemas/SatisfiedBySummary' histories: type: array description: Audit trail entries for this rule, ordered by creation time. Present only when a single rule is requested. The trail cannot be fetched for a whole collection in one query, so a component response omits it for every rule and callers read it from the per-rule endpoint for the one being shown. items: $ref: '#/components/schemas/AuditEntry' rule_descriptions_attributes: type: array description: Raw rule description records. items: $ref: '#/components/schemas/RuleDescriptionSummary' reviews: type: array description: Review actions on this rule (comments, approvals, etc.). items: $ref: '#/components/schemas/ReviewSummary' additional_answers_attributes: type: array description: Answers to component-level additional questions. items: $ref: '#/components/schemas/AdditionalAnswerSummary' srg_rule_attributes: description: Source SRG rule data (the baseline requirement this rule implements). Null if no SRG rule linked. oneOf: - $ref: '#/components/schemas/SrgRuleSummary' - type: 'null' srg_info: type: - object - 'null' description: SRG version metadata. properties: version: type: - string - 'null' example: V2R4 AuthoredSrgRuleEditorResponse: description: 'A component-authored SRG requirement for the editing form. Shares the common requirement surface with STIG rules — status, locking, reviews, audit history, content — but its status vocabulary is the three-value SRG set, and it carries none of the STIG-only surfaces: no satisfies/satisfied_by, no srg_rule_attributes, no additional answers, no InSpec fields. Lineage is the portable derived_from_version identifier.' type: object required: - id - rule_id - locked - srg_id - derived_from_version additionalProperties: false properties: id: type: integer description: Unique requirement identifier. example: 10633 rule_id: type: string description: Six-digit zero-padded requirement number combined with the component prefix to form the displayed ID. example: '000001' title: type: - string - 'null' description: Title of the requirement. Null if not yet authored. example: The container platform must enforce approved authorizations. version: type: - string - 'null' description: Requirement version identifier. Minted at release for authored requirements. example: null status: type: - string - 'null' description: Applicability status in the SRG authoring vocabulary. enum: - Not Yet Determined - Applicable - Not Applicable - null example: Applicable rule_severity: type: - string - 'null' description: DISA severity level. enum: - low - medium - high - null example: medium locked: type: boolean description: Whether the requirement is locked from further edits. example: false review_requestor_id: type: - integer - 'null' description: ID of the user who requested review. Null if no review requested. example: null changes_requested: type: boolean description: Whether changes have been requested during review. example: false comment_summary: type: object description: Per-requirement comment counts. required: - open - total additionalProperties: false properties: open: type: integer description: Comments not yet adjudicated, including replies under open parents. example: 1 total: type: integer description: Total comment count across all statuses. example: 1 rule_weight: type: - string - 'null' description: Rule weight for DISA scoring. example: '10.0' fixtext: type: - string - 'null' description: Remediation guidance authored for this requirement. example: Configure the container platform to enforce approved authorizations. fixtext_fixref: type: - string - 'null' description: Fix reference identifier. example: null ident: type: - string - 'null' description: Comma-separated CCI identifiers. example: CCI-000366 ident_system: type: - string - 'null' description: Identifier system URI. example: http://iase.disa.mil/cci vendor_comments: type: - string - 'null' description: Vendor comments. example: null vuln_id: type: - string - 'null' description: Vulnerability identifier. Assigned at release for authored requirements. example: null legacy_ids: type: - string - 'null' description: Comma-separated legacy identifiers. example: null component_id: type: integer description: The SRG-kind component this requirement is authored on. example: 46 status_justification: type: - string - 'null' description: Justification for the chosen status. example: null artifact_description: type: - string - 'null' description: Artifact description. example: null locked_fields: type: object description: Per-section lock map (section name to true). example: {} nist_control_family: type: string description: NIST control families derived from the CCI identifiers. example: CM srg_id: type: - string - 'null' description: The SRG requirement identifier shown by requirement lists (the editor sidebar's SRG ID display) — one kind-agnostic key across document kinds. For an authored requirement this is the row's version value, the same identifier the editor header displays. Null when the row has no requirement identifier yet. example: SRG-APP-000003 derived_from_version: type: - string - 'null' description: Version (SRG-ID) of the core-catalog requirement this authored requirement was derived from. Null for requirements authored from scratch. Always present — it distinguishes authored requirements from STIG rules wherever the two shapes appear in a oneOf. example: SRG-OS-000023 disa_rule_descriptions_attributes: type: array description: DISA rule description records. items: $ref: '#/components/schemas/DisaRuleDescription' checks_attributes: type: array description: Check content records. items: $ref: '#/components/schemas/CheckSummary' rule_descriptions_attributes: type: array description: Raw rule description records. items: $ref: '#/components/schemas/RuleDescriptionSummary' histories: type: array description: Audit trail entries for this requirement, ordered by creation time. Present only when a single requirement is requested. The trail cannot be fetched for a whole collection in one query, so a component response omits it for every requirement and callers read it from the per-requirement endpoint for the one being shown. items: $ref: '#/components/schemas/AuditEntry' reviews: type: array description: Review actions on this requirement (comments, locks, etc.). items: $ref: '#/components/schemas/ReviewSummary' ComponentEditorResponse: description: Full component for the editing page. Serialized by ComponentBlueprint :editor view. 35 total fields including nested rules, memberships, histories, reviews. Used by GET /components/:id (member), GET /components/:id/rules (via index). allOf: - $ref: '#/components/schemas/ComponentSummary' - type: object properties: effective_permissions: type: - string - 'null' description: Current user's role on this component's project (admin, reviewer, author, viewer). Null when user is not a member. System admins always get 'admin'. enum: - admin - reviewer - author - viewer - null example: admin title: type: - string - 'null' description: Full official title of the component. example: Photon OS 3 STIG Readiness Guide description: type: - string - 'null' description: Optional longer description. example: null admin_name: type: - string - 'null' description: Point of contact name. example: Photon OS Maintainer admin_email: type: - string - 'null' format: email description: Point of contact email. example: photon-team@example.org released: type: boolean description: Whether finalized. example: true advanced_fields: type: boolean description: Whether advanced DISA fields are shown in the editor. example: false project_id: type: integer description: ID of the parent project. example: 1 component_id: type: - integer - 'null' description: ID of the source component if this is an overlay. Null for originals. example: null security_requirements_guide_id: type: integer description: ID of the SRG this component is based on. example: 3 memberships_count: type: integer description: Number of direct memberships on this component. example: 0 rules_count: type: integer description: Number of requirement rows in this component — rules for stig-kind components, authored requirements for srg-kind components. example: 203 updated_at: type: string description: Last modified timestamp. Blueprinter format. example: 2026-05-29 15:36:06 UTC created_at: type: string description: Creation timestamp. Blueprinter format. example: 2026-05-19 14:07:48 UTC comment_phase: type: - string - 'null' description: Current comment period phase. enum: - draft - open - closed - null example: open closed_reason: type: - string - 'null' description: Reason the comment period was closed. example: null comment_period_starts_at: type: - string - 'null' description: Start of the public comment period. example: null comment_period_ends_at: type: - string - 'null' description: End of the public comment period. example: null releasable: type: boolean description: Whether all rules meet release criteria. example: false srg_is_latest: type: boolean description: Whether EVERY declared source SRG of the component is at its latest release. A component with any stale parent — including a secondary parent under dual lineage — reports false. example: true srg_latest_version: type: - string - 'null' description: Version string of the newest release available for the first stale parent (primary first, then secondaries). Null when srg_is_latest=true. example: null srg_latest_id: type: - integer - 'null' description: ID of that newest release for linking. Null when srg_is_latest=true. example: null status_counts: description: 'Requirement counts bucketed by the component''s document_type: five STIG buckets or three SRG buckets. The shapes are disjoint and never collapse into one list.' oneOf: - $ref: '#/components/schemas/RulesByStatus' - $ref: '#/components/schemas/SrgRulesByStatus' moved_out_count: type: integer description: Requirements that relocated OUT of this component — a lifecycle fact counted from executed relocation records, never one of the status buckets. Always 0 for stig-kind components. example: 0 additional_questions: type: array description: Component-level custom questions for rule authors. items: type: object rules: type: array description: 'All requirements, shaped by document_type: STIG rule objects for stig components, authored SRG requirement objects for srg components.' items: oneOf: - $ref: '#/components/schemas/RuleEditorResponse' - $ref: '#/components/schemas/AuthoredSrgRuleEditorResponse' reviews: type: array description: Recent reviews (last 20, hand-built hashes with displayed_rule_name). items: type: object histories: type: array description: Audit trail entries (last 50). items: type: object memberships: type: array description: Direct component memberships. items: $ref: '#/components/schemas/MembershipSummary' metadata: type: - object - 'null' description: Component metadata key-value pairs. example: null inherited_memberships: type: array description: Memberships inherited from the parent project. items: $ref: '#/components/schemas/MembershipSummary' ComponentShowResponse: description: Component detail for non-member read-only view. Serialized by ComponentBlueprint :show view. Includes rules (viewer view), reviews, and effective_permissions. allOf: - $ref: '#/components/schemas/ComponentSummary' - type: object properties: effective_permissions: type: - string - 'null' description: Current user's role on this component's project (admin, reviewer, author, viewer). Null when user is not a member. enum: - admin - reviewer - author - viewer - null example: viewer title: type: - string - 'null' description: Full official title of the component. example: Photon OS 3 STIG Readiness Guide description: type: - string - 'null' description: Optional longer description. example: null admin_name: type: - string - 'null' description: Point of contact name. example: Jane Doe admin_email: type: - string - 'null' format: email description: Point of contact email. example: jane@example.com released: type: boolean description: Whether the component has been released. example: false updated_at: type: string description: Last update timestamp. example: 2026-05-28 15:00:00 UTC comment_phase: type: string description: Current comment workflow phase. enum: - open - closed example: open closed_reason: type: - string - 'null' description: Reason for closure (adjudicating or finalized). example: null comment_period_starts_at: type: - string - 'null' description: When the comment period started. example: null comment_period_ends_at: type: - string - 'null' description: When the comment period ends. example: null rules: type: array description: Rules in viewer view. items: type: object reviews: type: array description: Reviews with displayed_rule_name. items: type: object ComponentUpdateInput: description: Partial update for an existing component — every field is optional and only provided attributes change. The authoring profile (document_type) is immutable after creation and is not accepted here. type: object properties: name: type: string description: Human-readable component name. example: Container SRG prefix: type: string description: Short alphanumeric prefix used to construct rule IDs (e.g. CNTR in CNTR-00-000050). example: CNTR version: type: integer description: Version number of the component. example: 1 release: type: integer description: Release number of the component. example: 1 title: type: string description: Full official title of the component. example: Container Platform Security Technical Implementation Guide description: type: string description: Optional longer description of the component scope and purpose. example: STIG guidance for container orchestration platform deployments. released: type: boolean description: Marks the component as released (admin-gated workflow action). example: false admin_name: type: string description: Point-of-contact name. example: Jane Analyst admin_email: type: string description: Point-of-contact email. example: jane.analyst@example.com advanced_fields: type: boolean description: Whether the editor shows the advanced field set for this component. example: false comment_phase: type: string description: Public comment phase for the component. enum: - draft - open - triage - final example: open closed_reason: type: - string - 'null' description: Reason recorded when the comment phase closes. example: null comment_period_starts_at: type: - string - 'null' format: date-time description: Public comment period opening time. example: '2026-07-01T00:00:00Z' comment_period_ends_at: type: - string - 'null' format: date-time description: Public comment period closing time. example: '2026-08-01T00:00:00Z' additional_questions_attributes: type: array description: Nested additional-question definitions (id + _destroy for removal). items: type: object properties: id: type: integer example: 3 name: type: string example: Deployment environment question_type: type: string example: dropdown _destroy: type: boolean example: false options: type: array items: type: string example: - Cloud - On-prem component_metadata_attributes: type: object description: Nested metadata payload; data is a free-form string map. properties: data: type: object additionalProperties: type: string example: Slack Channel ID: C123456 RuleContent: description: Rule content fields for the split-pane triage view, serialized by Component#serialize_rule_content. Present on comment rows only when the include_rule_content query parameter is true and the comment targets a rule (null for component-level comments). type: object additionalProperties: false properties: title: type: - string - 'null' description: Rule title. example: The container platform must use TLS 1.2 or greater for secure communication. rule_severity: type: - string - 'null' description: Rule severity. example: medium status: type: - string - 'null' description: Applicability status of the rule. example: Applicable - Configurable fixtext: type: - string - 'null' description: Fix text content. example: Configure the container platform to use TLS 1.2 or greater. status_justification: type: - string - 'null' description: Justification for the current status. example: TLS configuration is exposed by the platform and must be set by the operator. vendor_comments: type: - string - 'null' description: Vendor comments. example: Verified against platform version 4.12. artifact_description: type: - string - 'null' description: Artifact description. example: Screenshot of the TLS configuration panel. fix_id: type: - string - 'null' description: XCCDF fix identifier. example: F-59616r921424_fix fixtext_fixref: type: - string - 'null' description: XCCDF fixtext reference. example: F-59616r921424_fix version: type: - string - 'null' description: STIG/SRG identifier of the rule (document order key). example: CNTR-00-000050 rule_weight: type: - string - 'null' description: XCCDF rule weight. example: '10.0' ident: type: - string - 'null' description: CCI identifier string. example: CCI-000068 ident_system: type: - string - 'null' description: Identifier system URI. example: http://iase.disa.mil/cci vuln_discussion: type: - string - 'null' description: Vulnerability discussion from the DISA rule description. example: Without cryptographic integrity protections, information can be altered in transit. documentable: type: - boolean - 'null' description: Whether the requirement is documentable. example: false false_positives: type: - string - 'null' description: Known false positives. example: null false_negatives: type: - string - 'null' description: Known false negatives. example: null mitigations_available: type: - boolean - 'null' description: Whether mitigations are available. example: false mitigations: type: - string - 'null' description: Mitigation description. example: null poam_available: type: - boolean - 'null' description: Whether a POA&M is available. example: false poam: type: - string - 'null' description: POA&M description. example: null potential_impacts: type: - string - 'null' description: Potential impacts of applying the fix. example: Legacy clients that only support TLS 1.1 will fail to connect. third_party_tools: type: - string - 'null' description: Third-party tooling notes. example: null mitigation_control: type: - string - 'null' description: Mitigation control description. example: null responsibility: type: - string - 'null' description: Responsible party. example: System Administrator ia_controls: type: - string - 'null' description: IA controls reference. example: null severity_override_guidance: type: - string - 'null' description: Guidance for severity overrides. example: null check_content: type: - string - 'null' description: Check procedure content. example: Review the platform TLS configuration and verify the minimum version is 1.2. locked: type: - boolean - 'null' description: Whether the rule is locked. example: false rule_updated_at: type: - string - 'null' description: ISO 8601 timestamp of the rule's last update, for staleness detection. example: '2026-05-19T16:15:00Z' satisfied_by: type: array description: Parent rules that satisfy this rule. Empty for standalone rules. Powers the satisfied-by indicator in the triage rule panel. items: type: object additionalProperties: false required: - id - rule_id - component_prefix properties: id: type: integer description: Parent rule database identifier. example: 1901 rule_id: type: string description: Parent rule identifier within the component. example: '000020' component_prefix: type: string description: Component prefix used to build the displayed name. example: CNTR-00 CommentRow: description: A single comment row in the triage comment listing. Serialized by CommentQueryService#serialize_rows — NOT by ReviewBlueprint. This is a hand-built hash with triage attribution, grouping, and rule context fields. type: object required: - id - commentable_type - comment - created_at - triage_status - responses_count - reactions additionalProperties: false properties: id: type: integer description: Unique review/comment identifier. example: 26 rule_id: type: - integer - 'null' description: ID of the rule this comment is attached to. Null for component-level comments. example: 1823 rule_displayed_name: type: - string - 'null' description: Human-readable rule identifier (PREFIX-rule_id). Null or "(component)" for component-level comments. example: PHOS-03-000038 commentable_type: type: string description: Polymorphic type indicating whether the comment targets a rule or a component. enum: - BaseRule - Component example: BaseRule section: type: - string - 'null' description: Rule section the comment applies to (e.g. fixtext, check_content, vuln_discussion). Null for general or component-level comments. example: null author_name: type: - string - 'null' description: Display name of the comment author (from commenter_display_name). example: Demo Viewer author_email: type: - string - 'null' format: email description: Email address of the comment author. example: viewer@example.org comment: type: string description: The comment text content. example: FYI we already shipped this in our internal hardening guide. created_at: type: string description: Timestamp when the comment was created. example: 2026-05-19 14:08:18 UTC triage_status: type: - string - 'null' description: Current triage disposition of the comment. enum: - pending - concur - concur_with_comment - non_concur - duplicate - informational - needs_clarification - withdrawn - addressed_by - null example: informational triage_set_at: type: - string - 'null' description: Timestamp when the triage status was last changed. Null if still pending. example: 2026-05-19 14:08:18 UTC adjudicated_at: type: - string - 'null' description: Timestamp when the comment reached a terminal triage state. Null if not yet adjudicated. example: 2026-05-19 14:08:18 UTC duplicate_of_review_id: type: - integer - 'null' description: ID of the review this is marked as a duplicate of. Null if not a duplicate. example: null addressed_by_rule_id: type: - integer - 'null' description: ID of the rule that addresses this comment (for addressed_by triage status). Null otherwise. example: null srg_info: type: - object - 'null' description: SRG baseline metadata for the comment's component — title, version, and whether it's the latest available. properties: title: type: string description: Full title of the SRG. example: General Purpose Operating System Security Requirements Guide version: type: string description: SRG version in DISA V{major}R{minor} format. example: V3R3 is_latest: type: boolean description: Whether this SRG version is that SRG's latest available release. Green dot = true, yellow dot = false. example: true addressed_by_rule_name: type: - string - 'null' description: Display name of the rule that addresses this comment. Null if not addressed_by. example: null triager_display_name: type: - string - 'null' description: Display name of the user who triaged this comment. Uses ImportedAttribution resolution. example: Demo Author triager_imported: type: boolean description: Whether the triager attribution came from an import (no matching DB user). example: false adjudicator_display_name: type: - string - 'null' description: Display name of the user who adjudicated this comment. example: Demo Author adjudicator_imported: type: boolean description: Whether the adjudicator attribution came from an import. example: false commenter_display_name: type: - string - 'null' description: Display name of the comment author. Uses ImportedAttribution resolution. example: Demo Viewer commenter_imported: type: boolean description: Whether the commenter attribution came from an import. example: false responses_count: type: integer description: Number of threaded replies to this comment. example: 0 reactions: type: object description: Aggregate reaction counts for this comment (no mine field — unlike ReviewSummary). required: - up - down properties: up: type: integer description: Number of upvote reactions. example: 0 down: type: integer description: Number of downvote reactions. example: 0 updated_at: type: string description: Timestamp when the comment was last modified. example: 2026-05-19 14:08:18 UTC rule_status: type: - string - 'null' description: Current applicability status of the rule this comment is on. Null for component-level comments. example: Not Yet Determined parent_rule_displayed_name: type: - string - 'null' description: Display name of the parent rule (if this rule is a child via satisfies relationship). Null if no parent. example: null group_rule_displayed_name: type: - string - 'null' description: Grouping key — parent_rule_displayed_name if present, otherwise rule_displayed_name. Used for by-rule grouping in the triage table. example: PHOS-03-000038 rule_content: description: Rule content for the split-pane triage view. Present only when the include_rule_content query parameter is true; null for component-level comments. oneOf: - $ref: '#/components/schemas/RuleContent' - type: 'null' PaginatedComments: description: Paginated list of comments with pagination metadata and triage status counts. type: object required: - rows - pagination - status_counts properties: rows: type: array description: Comment rows for the current page. items: $ref: '#/components/schemas/CommentRow' pagination: type: object description: Pagination metadata for the comment listing. required: - page - per_page - total - total_comments properties: page: type: integer description: Current page number (1-based). example: 1 per_page: type: integer description: Number of comments per page. example: 25 total: type: integer description: Total number of pages available. example: 4 total_comments: type: integer description: Total number of comments across all pages. example: 87 status_counts: type: object description: Count of comments grouped by triage status. additionalProperties: type: integer example: pending: 12 concur: 45 non_concur: 8 withdrawn: 3 RuleInput: description: 'The full write surface for a requirement — every field the server accepts, shared by the update endpoint and the one-call create body. The endpoint serves both document kinds. Per-kind behavior is noted on the fields that carry it: the status vocabulary is per-kind, and the STIG-only nested attributes (additional_answers_attributes) are dropped server-side when the target is an authored SRG requirement. Nested attributes follow Rails semantics — include id to update an existing record, omit id to create one, send _destroy true to remove (where accepted); at one-call creation ids and _destroy are stripped server-side.' type: object properties: status: type: string description: Applicability status. The accepted vocabulary depends on the parent component's document_type — STIG rules accept Not Yet Determined, Applicable - Configurable, Applicable - Inherently Meets, Applicable - Does Not Meet, and Not Applicable; authored SRG requirements accept Not Yet Determined, Applicable, and Not Applicable. A value outside the target's vocabulary returns 422. enum: - Not Yet Determined - Applicable - Configurable - Applicable - Inherently Meets - Applicable - Does Not Meet - Applicable - Not Applicable example: Applicable - Configurable status_justification: type: string description: Justification for the status decision. For an authored SRG requirement the server requires it whenever status is Not Applicable (422 otherwise) — the justification records the decision and is excluded from the released catalog copy. example: The platform provides no wireless interfaces to configure. title: type: string description: Title of the security control. example: The container platform must enforce approved authorizations for access. artifact_description: type: string description: Description of artifacts or evidence supporting the rule implementation. example: Screenshot of the container platform access control configuration panel. vendor_comments: type: string description: Vendor-provided comments or implementation notes for this rule. example: This requirement is met by default when using the recommended container runtime configuration. rule_severity: type: string description: Severity category (maps to DISA CAT III / CAT II / CAT I). A value outside the accepted list returns 422. enum: - low - medium - high example: medium rule_weight: type: string description: Rule weight for DISA scoring. example: '10.0' version: type: string description: SRG requirement version identifier mapping this rule to its SRG source. example: SRG-OS-000001-GPOS-00001 ident: type: string description: CCI identifiers (comma-separated). example: CCI-000015 ident_system: type: string description: Identifier system URI for the ident value. Server default is http://iase.disa.mil/cci when never set. example: http://cyber.mil/cci fixtext: type: string description: Remediation instructions describing how to fix a non-compliant finding. example: Configure the container platform to enforce approved authorizations for logical access. fix_id: type: string description: Fix identifier. example: F-3716r557030_fix fixtext_fixref: type: string description: Fix reference identifier linking the fixtext to its fix element. example: F-3716r557030_fix audit_comment: type: string description: Free-text comment recorded on the audit-trail entry for this change. Not stored on the requirement itself — it annotates the history row that documents who changed what and why. example: Adjusted severity per authorizing official direction. inspec_control_body: type: string description: 'InSpec control Ruby source code. InSpec is a stig-kind surface: the server accepts this field on an authored SRG requirement but no read surface returns it for that kind — sending it there writes data nothing serves back.' example: |- control 'CNTR-00-000050' do impact 0.5 end inspec_control_file: type: string description: InSpec control file path. Stig-kind surface — same write/read asymmetry on authored SRG requirements as inspec_control_body. example: controls/CNTR-00-000050.rb inspec_control_body_lang: type: string description: Language of the InSpec control body. Server default is ruby. Stig-kind surface — same write/read asymmetry on authored SRG requirements as inspec_control_body. example: ruby inspec_control_file_lang: type: string description: Language of the InSpec control file. Server default is ruby. Stig-kind surface — same write/read asymmetry on authored SRG requirements as inspec_control_body. example: ruby checks_attributes: type: array description: Check content records (the XCCDF check element). Rails nested attributes — id updates, no id creates, _destroy true removes. items: type: object properties: id: type: integer description: Existing check record to update. Omit to create a new one. example: 311 system: type: string description: Check system identifier. example: C-Container Platform content_ref_name: type: string description: Name of the referenced check content document. example: M content_ref_href: type: string description: Href of the referenced check content document. example: DPMS_XCCDF_Benchmark_Container_Platform_SRG.xml content: type: string description: The check procedure text. example: Review the container platform configuration to verify approved authorizations are enforced. _destroy: type: boolean description: Send true to delete this check record. example: false rule_descriptions_attributes: type: array description: Plain rule description records. Rails nested attributes — id updates, no id creates, _destroy true removes. items: type: object properties: id: type: integer description: Existing description record to update. Omit to create a new one. example: 154 description: type: string description: The description text. example: Enforcing approved authorizations limits lateral movement inside the platform. _destroy: type: boolean description: Send true to delete this description record. example: false additional_answers_attributes: type: array description: Answers to the project's additional questions. STIG rules only — dropped server-side when the target is an authored SRG requirement (on update and at one-call creation alike). One answer per question per rule; records are created or updated, never destroyed through this surface (_destroy is not accepted). items: type: object properties: id: type: integer description: Existing answer record to update. Omit to create a new one. example: 87 additional_question_id: type: integer description: The additional question this answer belongs to. example: 3 answer: type: string description: The answer text. example: Yes — enforced through the platform's admission controller. disa_rule_descriptions_attributes: type: array description: DISA rule description records (the vulnerability discussion and DISA metadata block). Rails nested attributes — id updates, no id creates, _destroy true removes. items: type: object properties: id: type: integer description: Existing DISA description record to update. Omit to create a new one. example: 209 vuln_discussion: type: string description: Vulnerability discussion text. example: Unapproved authorizations allow users to exceed their intended privileges. false_positives: type: string description: Known false-positive conditions for the check. example: None identified. false_negatives: type: string description: Known false-negative conditions for the check. example: None identified. documentable: type: boolean description: Whether a finding may be addressed through documentation. example: false mitigations_available: type: boolean description: Whether mitigations are available for this requirement. example: true mitigations: type: string description: Available mitigation description. example: Network segmentation limits exposure until the control is configured. poam_available: type: boolean description: Whether a plan of action and milestones applies. example: false poam: type: string description: Plan of action and milestones text. example: Remediation scheduled for the next maintenance window. severity_override_guidance: type: string description: Guidance for overriding the assigned severity. example: Severity may be lowered when the platform is not internet-facing. potential_impacts: type: string description: Potential operational impacts of applying the fix. example: Existing sessions may be terminated when authorization enforcement is enabled. third_party_tools: type: string description: Third-party tool considerations. example: None. mitigation_control: type: string description: Mitigation control description. example: Compensating access controls at the ingress proxy. responsibility: type: string description: Responsible party for the requirement. example: System Administrator ia_controls: type: string description: Legacy IA control mapping. example: ECAN-1 _destroy: type: boolean description: Send true to delete this DISA description record. example: false RuleCreateResponse: description: 'Response from requirement creation. Toast notification plus the created row under the "data" key, shaped by the parent component''s document_type: a STIG rule or an authored SRG requirement.' type: object required: - toast - data properties: toast: $ref: '#/components/schemas/ToastObject' data: oneOf: - $ref: '#/components/schemas/RuleEditorResponse' - $ref: '#/components/schemas/AuthoredSrgRuleEditorResponse' RulePickerResponse: description: Lightweight rule for picker dropdowns. Serialized by RuleBlueprint :picker view. Extends RuleSummary defaults with displayed_name and satisfaction relationships. 13 total fields. allOf: - $ref: '#/components/schemas/RuleSummary' - type: object required: - displayed_name - satisfies - satisfied_by properties: displayed_name: type: string description: Human-readable rule identifier (PREFIX-rule_id). example: PHOS-03-000001 satisfies: type: array description: Rules that this rule satisfies. items: $ref: '#/components/schemas/SatisfactionSummary' satisfied_by: type: array description: Rules that satisfy this rule. items: $ref: '#/components/schemas/SatisfiedBySummary' AuthoredSrgRulePickerResponse: description: 'A component-authored SRG requirement for picker dropdowns. Serialized by AuthoredSrgRuleBlueprint :picker view — the default requirement fields plus displayed_name. Carries no satisfaction relationships: authored requirements have no satisfies graph, and the keys are omitted entirely rather than sent empty. The closed property set keeps this shape disjoint from RulePickerResponse wherever the two appear in a oneOf.' type: object required: - id - rule_id - locked - displayed_name additionalProperties: false properties: id: type: integer description: Unique requirement identifier. example: 10633 rule_id: type: string description: Six-digit zero-padded requirement number combined with the component prefix to form the displayed ID. example: '000001' title: type: - string - 'null' description: Title of the requirement. Null if not yet authored. example: The container platform must enforce approved authorizations. version: type: - string - 'null' description: Requirement version identifier. Minted at release for authored requirements. example: null status: type: - string - 'null' description: Applicability status in the SRG authoring vocabulary. enum: - Not Yet Determined - Applicable - Not Applicable - null example: Applicable rule_severity: type: - string - 'null' description: DISA severity level. enum: - low - medium - high - null example: medium locked: type: boolean description: Whether the requirement is locked from further edits. example: false review_requestor_id: type: - integer - 'null' description: ID of the user who requested review. Null if no review requested. example: null changes_requested: type: boolean description: Whether changes have been requested during review. example: false comment_summary: type: object description: Per-requirement comment counts. required: - open - total additionalProperties: false properties: open: type: integer description: Comments not yet adjudicated, including replies under open parents. example: 0 total: type: integer description: Total comment count across all statuses. example: 0 displayed_name: type: string description: Component-scoped display name (PREFIX-rule_id). example: RCPK-00-000001 RuleBasicFields: description: Lightweight rule snapshot used for version-to-version diff comparisons. Produced by Rule#basic_fields. Contains only the fields needed to detect content changes between component releases. type: object required: - rule_id additionalProperties: false properties: rule_id: type: string description: Six-digit zero-padded rule number. example: '000001' title: type: - string - 'null' description: Rule title. example: The operating system must provide automated mechanisms for account management. vuln_discussion: type: - string - 'null' description: Vulnerability discussion text (from first DISA rule description). example: Without automated mechanisms, account management becomes error-prone... check: type: - string - 'null' description: Check procedure text (exported format from checks). example: Verify the operating system provides automated mechanisms... fix: type: - string - 'null' description: Fix text (exported format). example: Configure the operating system to provide automated mechanisms... HistoryChangeEntry: description: 'A single rule change between two component versions. Part of the component version history diff. The change type determines which fields are present: ''added'' has only diff, ''removed'' has only base, ''updated'' has both.' type: object required: - change additionalProperties: false properties: change: type: string description: Type of change between versions. enum: - added - removed - updated example: updated base: description: Rule content in the previous version. Present for 'removed' and 'updated' changes. $ref: '#/components/schemas/RuleBasicFields' diff: description: Rule content in the new version. Present for 'added' and 'updated' changes. $ref: '#/components/schemas/RuleBasicFields' ComponentReleaseResponse: type: object description: 'Successful release of an SRG component. The component''s requirements are published to the SRG catalog: the catalog entry is shaped exactly like an uploaded SRG (other components can base on it immediately, and is-latest tracks it), and the changelog summarizes what left the document via executed relocations.' required: - toast - catalog_srg - changelog properties: toast: $ref: '#/components/schemas/ToastObject' catalog_srg: type: object description: The catalog entry created by this release. required: - id - srg_id - version - name properties: id: type: integer description: Catalog SecurityRequirementsGuide record id. srg_id: type: string description: The released document's benchmark id — the component name with spaces underscored. example: Container_Best_Practice_SRG version: type: string description: Catalog version string mapped from the component's integer version/release pair. example: V1R1 name: type: string description: Display name composed from the benchmark id and version. example: Container Best Practice SRG - Ver 1, Rel 1 changelog: type: object description: Release changelog content. Removals are the component's executed relocation records — requirements that left this document for another SRG. Storage is not implied; this is the generated content. required: - version - removals - text properties: version: type: string example: V1R1 removals: type: array items: type: object required: - identifier - destination_abbreviation - executed_on properties: identifier: type: string description: The requirement's published identifier (its working display name if it was never minted). example: SRG-OS-000811-CTR-000042 destination_abbreviation: type: string description: The destination SRG's short abbreviation. example: WEB executed_on: type: string format: date example: '2026-07-20' text: type: string description: Plain-text rendering of the changelog. RuleSectionLockResponse: description: Response from section lock/unlock. Toast notification plus the updated rule. Used by PATCH /rules/:id/section_locks and PATCH /rules/:id/bulk_section_locks. type: object required: - rule - toast properties: rule: $ref: '#/components/schemas/RuleEditorResponse' toast: $ref: '#/components/schemas/ToastObject' RequirementRelocationSummary: description: 'A relocation proposal in the per-SRG backlog: the open proposal plus enough source identity to act on it, or a retained non-concur whose rationale communicates the refusal back to the source author. Executed relocation records are immutable history and never served here.' type: object additionalProperties: false required: - id - source_rule_id - target_technology_token - source_displayed_name - component_id properties: id: type: integer description: Relocation record identifier. example: 12 source_rule_id: type: integer description: The authored requirement proposed for relocation. example: 5137 target_technology_token: type: string description: The destination SRG's abbreviation (CTR, GPOS, DB — the SRG-world analogue of a STIG component prefix). example: CTR created_at: type: string description: When the marker was created. Blueprinter format. example: 2026-07-20 15:36:06 UTC source_displayed_name: type: string description: Component-prefixed requirement name of the source. example: CNTR-00-000051 component_id: type: integer description: The source requirement's component. example: 42 component_name: type: - string - 'null' description: Name of the source component. example: Container Platform SRG requested_by_name: type: - string - 'null' description: Who marked the requirement. Null when the account was removed. example: Jane Doe declined_at: type: - string - 'null' description: When the receiving side declined the proposal. Null while the proposal is open. Blueprinter format. example: null adjudication_rationale: type: - string - 'null' description: Why the proposal was declined — required on every decline, shown to the source author. Null while the proposal is open. example: null declined_by_name: type: - string - 'null' description: Who declined the proposal. Null while open or when the account was removed. example: null RelocationDestination: description: 'A destination SRG option for the relocation propose flow: one row per SRG abbreviation across the SRG components the caller can discover. An open (unreleased) component wins the row; released true marks the queued next-release case (proposals wait until the receiving admin creates the next version).' type: object additionalProperties: false required: - token - name - released properties: token: type: string description: The destination SRG's abbreviation — the short code its requirement IDs start with (CTR, GPOS, DB). example: CTR name: type: string description: The component carrying the abbreviation — the open component when one exists, otherwise the latest released one. example: Container Platform SRG released: type: boolean description: True when no open component carries the abbreviation — a proposal queues for the SRG's next release. example: false RequirementRelocationDryRun: description: 'Zero-write preview of executing a relocation: whether the move can run, every reason it cannot, and exactly what would be created and tombstoned.' type: object additionalProperties: false required: - valid - errors - source_displayed_name - would_create - would_tombstone_source properties: valid: type: boolean description: Whether execute would run with these inputs. example: true errors: type: array description: Every reason the move cannot run. Empty when valid. items: type: string example: [] source_displayed_name: type: string description: Component-prefixed name of the source requirement. example: CNTR-00-000051 target_component_id: type: - integer - 'null' description: The destination component. example: 42 target_component_name: type: - string - 'null' description: Name of the destination component. example: Container Platform SRG would_create: type: object additionalProperties: false description: The requirement that execute would create in the target. properties: title: type: - string - 'null' description: Title carried over from the source. example: The application must enforce approved authorizations status: type: - string - 'null' description: Authoring status carried over from the source. example: Applicable rule_id: type: - string - 'null' description: The number the moved requirement would land under — the next in the target component's own sequence (working numbers are local ordinals; identifiers mint at release). example: '000003' derived_from_srg_rule_id: type: - integer - 'null' description: Core-requirement lineage preserved on the move. example: 5137 would_tombstone_source: type: boolean description: Execute soft-deletes the source row — always true. example: true RequirementRelocationAcceptResponse: description: 'Combined response for accepting a relocation proposal: the success toast plus the id of the requirement that landed in the destination component, so the editor can materialize the new row without a page reload.' type: object required: - toast - landed_rule_id additionalProperties: false properties: toast: $ref: '#/components/schemas/ToastObject' landed_rule_id: type: integer description: The requirement created in the destination component. example: 5137 ReviewInput: description: Input fields for creating a review action (comment, approval, review request, or lock) on a rule. type: object required: - action - comment properties: action: type: string description: The review action to perform. Vocabulary and role tiers come from Review::ACTION_PERMISSIONS — comment (viewer+), request_review / revoke_review_request (author+), request_changes / approve (reviewer+), lock_control / unlock_control (admin). enum: - comment - request_review - revoke_review_request - request_changes - approve - lock_control - unlock_control example: comment comment: type: string description: The comment text accompanying this review action. example: The fix text should reference the container runtime configuration file. section: type: - string - 'null' description: Rule section this comment applies to (e.g. fixtext, check_content, vuln_discussion). Null for general comments; component-level comments are always stored section-less. example: fixtext responding_to_review_id: type: integer description: ID of the parent review when creating a threaded reply. example: 43 BulkTriageResponse: description: Response from bulk-triaging multiple reviews at once. Returns the updated reviews and any auto-created response reviews (one per triaged comment if a response_comment was provided). type: object required: - reviews - response_reviews additionalProperties: false properties: reviews: type: array description: The triaged reviews with updated triage_status. items: $ref: '#/components/schemas/ReviewSummary' response_reviews: type: array description: Auto-created response reviews (one per triaged comment when response_comment is provided). Empty array if no response_comment. items: $ref: '#/components/schemas/ReviewSummary' MergeResponse: description: Response from merging duplicate reviews into a single survivor. The survivor absorbs the merged content. Duplicates are marked triage_status=duplicate with duplicate_of_review_id pointing to the survivor. type: object required: - survivor - duplicates additionalProperties: false properties: survivor: description: The surviving review that absorbed the duplicates. $ref: '#/components/schemas/ReviewSummary' duplicates: type: array description: The merged reviews, now marked as duplicates of the survivor. items: $ref: '#/components/schemas/ReviewSummary' ReviewUpdateInput: description: Input for editing an existing comment's text. Editing is allowed only while the comment is still pending triage; lifecycle fields (action, section, triage status) are server-controlled and cannot be changed here. type: object required: - comment additionalProperties: false properties: comment: type: string description: The replacement comment text. example: The fix text should reference the container runtime configuration file. ReviewWrapper: description: 'Standard review mutation response. Wraps a single ReviewSummary in a { review: ... } envelope. Used by update, reopen, withdraw, admin_withdraw, admin_restore, move_to_rule, and section endpoints.' type: object required: - review additionalProperties: false properties: review: $ref: '#/components/schemas/ReviewSummary' TriageResponse: description: Response from triage or adjudicate actions. Contains the updated review and an optional response_review (child comment created atomically when the triager provides a response comment alongside the triage decision). type: object required: - review additionalProperties: false properties: review: $ref: '#/components/schemas/ReviewSummary' response_review: description: Child review created as a response to the decision. Null if no response text was provided. Present when the request includes response_comment (triage) or resolution_comment (adjudicate). oneOf: - $ref: '#/components/schemas/ReviewSummary' - type: 'null' AdminDestroyResponse: description: Response from admin hard-delete of a review. Returns null for the review (confirming deletion) and the destroyed review's ID for frontend cleanup. type: object required: - review - destroyed_id additionalProperties: false properties: review: type: 'null' description: Always null — confirms the review was destroyed. example: null destroyed_id: type: integer description: ID of the destroyed review, for frontend to remove from local state. example: 44 ReactionsSummary: description: Detailed reaction lists showing which users reacted with each type. type: object required: - up - down additionalProperties: false properties: up: type: array description: Users who upvoted. items: type: object required: - name properties: name: type: string description: Display name of the user who upvoted. example: Jane Doe down: type: array description: Users who downvoted. items: type: object required: - name properties: name: type: string description: Display name of the user who downvoted. example: John Smith ReactionToggleResponse: description: Response after toggling a reaction on a comment, returning updated aggregate counts and the current user's reaction. type: object required: - reactions additionalProperties: false properties: reactions: type: object description: Updated reaction state for the comment. required: - up - down - mine properties: up: type: integer description: Total number of upvote reactions. example: 4 down: type: integer description: Total number of downvote reactions. example: 1 mine: type: - string - 'null' description: The current user's reaction type (up or down). Null if the user has no active reaction. example: up MembershipInput: description: Input fields for creating or updating a project or component membership. type: object required: - user_id - role properties: user_id: type: integer description: ID of the user to add or update membership for. example: 42 membership_id: type: integer description: ID of the existing membership record to update. Omit when creating a new membership. example: 15 membership_type: type: string description: Whether this membership is for a project or a component. enum: - Project - Component example: Project role: type: string description: Access role granted to the user (viewer < author < reviewer < admin). enum: - viewer - author - reviewer - admin example: author MembershipUpdateInput: description: Update for an existing membership — the membership is addressed by the URL and only the role may change; user and membership type are fixed at creation. type: object required: - role properties: role: type: string description: Access role granted to the user (viewer < author < reviewer < admin). enum: - viewer - author - reviewer - admin example: reviewer SrgSummary: description: Security Requirements Guide (SRG) listing entry. Serialized by SrgBlueprint (default/index view). SRGs use release_date (not benchmark_date — that is STIGs). type: object required: - id - srg_id - severity_counts - core properties: id: type: integer description: Unique SRG identifier. example: 1 srg_id: type: - string - 'null' description: DISA SRG identifier string. example: Container_Platform_SRG core: type: boolean description: Whether this is a core SRG. Core SRGs are the raw material SRG-kind components derive from; derived (non-core) SRGs are the valid sources for STIG-kind components. Drives the creation-flow source picker's eligibility filtering. example: false name: type: - string - 'null' description: Short name including version and release. example: Container Platform SRG - Ver 2, Rel 4 title: type: - string - 'null' description: Full official title. example: Container Platform Security Requirements Guide version: type: - string - 'null' description: Version string (e.g. V2R4). example: V2R4 release_date: type: - string - 'null' format: date description: Date the SRG was published by DISA. example: '2025-10-28' is_latest: type: boolean description: Whether this is the latest available release of this SRG. example: true latest_available_version: type: - string - 'null' description: Version string of this SRG's latest available release. Null when is_latest=true. example: null latest_available_id: type: - integer - 'null' description: ID of the latest available SRG for linking. Null when is_latest=true. example: null severity_counts: type: object description: Count of rules at each severity level within this SRG. properties: high: type: integer example: 8 medium: type: integer example: 177 low: type: integer example: 3 SrgDetailResponse: description: Full SRG detail with nested rules. Serialized by SrgBlueprint :show view. Extends SrgSummary with srg_rules array. allOf: - $ref: '#/components/schemas/SrgSummary' - type: object properties: srg_rules: type: array description: All rules in this SRG, each with full DISA metadata and check content. items: $ref: '#/components/schemas/SrgRuleSummary' StigSummary: description: Security Technical Implementation Guide (STIG) listing entry. Serialized by StigBlueprint (default/index view). STIGs use benchmark_date (not release_date — that is SRGs). type: object required: - id - stig_id - severity_counts properties: id: type: integer description: Unique STIG identifier. example: 1 stig_id: type: - string - 'null' description: DISA STIG identifier string. example: Application_Security_Development_STIG name: type: - string - 'null' description: Short name including version and release. example: Application Security Development STIG - Ver 6, Rel 4 title: type: - string - 'null' description: Full official title. example: Application Security and Development Security Technical Implementation Guide version: type: - string - 'null' description: Version string (e.g. V6R4). example: V6R4 benchmark_date: type: - string - 'null' format: date description: Date the STIG benchmark was published by DISA. example: '2025-10-01' is_latest: type: boolean description: Whether this is the latest available release of this STIG. example: true latest_available_version: type: - string - 'null' description: Version string of this STIG's latest available release. Null when is_latest=true. example: null latest_available_id: type: - integer - 'null' description: ID of the latest available STIG for linking. Null when is_latest=true. example: null severity_counts: type: object description: Count of rules at each severity level within this STIG. properties: high: type: integer example: 34 medium: type: integer example: 230 low: type: integer example: 22 StigRuleSummary: description: Published STIG rule — a finalized security requirement from a published STIG. type: object required: - id - rule_id - title additionalProperties: false properties: id: type: integer description: Unique STIG rule identifier. example: 600 rule_id: type: string description: DISA rule identifier. example: SV-222396r857506_rule title: type: string description: Requirement title. example: The container platform must enforce approved authorizations for access. version: type: - string - 'null' description: STIG version identifier. example: CNTR-00-000050 rule_severity: type: - string - 'null' enum: - low - medium - high example: medium rule_weight: type: - string - 'null' example: '10.0' ident: type: - string - 'null' description: CCI identifiers (comma-separated). example: CCI-000213 ident_system: type: - string - 'null' example: http://cyber.mil/cci fixtext: type: - string - 'null' description: Fix text describing how to remediate. example: Configure the container platform to enforce approved authorizations... fixtext_fixref: type: - string - 'null' example: F-25073r857505_fix fix_id: type: - string - 'null' example: F-25073r857505_fix srg_id: type: - string - 'null' description: SRG requirement this STIG rule implements. example: SRG-APP-000033-CTR-000095 vuln_id: type: - string - 'null' description: Vulnerability identifier (V-number). example: V-222396 legacy_ids: type: - string - 'null' description: Legacy rule identifiers from previous STIG versions (comma-separated string). example: V-69239, SV-83861 vendor_comments: type: - string - 'null' description: Vendor-provided implementation guidance or additional context. example: This is addressed by the vendor's default configuration. disa_rule_descriptions_attributes: type: array description: DISA rule description records. items: $ref: '#/components/schemas/DisaRuleDescription' checks_attributes: type: array description: Check content records. items: $ref: '#/components/schemas/CheckSummary' StigDetailResponse: description: Full STIG detail with nested rules. Serialized by StigBlueprint :show view. Extends StigSummary with description and stig_rules array. allOf: - $ref: '#/components/schemas/StigSummary' - type: object properties: description: type: - string - 'null' description: Full description of the STIG. example: This Security Technical Implementation Guide is published as a tool to improve the security of Department of Defense information systems. stig_rules: type: array description: All rules in this STIG, each with full DISA metadata and check content. items: $ref: '#/components/schemas/StigRuleSummary' IdentitySummary: description: A linked external identity (provider + uid) for a user account. type: object required: - provider - title properties: id: type: integer description: Unique identity record identifier. example: 7 provider: type: string description: Registry key of the authentication provider (e.g. okta, login_gov, oidc, ldap, github). example: okta email: type: - string - 'null' format: email description: Email address asserted by this provider. For display/audit only — not the link key. example: jane@example.com title: type: string description: Human-facing display name for the provider, from the OIDC registry or titleized fallback. example: Okta last_sign_in_at: type: - string - 'null' description: ISO 8601 timestamp of the most recent sign-in via this identity. Null if never used. example: '2026-06-14T13:29:15Z' can_unlink: type: boolean description: Whether this identity can be unlinked (false when it is the user's only sign-in method). Only present in the profile view. example: true UserSummary: description: Summary of a user account for admin management views. type: object required: - id - email - admin additionalProperties: false properties: id: type: integer description: Unique user identifier. example: 42 name: type: - string - 'null' description: Display name chosen by the user. Null if not yet set. example: Jane Doe email: type: string format: email description: Login email address. example: jane.doe@example.org provider: type: - string - 'null' description: Authentication provider used for this account (local, github, ldap, or oidc). Null for local accounts. example: local admin: type: boolean description: Whether the user has administrator privileges. example: false last_sign_in_at: type: - string - 'null' description: Timestamp of the most recent successful sign-in. Null if the user has never signed in. Blueprinter format. example: 2026-05-28 15:00:00 UTC failed_attempts: type: integer description: Number of consecutive failed login attempts since last successful sign-in. example: 0 locked_at: type: - string - 'null' description: Timestamp when the account was locked due to excessive failed attempts. Null if not locked. Blueprinter format. example: null slack_user_id: type: - string - 'null' description: Slack member ID driving this user's Slack notifications. Settable by the user (profile) and by admins (create/update, audited). Null when not set. example: U0123456789 identities: type: array description: Linked external identities for this user (provider, email, last sign-in). Present in admin and profile views. items: $ref: '#/components/schemas/IdentitySummary' UserToastResponse: description: Combined response containing a toast notification and the updated user. Used by PUT /users/:id, POST /users/:id/lock, POST /users/:id/unlock. type: object required: - toast - user additionalProperties: false properties: toast: $ref: '#/components/schemas/ToastObject' user: $ref: '#/components/schemas/UserSummary' UserCommentRow: description: A single comment row in the user's My Comments listing. Serialized by UsersController#comment_row_for — different shape from CommentRow (component triage listing). Includes project/component context for cross-project navigation but omits triage attribution fields. type: object required: - id - commentable_type - comment - created_at - triage_status - responses_count - reactions additionalProperties: false properties: id: type: integer description: Unique review/comment identifier. example: 29 project_id: type: - integer - 'null' description: ID of the project containing this comment's rule/component. example: 3 project_name: type: - string - 'null' description: Name of the project. example: vSphere 7.0 component_id: type: - integer - 'null' description: ID of the component containing the rule. example: 4 component_name: type: - string - 'null' description: Name of the component. example: Photon OS 3 author_name: type: - string - 'null' description: Display name of the comment author. example: Jane Doe rule_id: type: - integer - 'null' description: ID of the rule this comment is attached to. Null for component-level comments. example: 2397 rule_displayed_name: type: - string - 'null' description: Human-readable rule identifier (PREFIX-rule_id). "(component)" for component-level comments. example: PHOS-03-000039 commentable_type: type: string description: Polymorphic type indicating whether the comment targets a rule or a component. enum: - BaseRule - Component example: BaseRule section: type: - string - 'null' description: Rule section the comment applies to. example: fixtext comment: type: string description: The comment text content. example: 'vSphere 7.0: fix command targets ESXi 6.7 path — should reference 7.0 layout.' created_at: type: string description: Timestamp when the comment was created. Blueprinter format. example: 2026-05-19 14:08:18 UTC triage_status: type: - string - 'null' description: Current triage disposition of the comment. enum: - pending - concur - concur_with_comment - non_concur - duplicate - informational - needs_clarification - withdrawn - addressed_by - null example: pending triage_set_at: type: - string - 'null' description: Timestamp when the triage status was last changed. example: null adjudicated_at: type: - string - 'null' description: Timestamp when the comment reached a terminal triage state. example: null duplicate_of_review_id: type: - integer - 'null' description: ID of the review this is marked as a duplicate of. example: null addressed_by_rule_id: type: - integer - 'null' description: ID of the rule that addresses this comment. example: null srg_info: type: - object - 'null' description: SRG baseline metadata for the comment's component. properties: title: type: string description: Full title of the SRG. example: General Purpose Operating System Security Requirements Guide version: type: string description: SRG version in DISA V{major}R{minor} format. example: V3R3 is_latest: type: boolean description: Whether this SRG version is the latest available. example: true parent_rule_displayed_name: type: - string - 'null' description: Display name of the parent rule if this rule is a child via satisfies. Null if no parent. example: null addressed_by_rule_name: type: - string - 'null' description: Display name of the rule that addresses this comment. example: null latest_activity_at: type: - string - 'null' description: Most recent activity timestamp (triage, adjudication, or reply). example: null responses_count: type: integer description: Number of threaded replies to this comment. example: 0 reactions: type: object description: Aggregate reaction counts with current user's reaction. additionalProperties: false required: - up - down properties: up: type: integer description: Number of upvote reactions. example: 0 down: type: integer description: Number of downvote reactions. example: 0 mine: type: - string - 'null' description: The current user's reaction type. Null if no active reaction. example: null AdminCreateResponse: description: Response from admin user creation. Success includes toast, user, and optional reset_url. Error includes only the toast (no user key). type: object required: - toast properties: toast: $ref: '#/components/schemas/ToastObject' user: description: The created user (present on success, absent on error). $ref: '#/components/schemas/UserSummary' reset_url: type: string format: uri description: One-time password reset URL. Present only when SMTP is unavailable and no password was provided — the admin must deliver this link manually. example: https://vulcan.example.org/users/password/edit?reset_password_token=abc123def456 ResetLinkResponse: description: Response containing a toast notification and a one-time password reset URL for admin-generated resets. type: object required: - toast - reset_url additionalProperties: false properties: toast: $ref: '#/components/schemas/ToastObject' reset_url: type: string format: uri description: One-time password reset URL to share with the user. example: https://vulcan.example.org/users/password/edit?reset_password_token=abc123def456 AccessRequestToastResponse: description: Response from creating or deleting a project access request. The id is the affected access request — newly created on POST, destroyed on DELETE. type: object required: - toast - id additionalProperties: false properties: toast: $ref: '#/components/schemas/ToastObject' id: type: integer description: ID of the affected access request. example: 42 TriageResponseTemplate: description: A reusable response template for triage decisions, scoped to a project. type: object required: - id - name - body properties: id: type: integer description: Unique template identifier. example: 1 name: type: string description: Short name displayed in the template picker dropdown. example: Accept - standard body: type: string description: Markdown response text inserted into the triage response field. example: Concur with the finding as written. No changes needed. created_by_id: type: - integer - 'null' description: ID of the user who created this template. example: 42 created_at: type: string format: date-time description: When the template was created. example: '2026-06-03T01:00:00Z' PersonalAccessTokenSummary: description: A personal access token as seen by its OWNER (GET /personal_access_tokens). Carries no owner identity — administrators listing another user's tokens get PersonalAccessTokenAdminSummary instead. The secret itself is returned only once, at creation, and is never retrievable here. type: object required: - id - name - token_prefix - scopes - created_at additionalProperties: false properties: id: type: integer description: Unique token identifier. example: 1 name: type: string description: Human-readable label the owner gave the token. example: CI Pipeline token_prefix: type: string example: vulcan_a description: First 8 characters of the token for identification. The full token is never stored or returned after creation. scopes: type: array description: Capabilities granted to the token. items: type: string enum: - read - write - admin example: - read - write expires_at: type: - string - 'null' example: '2026-08-30' description: ISO 8601 date. Maximum 365 days from creation. Null means no expiry (warned in UI). last_used_at: type: - string - 'null' example: 2026-05-30 14:22:01 UTC description: Timestamp of last API request using this token. Updated at most once per minute. revoked_at: type: - string - 'null' example: null description: Null when active. Timestamp when revoked (soft-delete preserves audit trail). allowed_ips: type: - array - 'null' items: type: string example: - 10.0.0.0/8 - 192.168.1.0/24 description: CIDR allowlist. Null or empty means any IP allowed. created_at: type: string description: When the token was created. Blueprinter format. example: 2026-05-30 10:00:00 UTC PersonalAccessTokenAdminSummary: description: 'A personal access token as seen by an administrator listing ANOTHER user''s tokens (GET /personal_access_tokens?user_id=). Adds the owner''s identity to the standard summary so oversight is attributable. Read-only oversight: the secret is never included here or anywhere after creation, and no endpoint lets an administrator mint a token on this owner''s account.' type: object required: - id - name - token_prefix - scopes - created_at - user_id additionalProperties: false properties: id: type: integer description: Unique token identifier. example: 1 name: type: string description: Human-readable label the owner gave the token. example: CI Pipeline token_prefix: type: string description: First 8 characters of the token for identification. The full token is never stored or returned after creation. example: vulcan_a scopes: type: array description: Capabilities granted to the token. items: type: string enum: - read - write - admin example: - read - write expires_at: type: - string - 'null' description: ISO 8601 date. Maximum 365 days from creation. Null means no expiry (warned in UI). example: '2026-08-30' last_used_at: type: - string - 'null' description: Timestamp of last API request using this token. Updated at most once per minute. example: 2026-05-30 14:22:01 UTC revoked_at: type: - string - 'null' description: Null when active. Timestamp when revoked (soft-delete preserves audit trail). example: null allowed_ips: type: - array - 'null' description: CIDR allowlist. Null or empty means any IP allowed. items: type: string example: - 10.0.0.0/8 - 192.168.1.0/24 created_at: type: string description: When the token was created. Blueprinter format. example: 2026-05-30 10:00:00 UTC user_id: type: integer description: Numeric id of the token's owner. example: 42 user_name: type: - string - 'null' description: Display name of the token's owner. Null if the owner has not set one. example: Jane Doe user_email: type: - string - 'null' format: email description: Email address of the token's owner. example: jane@example.com PersonalAccessTokenCreateResponse: type: object required: - token - personal_access_token additionalProperties: false description: Returned only on token creation. The `token` field contains the raw token value — this is the ONLY time it is ever returned. After this response, only the SHA-256 digest is stored server-side. properties: token: type: string example: vulcan_a8BfDtSxd28fDXCuYaKxkeToqqJsmq5PekL6 description: The raw API token. Show to user once, then discard. Never stored or returned again. personal_access_token: $ref: '#/components/schemas/PersonalAccessTokenSummary' responses: Unauthorized: description: Authentication required (RFC 9457 problem details). Either no API token and no signed-in session, or an Authorization header token that is revoked, expired, or mistyped. The `type` URI names which case applied and `how_to_authenticate` spells out both supported methods. content: application/problem+json: schema: type: object additionalProperties: false required: - type - title - status - detail properties: type: type: string description: Stable machine identifier for the error class — a URI reference anchoring into the live API docs. example: /docs/api/errors#not_authenticated title: type: string description: Short human summary of the error class. example: Not authenticated status: type: integer description: HTTP status code, repeated in the body. example: 401 detail: type: string description: Occurrence-specific human explanation of why. example: This request included no API token and no valid signed-in session. If you were signed in, the session may have timed out, been signed out, or ended because this account signed in from another location. how_to_authenticate: type: object additionalProperties: false description: Both supported authentication methods (extension member). properties: session: type: string description: How to authenticate with a browser session. example: Sign in through the web UI (/users/sign_in) and retry with the session cookie. token: type: string description: How to authenticate with a personal access token. example: 'Create a personal access token (your profile page, or POST /personal_access_tokens) and send it in the request header: Authorization: Token .' examples: not_authenticated: summary: No API token and no signed-in session value: type: /docs/api/errors#not_authenticated title: Not authenticated status: 401 detail: This request included no API token and no valid signed-in session. If you were signed in, the session may have timed out, been signed out, or ended because this account signed in from another location. how_to_authenticate: session: Sign in through the web UI (/users/sign_in) and retry with the session cookie. token: 'Create a personal access token (your profile page, or POST /personal_access_tokens) and send it in the request header: Authorization: Token .' invalid_token: summary: Authorization header token revoked, expired, or mistyped value: type: /docs/api/errors#invalid_token title: Invalid or expired API token status: 401 detail: The Authorization header carried a token that does not match any active personal access token. It may be revoked, expired, or mistyped. how_to_authenticate: session: Sign in through the web UI (/users/sign_in) and retry with the session cookie. token: 'Create a personal access token (your profile page, or POST /personal_access_tokens) and send it in the request header: Authorization: Token .' session_superseded: summary: Session ended because the account signed in from another location value: type: /docs/api/errors#session_superseded title: Session ended — signed in elsewhere status: 401 detail: You were signed out because this account signed in from another location. Only one active session per account is allowed at a time. how_to_authenticate: session: Sign in through the web UI (/users/sign_in) and retry with the session cookie. token: 'Create a personal access token (your profile page, or POST /personal_access_tokens) and send it in the request header: Authorization: Token .' session_timed_out: summary: Session expired after inactivity value: type: /docs/api/errors#session_timed_out title: Session timed out status: 401 detail: Your session timed out after a period of inactivity. Sign in again to continue. how_to_authenticate: session: Sign in through the web UI (/users/sign_in) and retry with the session cookie. token: 'Create a personal access token (your profile page, or POST /personal_access_tokens) and send it in the request header: Authorization: Token .' ErrorResponse: description: Catch-all 4XX error response. Domain and validation feedback arrives as the canonical toast object (application/json); auth and infrastructure errors (401/403/404/400) arrive as RFC 9457 problem details (application/problem+json) with a stable `type` URI, `title`, `status`, and `detail`. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message (domain errors). example: No SRG IDs found in spreadsheet toast: type: object description: Optional toast notification with structured error details. properties: title: type: string description: Short error summary. example: Validation failed. message: type: array description: Detail lines describing what went wrong. items: type: string example: - Name can't be blank. - Prefix is too short (minimum is 2 characters). variant: type: string description: Bootstrap alert variant (always danger for errors). example: danger examples: validation_error: summary: Validation failure value: toast: title: Validation failed. message: - Name can't be blank. variant: danger application/problem+json: schema: type: object required: - type - title - status - detail properties: type: type: string description: Stable machine identifier for the error class — a URI reference anchoring into the live API docs. example: /docs/api/errors#not_found title: type: string description: Short human summary of the error class. example: Not found status: type: integer description: HTTP status code, repeated in the body. example: 404 detail: type: string description: Occurrence-specific human explanation. example: The requested resource could not be found. how_to_authenticate: type: object description: Extension member on 401s — both authentication methods. admins: type: array description: Extension member on permission denials — who to ask. items: type: object toast: type: object description: Legacy toast extension on permission denials. examples: not_found: summary: Resource not found value: type: /docs/api/errors#not_found title: Not found status: 404 detail: The requested resource could not be found. NotFound: description: Resource not found (RFC 9457 problem details). The body is identical for a truly nonexistent resource and one the caller may not learn exists. content: application/problem+json: schema: type: object additionalProperties: false required: - type - title - status - detail properties: type: type: string description: Stable machine identifier for the error class — a URI reference anchoring into the live API docs. example: /docs/api/errors#not_found title: type: string description: Short human summary of the error class. example: Not found status: type: integer description: HTTP status code, repeated in the body. example: 404 detail: type: string description: Occurrence-specific human explanation. example: The requested resource could not be found. examples: not_found: summary: No such resource is reachable by this request value: type: /docs/api/errors#not_found title: Not found status: 404 detail: The requested resource could not be found. Forbidden: description: Insufficient permissions (RFC 9457 problem details). The `type` URI names the denial class; permission denials carry the project `admins` to ask for access, plus a legacy `toast` extension kept until every consumer reads the problem fields directly. content: application/problem+json: schema: type: object additionalProperties: false required: - type - title - status - detail properties: type: type: string description: Stable machine identifier for the error class — a URI reference anchoring into the live API docs. example: /docs/api/errors#permission_denied title: type: string description: Short human summary of the error class. example: Permission denied status: type: integer description: HTTP status code, repeated in the body. example: 403 detail: type: string description: Occurrence-specific human explanation of why. example: You are not authorized to perform viewer actions on this project admins: type: array description: Project admin contacts to ask for access (extension member, present on permission denials when a project or component is in scope; empty otherwise). items: type: object additionalProperties: false required: - name - email properties: name: type: string description: Admin display name. example: Alice Admin email: type: string format: email description: Admin contact email. example: alice@example.com toast: type: object additionalProperties: false description: Legacy toast extension for older consumers (permission denials only). properties: title: type: string description: Toast heading. example: Not Authorized. message: type: array description: Toast body lines. items: type: string example: - You are not authorized to perform viewer actions on this project variant: type: string description: Bootstrap alert variant. example: danger examples: permission_denied: summary: Authenticated but lacking the required project capability value: type: /docs/api/errors#permission_denied title: Permission denied status: 403 detail: You are not authorized to perform viewer actions on this project admins: - name: Alice Admin email: alice@example.com toast: title: Not Authorized. message: - You are not authorized to perform viewer actions on this project variant: danger insufficient_token_scope: summary: Token lacks the scope this request requires value: type: /docs/api/errors#insufficient_token_scope title: Insufficient token scope status: 403 detail: This request requires the write scope, and the token does not grant it. ip_not_allowed: summary: Request IP outside the token allowlist value: type: /docs/api/errors#ip_not_allowed title: IP address not allowed status: 403 detail: The request came from an IP address outside this token's allowlist. UnprocessableEntity: description: Validation errors prevented the request from being processed. content: application/json: schema: type: object properties: toast: type: object description: Toast notification containing validation error details. properties: title: type: string description: Short error summary. example: Unable to save changes. message: type: array description: Specific validation error messages. items: type: string example: - Name can't be blank. - Prefix format is invalid. variant: type: string description: Bootstrap alert variant (always danger for validation errors). example: danger examples: validation_failure: summary: Component creation with missing fields value: toast: title: Unable to save changes. message: - Name can't be blank. - Prefix format is invalid. variant: danger parameters: SearchQuery: name: q in: query required: true description: Search query string (minimum 2 characters). schema: type: string minLength: 2 example: container platform ProjectId: name: projectId in: path required: true description: Numeric ID of the target project. schema: type: integer example: 7 TriageStatusFilter: name: triage_status in: query description: Filter comments by triage disposition. Defaults to "pending" — the triage table opens on undispositioned comments. Use "all" to return comments in any status. schema: type: string enum: - all - pending - concur - concur_with_comment - non_concur - duplicate - informational - needs_clarification - withdrawn - addressed_by default: pending example: pending PageParam: name: page in: query description: Page number for paginated results (1-based). schema: type: integer minimum: 1 default: 1 example: 1 PerPageParam: name: per_page in: query description: Number of items to return per page. schema: type: integer minimum: 1 maximum: 1000 default: 25 example: 25 ComponentId: name: componentId in: path required: true description: Numeric ID of the target component. schema: type: integer example: 29 RuleId: name: ruleId in: path required: true description: Numeric ID of the target rule. schema: type: integer example: 100 ReviewId: name: reviewId in: path required: true description: Numeric ID of the target review. schema: type: integer example: 44 MembershipId: name: membershipId in: path required: true description: Numeric ID of the target membership record. schema: type: integer example: 15 SrgId: name: id in: path required: true description: Numeric ID of the target Security Requirements Guide (SRG). schema: type: integer example: 1 StigId: name: id in: path required: true description: Numeric ID of the target Security Technical Implementation Guide (STIG). schema: type: integer example: 1 UserId: name: userId in: path required: true description: Numeric ID of the target user. schema: type: integer example: 42