Topolo Docs Topolo Platform
Open workspace

Complete assigned Compose review

Record one pending review decision as approved or rejected. The authenticated user must be the assigned reviewer; a completed review cannot be decided again.

Outcome

Record one pending review decision as approved or rejected. The authenticated user must be the assigned reviewer; a completed review cannot be decided again.

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.approvals.complete --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.
  • Retain review.id from documents.reviews.request and use the assigned reviewer’s legitimate credential context. Document approvalOwner text is not proof of that grant.

Request

POST /api/documents/{documentId}/approvals

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

FieldRequiredTypeConstraints
documentIdRequiredstring{"minLength":1}
reviewIdRequiredstring{"minLength":1}
decisionRequiredstring{"enum":["approved","rejected"]}
notesOptionalstring{"minLength":1}

Exact input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "documentId": {
      "type": "string",
      "minLength": 1
    },
    "reviewId": {
      "type": "string",
      "minLength": 1
    },
    "decision": {
      "type": "string",
      "enum": [
        "approved",
        "rejected"
      ]
    },
    "notes": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "documentId",
    "reviewId",
    "decision"
  ],
  "additionalProperties": false
}

Effects

  • Updates the pending review and document approval status once.
  • Rejects a different reviewer, missing review or already-completed review.
  • Attempts Notify emission after persistence; this is an approval decision, not a signature, export or notification delivery receipt.

Interpret the response

Use response path $.approval.id for compose_review. An empty list does not discover a target.

Expect HTTP 200 with approval.id equal to reviewId and the requested status. Read documents.get to inspect approval state; preserve decision and request evidence. A retry after success returns review_completed rather than repeating the decision.

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": [
    "approval"
  ],
  "properties": {
    "approval": {
      "type": "object",
      "required": [
        "id",
        "status",
        "completedAt"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "completedAt": {
          "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: Compose notification workflows > persists a review request and only the assigned reviewer can complete it.

Input · payload.json:

{
  "documentId": "04272175-06fb-44ec-8eaf-2f47e9dfb954",
  "reviewId": "review_17e56bb8-b1b9-4b3a-a44d-f38d05e41af5",
  "decision": "approved",
  "notes": "Ready to publish."
}

CLI:

topolo actions validate app_topolo_compose.documents.approvals.complete --data @payload.json --json
topolo actions plan app_topolo_compose.documents.approvals.complete --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.approvals.complete --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.approvals.complete",
    "input": {
      "documentId": "04272175-06fb-44ec-8eaf-2f47e9dfb954",
      "reviewId": "review_17e56bb8-b1b9-4b3a-a44d-f38d05e41af5",
      "decision": "approved",
      "notes": "Ready to publish."
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "approval": {
    "id": "review_17e56bb8-b1b9-4b3a-a44d-f38d05e41af5",
    "status": "approved",
    "completedAt": "2026-10-04T02:26:27.219Z"
  }
}

HTTP 200. Expect HTTP 200 with approval.id equal to reviewId and the requested status. Read documents.get to inspect approval state; preserve decision and request evidence. A retry after success returns review_completed rather than repeating the decision.

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: Compose notification workflows > supports a review without optional metadata and reports a rejected decision.

Input · payload.json:

{
  "documentId": "e8076730-3dff-41c0-bc6b-15953e2a0522",
  "reviewId": "review_d244f5f4-4876-4f7d-b47b-b201068881ef",
  "decision": "rejected"
}

CLI:

topolo actions validate app_topolo_compose.documents.approvals.complete --data @payload.json --json
topolo actions plan app_topolo_compose.documents.approvals.complete --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.approvals.complete --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.approvals.complete",
    "input": {
      "documentId": "e8076730-3dff-41c0-bc6b-15953e2a0522",
      "reviewId": "review_d244f5f4-4876-4f7d-b47b-b201068881ef",
      "decision": "rejected"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "approval": {
    "id": "review_d244f5f4-4876-4f7d-b47b-b201068881ef",
    "status": "rejected",
    "completedAt": "2026-10-04T02:26:27.232Z"
  }
}

HTTP 200. Expect HTTP 200 with approval.id equal to reviewId and the requested status. Read documents.get to inspect approval state; preserve decision and request evidence. A retry after success returns review_completed rather than repeating the decision.

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: Compose notification workflows > persists a review request and only the assigned reviewer can complete it.

Input · payload.json:

{
  "documentId": "04272175-06fb-44ec-8eaf-2f47e9dfb954",
  "reviewId": "review_17e56bb8-b1b9-4b3a-a44d-f38d05e41af5",
  "decision": "approved"
}

CLI:

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

Captured local response · HTTP 403:

{
  "error": "reviewer_required"
}

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.

Refused request · HTTP 409

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: Compose notification workflows > persists a review request and only the assigned reviewer can complete it.

Input · payload.json:

{
  "documentId": "04272175-06fb-44ec-8eaf-2f47e9dfb954",
  "reviewId": "review_17e56bb8-b1b9-4b3a-a44d-f38d05e41af5",
  "decision": "approved"
}

CLI:

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

Captured local response · HTTP 409:

{
  "error": "review_completed"
}

HTTP 409. 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 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: Compose notification workflows > rejects invalid workflow input and missing documents without persistence.

Input · payload.json:

{
  "reviewId": "review_missing",
  "decision": "maybe",
  "documentId": "647ff33b-dfc7-4ca0-bb1b-db3f248691e9"
}

CLI:

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

Captured local response · HTTP 400:

{
  "error": "decision_invalid"
}

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 404

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: Compose notification workflows > rejects invalid workflow input and missing documents without persistence.

Input · payload.json:

{
  "documentId": "647ff33b-dfc7-4ca0-bb1b-db3f248691e9",
  "reviewId": "review_missing",
  "decision": "approved"
}

CLI:

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

Captured local response · HTTP 404:

{
  "error": "review_not_found"
}

HTTP 404. 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/{documentId}/approvals' with a 'read' grant.

Input · payload.json:

{
  "documentId": "documentId_missing"
}

CLI:

topolo actions validate app_topolo_compose.documents.approvals.complete --data @payload.json --json
topolo actions plan app_topolo_compose.documents.approvals.complete --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.

Refused request · HTTP 404

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/{documentId}/approvals' with a 'read_write' grant.

Input · payload.json:

{
  "documentId": "documentId_missing"
}

CLI:

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

Captured local response · HTTP 404:

{
  "error": "not_found"
}

HTTP 404. 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 with approval.id equal to reviewId and the requested status.
  • Read documents.get to inspect approval state; preserve decision and request evidence. A retry after success returns review_completed rather than repeating the decision.

Errors and recovery

  • reviewer_required (HTTP 403): Verify the authenticated organization, application permission and granted workspace. For reviewer_required, use the legitimately assigned reviewer; requesting review grants no access.
  • review_completed (HTTP 409): Inspect the exact conflict. A completed review cannot be decided again, and a nonempty workspace cannot be archived. Resolve state through the documented workflow.
  • decision_invalid (HTTP 400): Correct the exact discovered input fields; refused fixtures are not successful requests.
  • review_not_found (HTTP 404): Discover the accessible document and version in the selected workspace. A missing or inaccessible id is not permission to create a replacement.
  • 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.
  • not_found (HTTP 404): Discover the accessible document and version in the selected workspace. A missing or inaccessible id is not permission to create a replacement.

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

A completed review cannot be reopened or decided again by this action. Request a new legitimate review if reconsideration is needed; editing approval metadata does not erase the decision record.

  • 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.
  • Request Compose document review: Create a pending review assigned to one user and update document approval metadata to in_review. Notification emission is attempted after persistence and does not prove delivery.

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.