<!--
  immut documentation, machine-readable.

  Everything in one file:  https://www.immut.io/llms-full.txt
    What immut is, which integration path to choose, authentication and scopes, and the COMPLETE
    API reference: every endpoint with parameters, responses and a runnable curl. Fetch this first
    if you intend to call the API.

  Index of all pages:      https://www.immut.io/llms.txt
  OpenAPI contract:        https://www.immut.io/docs/openapi.json
  This page as HTML:       https://www.immut.io/docs/mcp/protect_new_version

  Any page on this site is available as raw markdown by appending .md to its URL.
-->


# protect_new_version

**Protect a new version of an existing document (by bytes)**

Protect an UPDATED version of a document already on immut. This proves the NEW content existed by the time immut received it. It does NOT prove when the edit was made, so never date the change itself. immut proves the bytes it receives. Ask first whether your AI can open this file from the disk. If it cannot, it can only send bytes handed to it, and text read out of a document is NOT those bytes: a proof of transcribed text is not a proof of your file. When you cannot read the file itself, say so and stop rather than reconstructing it. This server is remote and cannot read your filesystem, so pass the new bytes as base64 along with the existing documentId. Use when a protected file has been revised (e.g. a contract re-signed, a policy updated). Do NOT transcribe a large file into base64 here (it is slow and error-prone): for anything substantial use multipart POST /api/v1/documents/{id}/version directly, or install the immut skill so it can read the file locally. Find the documentId with list_documents.

- Access: write
- Calls: `/api/v1/documents/{documentId}/version`

## Arguments

| Name | Type | Required | Description |
|---|---|---|---|
| `documentId` | string | **yes** | Id of the existing immut document to add a version to |
| `filename` | string | **yes** | Original file name incl. extension |
| `contentBase64` | string | **yes** | Base64-encoded bytes of the NEW version |
| `runId` | string | no | Id of the sweep this upload belongs to. Use the SAME value on every file in one sweep and on the matching report_run call — it is what links a run to the files it protected. |
| `agentClassification` | string | no | What you judged about this file, recorded against the proof. Every field optional — send only what you actually determined, and never invent a verdict you did not reach. |

## Tool contract

```json
{
  "name": "protect_new_version",
  "title": "Protect a new version of an existing document (by bytes)",
  "description": "Protect an UPDATED version of a document already on immut. This proves the NEW content existed by the time immut received it. It does NOT prove when the edit was made, so never date the change itself. immut proves the bytes it receives. Ask first whether your AI can open this file from the disk. If it cannot, it can only send bytes handed to it, and text read out of a document is NOT those bytes: a proof of transcribed text is not a proof of your file. When you cannot read the file itself, say so and stop rather than reconstructing it. This server is remote and cannot read your filesystem, so pass the new bytes as base64 along with the existing documentId. Use when a protected file has been revised (e.g. a contract re-signed, a policy updated). Do NOT transcribe a large file into base64 here (it is slow and error-prone): for anything substantial use multipart POST /api/v1/documents/{id}/version directly, or install the immut skill so it can read the file locally. Find the documentId with list_documents.",
  "access": "write",
  "destructive": false,
  "hostedOnProduction": true,
  "restEndpoint": "/api/v1/documents/{documentId}/version",
  "arguments": {
    "documentId": {
      "type": "string",
      "required": true,
      "description": "Id of the existing immut document to add a version to"
    },
    "filename": {
      "type": "string",
      "required": true,
      "description": "Original file name incl. extension"
    },
    "contentBase64": {
      "type": "string",
      "required": true,
      "description": "Base64-encoded bytes of the NEW version"
    },
    "runId": {
      "type": "string",
      "required": false,
      "description": "Id of the sweep this upload belongs to. Use the SAME value on every file in one sweep and on the matching report_run call — it is what links a run to the files it protected."
    },
    "agentClassification": {
      "type": "string",
      "required": false,
      "description": "What you judged about this file, recorded against the proof. Every field optional — send only what you actually determined, and never invent a verdict you did not reach."
    }
  }
}
```