# Describe a document after it was protected `PATCH /documents/{id}/classification` **Required scope:** `documents:write` This is the only way to classify a file that was uploaded through the web app or protected before it had a classification, and it is what lets an agent backfill a library it did not create. ## Parameters | Name | In | Required | Description | |---|---|---|---| | `id` | path | yes | id of the target record | ## Request body Content type: `application/json` | Field | Type | Required | Description | |---|---|---|---| | `parties` | string | no | array of named counterparties, e.g. ["Acme Corp"] (optional) | | `documentDate` | string | no | the date ON the document, ISO 8601 (optional). Agent-read and NOT proven | | `abstract` | string | no | one or two lines on what the document holds (optional). Requires the organisation to have enabled abstracts, otherwise this returns 403 | | `docType` | string | no | contract \| ip_disclosure \| policy \| board \| financial \| corporate \| other (optional) | | `docState` | string | no | executed \| issued \| draft \| template \| proposal \| superseded \| unknown (optional) | | `reason` | string | no | one citable reason (optional) | | `folderKey` | string | no | the objective folder key (optional) | | `objective` | string | no | the objective this was judged against (optional) | ## Responses | Status | Meaning | |---|---| | `200` | Merged. `updated` names the fields that actually landed. Returns: documentId, updated (the field names that landed) and the merged classification. MERGES rather than replaces, so a partial annotation never blanks what it says nothing about. Returns 409 HUMAN_CLASSIFICATION if a person set the classification: an agent does not overwrite a human. Returns 403 ABSTRACTS_NOT_PERMITTED rather than silently dropping an abstract the organisation has not consented to store. | | `400` | BadRequest | | `401` | Unauthorized | | `403` | Forbidden | | `429` | RateLimited | ## Example ```bash curl -X PATCH "https://backend.immut.io/api/v1/documents//classification" \ -H "Authorization: Bearer $IMMUT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"parties":"","documentDate":"","abstract":"","docType":"","docState":"","reason":"","folderKey":"","objective":""}' ``` ## OpenAPI fragment ```json { "/documents/{id}/classification": { "patch": { "operationId": "patchdocumentsidclassification", "summary": "Describe a document after it was protected. This is the only way to classify a file that was uploaded through the web app or protected before it had a classification, and it is what lets an agent backfill a library it did not create.", "description": "Describe a document after it was protected. This is the only way to classify a file that was uploaded through the web app or protected before it had a classification, and it is what lets an agent backfill a library it did not create.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id of the target record" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "parties": { "type": "string", "description": "array of named counterparties, e.g. [\"Acme Corp\"] (optional)" }, "documentDate": { "type": "string", "description": "the date ON the document, ISO 8601 (optional). Agent-read and NOT proven" }, "abstract": { "type": "string", "description": "one or two lines on what the document holds (optional). Requires the organisation to have enabled abstracts, otherwise this returns 403" }, "docType": { "type": "string", "description": "contract | ip_disclosure | policy | board | financial | corporate | other (optional)" }, "docState": { "type": "string", "description": "executed | issued | draft | template | proposal | superseded | unknown (optional)" }, "reason": { "type": "string", "description": "one citable reason (optional)" }, "folderKey": { "type": "string", "description": "the objective folder key (optional)" }, "objective": { "type": "string", "description": "the objective this was judged against (optional)" } } } } } }, "responses": { "200": { "description": "Merged. `updated` names the fields that actually landed. Returns: documentId, updated (the field names that landed) and the merged classification. MERGES rather than replaces, so a partial annotation never blanks what it says nothing about. Returns 409 HUMAN_CLASSIFICATION if a person set the classification: an agent does not overwrite a human. Returns 403 ABSTRACTS_NOT_PERMITTED rather than silently dropping an abstract the organisation has not consented to store." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Documents" ], "x-required-scope": "documents:write" } } } ```