Improved

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-blank title; name is not a substitute. Clients generated from the earlier contract should update their request models. Creation responses also document optional approver and team objects 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 approver and team objects, each with id and name, 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 approver and team objects containing id and name. 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 approver and team objects containing id and name, with matching response examples.
  • POST /controlmap/v1/clients/{client_id}/policies/search

    • Available → Improved
    • Type: improvement
    • Notes: Section timestamps created_at and updated_at are documented as optional date-time strings, omitted when unavailable rather than returned as JSON null. Their deprecated createdate and updatedate aliases 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, and updatedate are explicitly marked deprecated. Prefer policy_id, section_order, major_version, minor_version, created_at, and updated_at, respectively. For the deprecated policySections field, use the policy's existing flat sections list 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]