---
title: "Prepare VDMI matrix nomination — draft only, no write"
method: POST
path: "/api/copilot-process/vdmi/:matrixId/prepare-validation"
tags: ["Copilot Process"]
---

# Prepare VDMI matrix nomination — draft only, no write

`POST /api/copilot-process/vdmi/:matrixId/prepare-validation`

## Request

- Base URL: `https://api.cernion.de`
- URL: `https://api.cernion.de/api/copilot-process/vdmi/:matrixId/prepare-validation`
- Auth: none declared

Analyses the VDMI matrix and returns a draft nomination proposal.
**No writes**: This action creates no persisted state. The returned draft must be explicitly confirmed by a consequential execute action (Phase 3).

Set `requiredConfirmation: true` in the response means Copilot must ask the user to confirm before proceeding.

## Query parameters

- `token` string

## Request body

- object
  - `matrixId` string, required: VDMI matrix ID
  - `reason` string, required: Business reason for the nomination
  - `correlationId` string: Caller-supplied trace ID for audit logging
  - `idempotencyKey` string: Prevents duplicate submissions on retries
  - `token` string: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.

## Response `200`

Draft nomination proposal

- object
  - `draftId` string, required: Unique ID of this draft
  - `action` string, required
  - `target` object, required
    - `matrixId` string
    - `matrixName` string
    - `currentStatus` string
  - `proposedChange` object
    - `from` string
    - `to` string
    - `nominationStatus` string
  - `warningIfAny` string, nullable
  - `summary` string, required
  - `confirmationMessage` string
  - `requiredConfirmation` boolean, required
  - `readyToExecute` boolean
  - `consequentialAction` object: The Phase 3 execute action that would perform this change
    - `operationId` string
    - `note` string
  - `auditTrail` object, required
    - `requestedAt` string
    - `requestedBy` string
    - `correlationId` string
    - `idempotencyKey` string, nullable

## Other responses

- `404`: Matrix not found
- `422`: Matrix status does not allow nomination

---

[API](https://skmtc.dev/cernion/apis/cernion-energy-tools-api.md) · [All operations](https://skmtc.dev/cernion/apis/cernion-energy-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cernion/apis/cernion-energy-tools-api/revisions/cdb94473b538?raw)