ControlMap API - Documentation Updates
Summary
Updated API descriptions and removed nullable flags from policy-section timestamps.
The published request contract now explicitly requires a non-blank title when creating governance documents or procedures. This aligns the reference with existing server validation; callers must continue supplying title. Document responses also describe approver and team information, and policy-search responses identify deprecated aliases and their supported replacements. The major version remains v1; no endpoints are added in this release.
Client-resource and cross-client summary descriptions now consistently distinguish a client's resources from multiple clients' resources. These wording changes do not change request paths, methods, permissions, or behavior.
Changes
Changed
-
POST
/controlmap/v1/clients/{client_id}/governance; POST/controlmap/v1/clients/{client_id}/procedures- Optional documented title → Required documented title
- Type: breaking change
- Notes: The published request contract now requires
title, matching existing server validation. Always provide a non-blanktitle;nameis not a substitute. Clients generated from the earlier contract should update their request models. Creation responses also document optionalapproverandteamobjects containing an identifier and display name.
-
GET and PATCH
/controlmap/v1/clients/{client_id}/governance/{governance_id}- Available → Improved
- Type: addition
- Notes: Response documentation and examples include optional
approverandteamobjects, each withidandname, alongside the document owner.
-
POST
/controlmap/v1/clients/{client_id}/policies; GET and PATCH/controlmap/v1/clients/{client_id}/policies/{policy_id}- Available → Improved
- Type: addition
- Notes: Creation, detail, and partial-update responses document optional
approverandteamobjects containingidandname. Detail and partial-update examples show these fields.
-
GET and PATCH
/controlmap/v1/clients/{client_id}/procedures/{procedure_id}- Available → Improved
- Type: addition
- Notes: Detail and partial-update responses document optional
approverandteamobjects containingidandname, with matching response examples.
-
POST
/controlmap/v1/clients/{client_id}/policies/search- Available → Improved
- Type: improvement
- Notes: Section timestamps
created_atandupdated_atare documented as optional date-time strings, omitted when unavailable rather than returned as JSONnull. Their deprecatedcreatedateandupdatedatealiases also remain optional, non-nullable date-time strings. This documents existing serialization behavior; callers must allow timestamp properties to be absent.
-
GET
/controlmap/v1/clients/{client_id}/risks/categories; GET/controlmap/v1/clients/{client_id}/risk-categories/{risk_category_id}- Available → Improved
- Type: improvement
- Notes: Existing risk-category lookup summaries clarify that categories belong to the selected client. These operations already exist; their request and response contracts are unchanged.
-
GET
/controlmap/v1/clients/{client_id}/risks/departments- Available → Improved
- Type: improvement
- Notes: The existing risk-department lookup summary clarifies client ownership. No lookup endpoint is added.
-
GET
/controlmap/v1/clients/{client_id}/vendors/questionnaires- Available → Improved
- Type: improvement
- Notes: The existing vendor Risk Assessment questionnaire lookup description clarifies client ownership. Questionnaire selection and pagination behavior are unchanged; no Risk Assessment operations are added.
Deprecated
- POST
/controlmap/v1/clients/{client_id}/policies/search- Legacy section fields → Deprecated
- Type: deprecation
- Notes: Section aliases
policyId,sectionOrder,majorVersion,minorVersion,createdate, andupdatedateare explicitly marked deprecated. Preferpolicy_id,section_order,major_version,minor_version,created_at, andupdated_at, respectively. For the deprecatedpolicySectionsfield, use the policy's existing flatsectionslist instead. Legacy fields remain supported for compatibility; no removal date is established and no removal migration is required for this release.
Dates
- Effective: [2026-10-26]
