# Queue a human decision about ONE file the agent left waiting `POST /agent/instructions` **Required scope:** `documents:write` The file is on the customer's machine and immut does not hold the bytes, so this records an intention, NOT an outcome. Nothing is protected until the agent acts and reports it. Upserts on (company, path), so changing your mind replaces the decision rather than queueing a contradictory second one. ## Request body Content type: `application/json` (required) | Field | Type | Required | Description | |---|---|---|---| | `path` | string | **yes** | the file path exactly as the agent reported it in a run's decisions[] (required) | | `action` | string | **yes** | protect \| reject (required). protect = upload it on the next sweep; reject = leave it and record decision declined_by_human | | `workspace` | string | no | workspace id (optional) | ## Responses | Status | Meaning | |---|---| | `200` | Success | | `400` | BadRequest | | `401` | Unauthorized | | `403` | Forbidden | | `429` | RateLimited | ## Example ```bash curl -X POST "https://backend.immut.io/api/v1/agent/instructions" \ -H "Authorization: Bearer $IMMUT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"path":"","action":"","workspace":""}' ``` ## OpenAPI fragment ```json { "/agent/instructions": { "post": { "operationId": "postagentinstructions", "summary": "Queue a human decision about ONE file the agent left waiting. The file is on the customer's machine and immut does not hold the bytes, so this records an intention, NOT an outcome. Nothing is protected until the agent acts and reports it. Upserts on (company, path), so changing your mind replaces the decision rather than queueing a contradictory second one.", "description": "Queue a human decision about ONE file the agent left waiting. The file is on the customer's machine and immut does not hold the bytes, so this records an intention, NOT an outcome. Nothing is protected until the agent acts and reports it. Upserts on (company, path), so changing your mind replaces the decision rather than queueing a contradictory second one.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "description": "the file path exactly as the agent reported it in a run's decisions[] (required)" }, "action": { "type": "string", "description": "protect | reject (required). protect = upload it on the next sweep; reject = leave it and record decision declined_by_human" }, "workspace": { "type": "string", "description": "workspace id (optional)" } }, "required": [ "path", "action" ] } } } }, "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Agent" ], "x-required-scope": "documents:write" } } } ```