Revise and save Compose document

Request a Nexus revision of supplied text. If documentId resolves in the selected workspace, update that document and snapshot the revised result; otherwise create a new document from the snapshot.

Outcome

Request a Nexus revision of supplied text. If documentId resolves in the selected workspace, update that document and snapshot the revised result; otherwise create a new document from the snapshot.

Before you start

Verify the authenticated identity, environment and pinned organization before preparing an action.
The published application permission is workspace:write. Discover and select a granted Compose workspace separately from action input. A supplied identifier does not grant access.
A read_write workspace grant is required, including model suggestion previews that do not persist document text.
Authorize the documented effects or private-data export before CLI --confirm or MCP confirm:true. HTTP method alone does not establish a read-only operation.

Discover the target

topolo whoami --json
topolo actions get app_topolo_compose.documents.revise --detail --json
topolo resources topolo-compose --json
topolo workspaces list topolo-compose --json

Select the granted workspace id as COMPOSE_WORKSPACE_ID. Use document and version ids returned by accessible reads; fixture ids confer no live access.

Request

POST /api/documents/revise

Save action input as payload.json. Inspect the plan for the exact path, query and body. Set COMPOSE_WORKSPACE_ID from granted resource discovery.

Inspect and test this action in the signed action console, then perform the verification below.

Input fields

Field	Required	Type	Constraints
`documentId`	Optional	string	{"minLength":1}
`document`	Required	object	{}
`instruction`	Required	string	{"minLength":1}
`revisionContext`	Optional	See exact schema	{}

Exact input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "documentId": {
      "type": "string",
      "minLength": 1
    },
    "document": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "title": {
          "type": "string",
          "minLength": 1
        },
        "type": {
          "type": "string"
        },
        "style": {
          "type": "string"
        },
        "audience": {
          "type": "string",
          "minLength": 1
        },
        "markdown": {
          "type": "string",
          "minLength": 1
        },
        "sourceMaterial": {
          "type": "string"
        },
        "generationContract": {}
      },
      "required": [
        "markdown"
      ],
      "additionalProperties": false
    },
    "instruction": {
      "type": "string",
      "minLength": 1
    },
    "revisionContext": {}
  },
  "required": [
    "document",
    "instruction"
  ],
  "additionalProperties": false
}

Effects

Uses the supplied document snapshot and instruction as model context.
An accessible documentId updates that row; a missing or inaccessible id produces a new draft rather than a 404 refusal. Verify the returned id.
Saves the revised result with reason revision. It does not automatically snapshot the current text before replacing it; save a manual version first.
On an existing row preserves approval metadata while replacing text and provenance; this does not prove the revised text was reviewed.

Interpret the response

Use response path $.document.id for compose_document. An empty list does not discover a target.

Expect HTTP 200 and compare document.id to your intended target. Read documents.get and documents.versions.list; confirm revised text and reason revision. If the id changed, inspect the newly created draft before continuing.

The success schema below was checked against captured handler responses. Optional structured generation metadata and integration-dependent values can vary. Error examples retain their actual refusal shapes.

Success schema:

{
  "type": "object",
  "required": [
    "document"
  ],
  "properties": {
    "document": {
      "type": "object",
      "required": [
        "id",
        "title",
        "type",
        "style",
        "audience",
        "markdown",
        "sourceMaterial",
        "generationContract",
        "provider",
        "model",
        "approvalStatus",
        "approvalOwner",
        "approvalDueAt",
        "approvalNotes",
        "archivedAt",
        "createdByUserId",
        "createdByEmail",
        "createdAt",
        "updatedAt"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "style": {
          "type": "string"
        },
        "audience": {
          "type": "string"
        },
        "markdown": {
          "type": "string"
        },
        "sourceMaterial": {
          "type": "null"
        },
        "generationContract": {
          "type": "null"
        },
        "provider": {
          "type": "string"
        },
        "model": {
          "type": "string"
        },
        "approvalStatus": {
          "type": "string"
        },
        "approvalOwner": {
          "type": "null"
        },
        "approvalDueAt": {
          "type": "null"
        },
        "approvalNotes": {
          "type": "null"
        },
        "archivedAt": {
          "type": "null"
        },
        "createdByUserId": {
          "type": "string"
        },
        "createdByEmail": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      }
    }
  }
}

Worked examples

Responses were captured from the actual Compose Worker using synthetic users, organizations, content and identifiers. Tests simulate Auth, Nexus, Notify, metering and platform workspace transport and use an in-memory D1 adapter or local SQLite. They prove local handler behavior, not live model correctness, provider cost, notification delivery, real workspace grants or cross-store atomicity. HTTP 204 responses are exactly empty strings in the SDK transport. Replace fixture identifiers through credential-scoped discovery. Refused examples demonstrate boundaries and must not be executed as successful workflows.

Successful request

Actual Compose Worker response. Auth, Nexus, notifications, metering and platform workspace transport are simulated. D1 is an in-memory adapter or local SQLite as stated by the test. This does not prove a live model completion or notification delivery. No request credentials are captured. Captured scenario: revision snapshots the result and requires an explicit version to preserve a later manual edit.

Input · payload.json:

{
  "documentId": "34c69a42-3e7f-4c74-9756-ee4a67da1f14",
  "document": {
    "id": "34c69a42-3e7f-4c74-9756-ee4a67da1f14",
    "title": "Brief",
    "markdown": "# Unsnapshotted manual edit"
  },
  "instruction": "Improve the brief"
}

CLI:

topolo actions validate app_topolo_compose.documents.revise --data @payload.json --json
topolo actions plan app_topolo_compose.documents.revise --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.revise --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_compose.documents.revise",
    "input": {
      "documentId": "34c69a42-3e7f-4c74-9756-ee4a67da1f14",
      "document": {
        "id": "34c69a42-3e7f-4c74-9756-ee4a67da1f14",
        "title": "Brief",
        "markdown": "# Unsnapshotted manual edit"
      },
      "instruction": "Improve the brief"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "document": {
    "id": "34c69a42-3e7f-4c74-9756-ee4a67da1f14",
    "title": "Brief",
    "type": "general",
    "style": "executive",
    "audience": "General audience",
    "markdown": "# Revised result",
    "sourceMaterial": null,
    "generationContract": null,
    "provider": "anthropic",
    "model": "claude-test",
    "approvalStatus": "draft",
    "approvalOwner": null,
    "approvalDueAt": null,
    "approvalNotes": null,
    "archivedAt": null,
    "createdByUserId": "user_test_1",
    "createdByEmail": "writer@stg.topolo.us",
    "createdAt": "2026-10-04T02:26:27.223Z",
    "updatedAt": "2026-10-04T02:26:27.227Z"
  }
}

HTTP 200. Expect HTTP 200 and compare document.id to your intended target. Read documents.get and documents.versions.list; confirm revised text and reason revision. If the id changed, inspect the newly created draft before continuing.

Another supported request

Actual Compose Worker response. Auth, Nexus, notifications, metering and platform workspace transport are simulated. D1 is an in-memory adapter or local SQLite as stated by the test. This does not prove a live model completion or notification delivery. No request credentials are captured. Captured scenario: generate / revise / suggest > revise updates an existing org document in place.

Input · payload.json:

{
  "documentId": "27d38113-ff59-4f75-96b8-f7ceb8c18907",
  "document": {
    "id": "27d38113-ff59-4f75-96b8-f7ceb8c18907",
    "title": "Orig",
    "markdown": "# Orig\n\nbody"
  },
  "instruction": "make it crisp"
}

CLI:

topolo actions validate app_topolo_compose.documents.revise --data @payload.json --json
topolo actions plan app_topolo_compose.documents.revise --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.revise --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_compose.documents.revise",
    "input": {
      "documentId": "27d38113-ff59-4f75-96b8-f7ceb8c18907",
      "document": {
        "id": "27d38113-ff59-4f75-96b8-f7ceb8c18907",
        "title": "Orig",
        "markdown": "# Orig\n\nbody"
      },
      "instruction": "make it crisp"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "document": {
    "id": "27d38113-ff59-4f75-96b8-f7ceb8c18907",
    "title": "Orig",
    "type": "general",
    "style": "executive",
    "audience": "General audience",
    "markdown": "# Revised\n\nUpdated text.",
    "sourceMaterial": null,
    "generationContract": null,
    "provider": "anthropic",
    "model": "claude-test",
    "approvalStatus": "draft",
    "approvalOwner": null,
    "approvalDueAt": null,
    "approvalNotes": null,
    "archivedAt": null,
    "createdByUserId": "user_test_1",
    "createdByEmail": "writer@stg.topolo.us",
    "createdAt": "2026-10-04T02:26:27.292Z",
    "updatedAt": "2026-10-04T02:26:27.293Z"
  }
}

Another supported request

Actual Compose Worker response. Auth, Nexus, notifications, metering and platform workspace transport are simulated. D1 is an in-memory adapter or local SQLite as stated by the test. This does not prove a live model completion or notification delivery. No request credentials are captured. Captured scenario: generate / revise / suggest > revise creates a new document when no row resolves.

Input · payload.json:

{
  "document": {
    "title": "Snapshot",
    "type": "letter",
    "markdown": "# Snapshot\n\nbody"
  },
  "instruction": "tighten"
}

CLI:

topolo actions validate app_topolo_compose.documents.revise --data @payload.json --json
topolo actions plan app_topolo_compose.documents.revise --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.revise --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_compose.documents.revise",
    "input": {
      "document": {
        "title": "Snapshot",
        "type": "letter",
        "markdown": "# Snapshot\n\nbody"
      },
      "instruction": "tighten"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "document": {
    "id": "308c6aec-393e-4bce-83b4-7c5c9414af49",
    "title": "Snapshot",
    "type": "general",
    "style": "executive",
    "audience": "General audience",
    "markdown": "# New\n\nfresh",
    "sourceMaterial": null,
    "generationContract": null,
    "provider": "anthropic",
    "model": "claude-test",
    "approvalStatus": "draft",
    "approvalOwner": null,
    "approvalDueAt": null,
    "approvalNotes": null,
    "archivedAt": null,
    "createdByUserId": "user_test_1",
    "createdByEmail": "writer@stg.topolo.us",
    "createdAt": "2026-10-04T02:26:27.293Z",
    "updatedAt": "2026-10-04T02:26:27.293Z"
  }
}

Another supported request

Actual Compose Worker response. Auth, Nexus, notifications, metering and platform workspace transport are simulated. D1 is an in-memory adapter or local SQLite as stated by the test. This does not prove a live model completion or notification delivery. No request credentials are captured. Captured scenario: each grant level against each route > 'POST' '/api/documents/revise' with a 'read_write' grant.

Input · payload.json:

{
  "document": {
    "title": "Plan",
    "markdown": "# Plan"
  },
  "instruction": "Tighten it"
}

CLI:

topolo actions validate app_topolo_compose.documents.revise --data @payload.json --json
topolo actions plan app_topolo_compose.documents.revise --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.revise --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_compose.documents.revise",
    "input": {
      "document": {
        "title": "Plan",
        "markdown": "# Plan"
      },
      "instruction": "Tighten it"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "document": {
    "id": "f785e343-aaef-467d-b1ec-4ff635ecf5c9",
    "title": "Plan",
    "type": "general",
    "style": "executive",
    "audience": "General audience",
    "markdown": "# Generated Title\n\nBody paragraph one.",
    "sourceMaterial": null,
    "generationContract": null,
    "provider": "anthropic",
    "model": "claude-test",
    "approvalStatus": "draft",
    "approvalOwner": null,
    "approvalDueAt": null,
    "approvalNotes": null,
    "archivedAt": null,
    "createdByUserId": "user_test_1",
    "createdByEmail": "writer@stg.topolo.us",
    "createdAt": "2026-10-04T02:26:27.374Z",
    "updatedAt": "2026-10-04T02:26:27.374Z"
  }
}

Refused request · HTTP 400

Actual Compose Worker response. Auth, Nexus, notifications, metering and platform workspace transport are simulated. D1 is an in-memory adapter or local SQLite as stated by the test. This does not prove a live model completion or notification delivery. No request credentials are captured. Captured scenario: generate / revise / suggest > revise validates instruction and document presence.

Input · payload.json:

{
  "document": {
    "markdown": "# x"
  }
}

CLI:

topolo actions validate app_topolo_compose.documents.revise --data @payload.json --json
topolo actions plan app_topolo_compose.documents.revise --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 400:

{
  "success": false,
  "error": {
    "code": "invalid_action_input",
    "message": "Invalid action input for \"documents.revise\".",
    "action": "documents.revise",
    "issues": [
      {
        "path": "instruction",
        "message": "Invalid input: expected string, received undefined",
        "code": "invalid_type"
      }
    ]
  }
}

HTTP 400. The handler refused this request. Resolve its exact cause before retrying; input validation can reject an invalid fixture before it reaches the handler.

Refused request · HTTP 403

Actual Compose Worker response. Auth, Nexus, notifications, metering and platform workspace transport are simulated. D1 is an in-memory adapter or local SQLite as stated by the test. This does not prove a live model completion or notification delivery. No request credentials are captured. Captured scenario: each grant level against each route > 'POST' '/api/documents/revise' with a 'read' grant.

Input · payload.json:

{
  "document": {
    "title": "Plan",
    "markdown": "# Plan"
  },
  "instruction": "Tighten it"
}

CLI:

topolo actions validate app_topolo_compose.documents.revise --data @payload.json --json
topolo actions plan app_topolo_compose.documents.revise --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 403:

{
  "error": "This workspace requires read_write access",
  "code": "workspace_access_insufficient"
}

HTTP 403. The handler refused this request. Resolve its exact cause before retrying; input validation can reject an invalid fixture before it reaches the handler.

Verify the result

Expect HTTP 200 and compare document.id to your intended target.
Read documents.get and documents.versions.list; confirm revised text and reason revision. If the id changed, inspect the newly created draft before continuing.

Errors and recovery

invalid_action_input (HTTP 400): Correct the exact discovered input fields; refused fixtures are not successful requests.
This workspace requires read_write access (HTTP 403): Verify the authenticated organization, application permission and granted workspace. For reviewer_required, use the legitimately assigned reviewer; requesting review grants no access.

Auth, action-input validation and platform resource resolution can refuse a request before its handler. Retain the exact error, request id and context; requesting another context is not a legitimate way to bypass a refusal.

Recovery boundary

Snapshot the current document before revision. Restore that saved version through documents.versions.restore if needed; archive a new draft created from an unresolved id. Neither operation reverses completion cost.

Get Compose document: Read one document in the authorized organization and workspace, including current markdown, provenance, approval metadata and archival state. This read can initialize the local workspace mirror.
Save Compose document snapshot: Save a manual snapshot of the current accessible document’s text and provenance. This creates a new version without editing the current document.
Restore saved Compose document text: Replace current text and provenance with an accessible saved version, first saving pre_restore text and then a restore snapshot. Approval metadata resets to draft.
Archive Compose document: Hide a document from the active list by setting archivedAt, while retaining its content and saved versions. Archived documents still count toward the workspace archival emptiness check.
Preview Compose revision suggestion: Preview through Nexus suggested revised text without saving a document or version. The operation still requests an AI completion and requires an authorized write-capable workspace context.

Evidence

Responses were captured from the actual Compose Worker using synthetic users, organizations, content and identifiers. Tests simulate Auth, Nexus, Notify, metering and platform workspace transport and use an in-memory D1 adapter or local SQLite. They prove local handler behavior, not live model correctness, provider cost, notification delivery, real workspace grants or cross-store atomicity. HTTP 204 responses are exactly empty strings in the SDK transport. Replace fixture identifiers through credential-scoped discovery. Capture digests and test scenarios are retained in the source fixture records.

Revise and save Compose document

Outcome

Before you start

Discover the target

Request

Input fields

Effects

Interpret the response

Worked examples

Successful request

Another supported request

Another supported request

Another supported request

Refused request · HTTP 400

Refused request · HTTP 403

Verify the result

Errors and recovery

Recovery boundary

Related actions

Evidence