Changelog
Back to All
Added

ControlMap API – Objective Editing, Risk Detail & Health History

September 23rd, 2026

Summary

This release opens up objective editing and crosswalks, adds daily history to client health metrics, and returns much richer risk detail — full impact/likelihood scoring, mappings, and tags — with a matching set of new risk filters. Every {client_id} path now accepts your own tenant_id as well as the ScalePad client UUID, so you can call ControlMap with the identifier you already have.

It also restores several contracts that the 2026-08-04 release removed: the deprecated DELETE routes for evidence schedules and assessment-question unmapping work again, the evidence-mappings refresh response returns client_id again, and the Remediation in progress risk status is accepted again. Each is kept for backward compatibility and marked deprecated — see Deprecated below for the replacements.

Two breaking changes remain: the create-action-item response changes shape, and terminal pagination returns next_cursor: null again instead of omitting the field on the client health, evidence, and framework-objectives lists — a reversal of the 2026-08-04 behaviour that breaks loops written against it. Review both before upgrading. The major version stays v1, and the regional server list is unchanged.

Changes

New endpoints

Objectives

  • PATCH /controlmap/v1/clients/{client_id}/frameworks/{framework_id}/objectives/{objective_id}

    • N/A → Available
    • Type: addition
    • Notes: Update an objective in place. Send only the fields you want to change: status, target_maturity, current_maturity (name plus a required observation), implementation_details, in_scope, description, or remarks. When you send both in_scope and status, status is applied last and may adjust the final scope.

  • POST /controlmap/v1/clients/{client_id}/frameworks/{framework_id}/objectives/{objective_id}/mappings

    • N/A → Available
    • Type: addition
    • Notes: Map an objective to crosswalk objectives, supplied as objective codes grouped by compliance program name. Returns 204.

  • POST /controlmap/v1/clients/{client_id}/frameworks/{framework_id}/objectives/{objective_id}/mappings/bulk-delete

    • N/A → Available
    • Type: addition
    • Notes: Remove crosswalk mappings from an objective, using the same program-scoped body shape. Empty lists result in no changes.

Risks

  • GET /controlmap/v1/clients/{client_id}/risks/categories
    • N/A → Available
    • Type: addition
    • Notes: List the risk categories configured for a client, with an optional search term (case-insensitive, minimum 3 characters) to filter by name. Use it to populate category pickers and to resolve the risk_category_id values now accepted by risk search.

Client identifiers

  • {client_id} accepts your tenant ID
    • UUID only → UUID or tenant_id
    • Type: addition
    • Notes: Every ControlMap endpoint with a {client_id} path segment now accepts either the ScalePad client UUID or that client's tenant_id. Existing calls that pass a UUID are unaffected.

Client health

  • GET /controlmap/v1/clients/{client_id}/health
    • N/A → Available
    • Type: addition
    • Notes: The single-client health snapshot can now return daily history. Pass include_history (any of compliance_score, risk_score, frameworks, evidence, controls, action_items, assessments, documents, or work_progress to cover all five nested work-progress sections at once) plus an optional start_date/end_date range in yyyy-MM-dd. The selected sections return a metric_history array of dated snapshots, and compliance_score also returns trend_data with a daily 0–10 score. include_history defaults to compliance_score; the default window is the previous 7 days.

Risks

  • Richer risk detail on read

    • N/A → Available
    • Type: addition
    • Notes: Risk responses now include status_id, department_id, risk_category_id, and treatment_code alongside their existing name fields, plus full inherent_risk, current_risk, and target_risk objects (impact and likelihood values with their option IDs and labels, the calculated score, a risk label, and a score colour). Each risk also returns mappings — the compact code/name/type of every entity linked to it — and tags.

  • POST /controlmap/v1/clients/{client_id}/risks/search

    • Filters and sorting expanded
    • Type: addition
    • Notes: Risk search accepts a search term (case-insensitive across risk name and code) and new filters for id, name, status_id, owner.id, owner.name, department, department_id, risk_category, risk_category_id, the inherent/current/target impact and likelihood option IDs, current_risk_label, and tag. Sorting adds code, status, treatment, department, and risk_category. All new filters and sorting options are optional, and an existing {} request remains valid.

Objectives

  • POST /controlmap/v1/clients/{client_id}/frameworks/{framework_id}/objectives/search

    • Filters and sorting expanded
    • Type: addition
    • Notes: Objective search accepts a search term across objective name and code, plus scope_id, level1_id, and level2_id filters for implementation scope and hierarchy. Sorting adds id, sort_order, and status. Document mappings are now returned once per managed document and carry a document_type of policy, procedure, or governance so you can resolve the correct destination.

  • remarks and observation on objective detail

    • N/A → Available
    • Type: addition
    • Notes: Objective detail responses now return remarks and the current assessment observation, matching the fields you can set through the new PATCH endpoint.

Action items

  • POST /controlmap/v1/clients/{client_id}/action-items

    • Response shape changed
    • Type: breaking change
    • Notes: The create response is now a create-specific object rather than the full action item. parent_entity_id is returned again; the date, effort, and milestone fields use the create naming (planned_end_date, actual_end_date, efforts, change_in_milestone); responsible_person is a string; cost is an integer; and the linked collections returned by GET — documents, controls, risks, objectives, requirements, assessment questions, assets, and programs — along with created_at, created_by, updated_at, type, and source_of_weakness, are not part of the create response. Read the created item back with GET /controlmap/v1/clients/{client_id}/action-items/{action_item_id} if you need those fields.

  • POA&M flag

    • N/A → Available
    • Type: addition
    • Notes: Action item responses return is_poam, indicating whether the item is included in the Plan of Action and Milestones, and the partial-update endpoint accepts it. Partial update also accepts responsible_department_id for setting the responsible department by ID.

  • GET /controlmap/v1/clients/action-items-summary

    • Generic envelope → documented response
    • Type: improvement
    • Notes: The response is now fully documented: each data entry pairs a client with its action_summary progress metrics. The wire format is unchanged.

Assessments

  • Previous answer on question responses
    • N/A → Available
    • Type: addition
    • Notes: Assessment question responses now include past_answered_at and past_answered_by, so you can show when a question was last answered and by whom.

Evidence

  • Program-scoped objective mapping

    • N/A → Available
    • Type: addition
    • Notes: Evidence mapping requests accept an objectives array of objective codes grouped by program_name, which resolves codes within a single compliance program instead of tenant-wide. The tenant-wide objective_codes array still works but is deprecated.

  • POST /controlmap/v1/clients/{client_id}/evidence-mappings/refresh

    • clientId → client_id
    • Type: improvement
    • Notes: The refresh response returns client_id again, reversing the rename in the 2026-08-04 release. clientId is still returned as a deprecated alias, so integrations written against either name keep working.

Pagination

  • next_cursor is always present
    • Field omitted → null on the last page
    • Type: breaking change
    • Notes: On the client compliance-health, evidence, and framework-objectives list responses, next_cursor is always returned and is null on the last page, reversing the omit-on-last-page behaviour described in the 2026-08-04 release. Loops that test for a missing key should test for null instead.

Deprecated

  • DELETE /controlmap/v1/clients/{client_id}/evidences/{evidence_id}/schedule

    • Removed → Available (deprecated)
    • Type: deprecation
    • Notes: This route works again after being removed in the 2026-08-04 release, so existing integrations are unblocked. It takes the same required schedule_action query parameter as before. Migrate to POST /controlmap/v1/clients/{client_id}/evidences/{evidence_id}/schedule/delete, a direct replacement, before the next major version.

  • DELETE /controlmap/v1/clients/{client_id}/assessments/common/questions/{question_code}/mappings

    • Removed → Available (deprecated)
    • Type: deprecation
    • Notes: This route works again after being removed in the 2026-08-04 release. Migrate to POST /controlmap/v1/clients/{client_id}/assessments/common/questions/{question_code}/mappings/bulk-delete, which takes the same body shape, before the next major version.

  • Risk status Remediation in progress

    • Rejected → Accepted (deprecated)
    • Type: deprecation
    • Notes: Creating or updating a risk with Remediation in progress is accepted again for backward compatibility after being rejected in the 2026-08-04 release. Needs Remediation is the current value; migrate to it before the next major version.

  • objective_codes on evidence mapping requests

    • Available → Deprecated
    • Type: deprecation
    • Notes: Use the program-scoped objectives array instead, which resolves objective codes within a named compliance program.

  • clientId on the evidence-mappings refresh response

    • Available → Deprecated
    • Type: deprecation
    • Notes: Read client_id instead. The camelCase alias remains for now and will be removed in a future version.

Dates

  • Effective: [2026-09-22]