Outcome
Generate through Nexus text from a prompt and audience, then create a new Compose document and generated snapshot. Every successful call creates a new document.
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.generate --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/generate
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 |
|---|---|---|---|
type | Optional | string | {"enum":["contract","scientific_paper","maths_paper","letterhead","proposal","report","policy","general"]} |
style | Optional | string | {"enum":["executive","legal","academic","technical","brand"]} |
audience | Required | string | {"minLength":1} |
prompt | Required | string | {"minLength":1} |
sourceMaterial | Optional | string | {} |
generationContract | Optional | See exact schema | {} |
Exact input schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"contract",
"scientific_paper",
"maths_paper",
"letterhead",
"proposal",
"report",
"policy",
"general"
]
},
"style": {
"type": "string",
"enum": [
"executive",
"legal",
"academic",
"technical",
"brand"
]
},
"audience": {
"type": "string",
"minLength": 1
},
"prompt": {
"type": "string",
"minLength": 1
},
"sourceMaterial": {
"type": "string"
},
"generationContract": {}
},
"required": [
"audience",
"prompt"
],
"additionalProperties": false
}
Effects
- Requests a model completion through the configured platform provider.
- On completion success persists a new draft, generated version and returned provenance.
- The prompt contract guides the model; it does not certify legal, factual, scientific or citation correctness.
- A failed provider response creates no successful generated document; retry can incur another completion and successful retry creates a new id.
Interpret the response
Use response path $.document.id for compose_document. An empty list does not discover a target.
Expect HTTP 200 with document.id, markdown and provider/model provenance. Read documents.get and documents.versions.list, inspect generated reason, then review the content and citations before using it. Local provider fixtures prove no live completion.
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": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"generationContract": {
"type": "object",
"required": [
"brandVoiceProfile",
"styleReferenceSummary",
"approvedTerms",
"bannedTerms",
"groundingMode",
"citationStyle",
"includedSections",
"excludedSections",
"readinessCounts",
"missingReadinessItems"
],
"properties": {
"brandVoiceProfile": {
"type": "string"
},
"styleReferenceSummary": {
"type": "string"
},
"approvedTerms": {
"type": "array",
"items": {
"type": "string"
}
},
"bannedTerms": {
"type": "array",
"items": {
"type": "string"
}
},
"groundingMode": {
"type": "string"
},
"citationStyle": {
"type": "string"
},
"includedSections": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"purpose",
"evidence"
],
"properties": {
"title": {
"type": "string"
},
"purpose": {
"type": "string"
},
"evidence": {
"type": "string"
}
}
}
},
"excludedSections": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"purpose",
"evidence"
],
"properties": {
"title": {
"type": "string"
},
"purpose": {
"type": "string",
"maxLength": 0
},
"evidence": {
"type": "string",
"maxLength": 0
}
}
}
},
"readinessCounts": {
"type": "object",
"required": [],
"properties": {
"ready": {
"type": "number"
},
"partial": {
"type": "number"
},
"missing": {
"type": "number"
}
}
},
"missingReadinessItems": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"purpose",
"evidence"
],
"properties": {
"title": {
"type": "string"
},
"purpose": {
"type": "string",
"maxLength": 0
},
"evidence": {
"type": "string",
"maxLength": 0
}
}
}
},
"readinessScore": {
"type": "number"
}
}
},
"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: generate / revise / suggest > generate persists a document from the Nexus completion.
Input · payload.json:
{
"type": "report",
"style": "executive",
"audience": "leadership",
"prompt": "Draft a strategy memo",
"sourceMaterial": "Q3 notes"
}
CLI:
topolo actions validate app_topolo_compose.documents.generate --data @payload.json --json
topolo actions plan app_topolo_compose.documents.generate --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.generate --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.generate",
"input": {
"type": "report",
"style": "executive",
"audience": "leadership",
"prompt": "Draft a strategy memo",
"sourceMaterial": "Q3 notes"
},
"resourceType": "workspace",
"resourceId": "<identifier returned by granted resource discovery>",
"confirm": true
}
}
Captured local response · HTTP 200:
{
"document": {
"id": "ddc7f8d1-db9d-40dd-bed2-304aae457303",
"title": "AI Memo",
"type": "report",
"style": "executive",
"audience": "leadership",
"markdown": "# AI Memo\n\nGenerated body.",
"sourceMaterial": "Q3 notes",
"generationContract": {
"brandVoiceProfile": "",
"styleReferenceSummary": "",
"approvedTerms": [],
"bannedTerms": [],
"groundingMode": "source_locked",
"citationStyle": "inline_evidence",
"includedSections": [],
"excludedSections": [],
"readinessCounts": {},
"missingReadinessItems": []
},
"provider": "anthropic",
"model": "claude-x",
"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.286Z",
"updatedAt": "2026-10-04T02:26:27.286Z"
}
}
HTTP 200. Expect HTTP 200 with document.id, markdown and provider/model provenance. Read documents.get and documents.versions.list, inspect generated reason, then review the content and citations before using it. Local provider fixtures prove no live completion.
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 > generate with a rich generation contract still succeeds.
Input · payload.json:
{
"audience": "board",
"prompt": "Quarterly review",
"generationContract": {
"brandVoiceProfile": "confident",
"styleReferenceSummary": "concise",
"approvedTerms": [
"runway"
],
"bannedTerms": [
"synergy"
],
"groundingMode": "source_guided",
"citationStyle": "apa",
"readinessScore": 80,
"readinessCounts": {
"ready": 4,
"partial": 1,
"missing": 2
},
"includedSections": [
{
"title": "Summary",
"purpose": "overview",
"evidence": "metrics"
}
],
"excludedSections": [
{
"title": "Appendix"
}
],
"missingReadinessItems": [
{
"title": "Forecast"
}
]
}
}
CLI:
topolo actions validate app_topolo_compose.documents.generate --data @payload.json --json
topolo actions plan app_topolo_compose.documents.generate --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.generate --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.generate",
"input": {
"audience": "board",
"prompt": "Quarterly review",
"generationContract": {
"brandVoiceProfile": "confident",
"styleReferenceSummary": "concise",
"approvedTerms": [
"runway"
],
"bannedTerms": [
"synergy"
],
"groundingMode": "source_guided",
"citationStyle": "apa",
"readinessScore": 80,
"readinessCounts": {
"ready": 4,
"partial": 1,
"missing": 2
},
"includedSections": [
{
"title": "Summary",
"purpose": "overview",
"evidence": "metrics"
}
],
"excludedSections": [
{
"title": "Appendix"
}
],
"missingReadinessItems": [
{
"title": "Forecast"
}
]
}
},
"resourceType": "workspace",
"resourceId": "<identifier returned by granted resource discovery>",
"confirm": true
}
}
Captured local response · HTTP 200:
{
"document": {
"id": "97f80001-ad67-45fc-ad8e-c11be465ca64",
"title": "Generated Title",
"type": "general",
"style": "executive",
"audience": "board",
"markdown": "# Generated Title\n\nBody paragraph one.",
"sourceMaterial": null,
"generationContract": {
"brandVoiceProfile": "confident",
"styleReferenceSummary": "concise",
"approvedTerms": [
"runway"
],
"bannedTerms": [
"synergy"
],
"groundingMode": "source_guided",
"citationStyle": "apa",
"includedSections": [
{
"title": "Summary",
"purpose": "overview",
"evidence": "metrics"
}
],
"excludedSections": [
{
"title": "Appendix",
"purpose": "",
"evidence": ""
}
],
"readinessScore": 80,
"readinessCounts": {
"ready": 4,
"partial": 1,
"missing": 2
},
"missingReadinessItems": [
{
"title": "Forecast",
"purpose": "",
"evidence": ""
}
]
},
"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.291Z",
"updatedAt": "2026-10-04T02:26:27.291Z"
}
}
HTTP 200. Expect HTTP 200 with document.id, markdown and provider/model provenance. Read documents.get and documents.versions.list, inspect generated reason, then review the content and citations before using it. Local provider fixtures prove no live completion.
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/generate' with a 'read_write' grant.
Input · payload.json:
{
"audience": "Leaders",
"prompt": "Write a plan"
}
CLI:
topolo actions validate app_topolo_compose.documents.generate --data @payload.json --json
topolo actions plan app_topolo_compose.documents.generate --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.generate --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.generate",
"input": {
"audience": "Leaders",
"prompt": "Write a plan"
},
"resourceType": "workspace",
"resourceId": "<identifier returned by granted resource discovery>",
"confirm": true
}
}
Captured local response · HTTP 200:
{
"document": {
"id": "b0b21354-a3a5-4ab2-85df-fc890abfd4eb",
"title": "Generated Title",
"type": "general",
"style": "executive",
"audience": "Leaders",
"markdown": "# Generated Title\n\nBody paragraph one.",
"sourceMaterial": null,
"generationContract": {
"brandVoiceProfile": "",
"styleReferenceSummary": "",
"approvedTerms": [],
"bannedTerms": [],
"groundingMode": "source_locked",
"citationStyle": "inline_evidence",
"includedSections": [],
"excludedSections": [],
"readinessCounts": {},
"missingReadinessItems": []
},
"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.369Z",
"updatedAt": "2026-10-04T02:26:27.369Z"
}
}
HTTP 200. Expect HTTP 200 with document.id, markdown and provider/model provenance. Read documents.get and documents.versions.list, inspect generated reason, then review the content and citations before using it. Local provider fixtures prove no live completion.
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/generate' with a 'admin' grant.
Input · payload.json:
{
"audience": "Leaders",
"prompt": "Write a plan"
}
CLI:
topolo actions validate app_topolo_compose.documents.generate --data @payload.json --json
topolo actions plan app_topolo_compose.documents.generate --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.generate --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.generate",
"input": {
"audience": "Leaders",
"prompt": "Write a plan"
},
"resourceType": "workspace",
"resourceId": "<identifier returned by granted resource discovery>",
"confirm": true
}
}
Captured local response · HTTP 200:
{
"document": {
"id": "027ba8ce-166b-4dfa-b7f2-da0926369472",
"title": "Generated Title",
"type": "general",
"style": "executive",
"audience": "Leaders",
"markdown": "# Generated Title\n\nBody paragraph one.",
"sourceMaterial": null,
"generationContract": {
"brandVoiceProfile": "",
"styleReferenceSummary": "",
"approvedTerms": [],
"bannedTerms": [],
"groundingMode": "source_locked",
"citationStyle": "inline_evidence",
"includedSections": [],
"excludedSections": [],
"readinessCounts": {},
"missingReadinessItems": []
},
"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.371Z",
"updatedAt": "2026-10-04T02:26:27.371Z"
}
}
HTTP 200. Expect HTTP 200 with document.id, markdown and provider/model provenance. Read documents.get and documents.versions.list, inspect generated reason, then review the content and citations before using it. Local provider fixtures prove no live completion.
Refused request · HTTP 504
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: worker error branches > Nexus timeout surfaces a 504.
Input · payload.json:
{
"audience": "execs",
"prompt": "memo"
}
CLI:
topolo actions validate app_topolo_compose.documents.generate --data @payload.json --json
topolo actions plan app_topolo_compose.documents.generate --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
Captured local response · HTTP 504:
{
"error": "nexus_completion_timeout"
}
HTTP 504. 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 401
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: worker error branches > completion requires an Authorization header.
Input · payload.json:
{
"audience": "execs",
"prompt": "memo"
}
CLI:
topolo actions validate app_topolo_compose.documents.generate --data @payload.json --json
topolo actions plan app_topolo_compose.documents.generate --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
Captured local response · HTTP 401:
{
"error": "authorization_required"
}
HTTP 401. 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: generate / revise / suggest > generate validates required prompt.
Input · payload.json:
{
"audience": "execs"
}
CLI:
topolo actions validate app_topolo_compose.documents.generate --data @payload.json --json
topolo actions plan app_topolo_compose.documents.generate --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.generate\".",
"action": "documents.generate",
"issues": [
{
"path": "prompt",
"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 502
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 > generate surfaces a Nexus failure.
Input · payload.json:
{
"audience": "execs",
"prompt": "memo"
}
CLI:
topolo actions validate app_topolo_compose.documents.generate --data @payload.json --json
topolo actions plan app_topolo_compose.documents.generate --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
Captured local response · HTTP 502:
{
"error": "nexus_down"
}
HTTP 502. 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/generate' with a 'read' grant.
Input · payload.json:
{
"audience": "Leaders",
"prompt": "Write a plan"
}
CLI:
topolo actions validate app_topolo_compose.documents.generate --data @payload.json --json
topolo actions plan app_topolo_compose.documents.generate --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 with document.id, markdown and provider/model provenance.
- Read documents.get and documents.versions.list, inspect generated reason, then review the content and citations before using it. Local provider fixtures prove no live completion.
Errors and recovery
nexus_completion_timeout(HTTP 504): Preserve the error and request id. Inspect configured Auth, Nexus or transport health through authorized operational actions before retrying; no live provider outcome is proved by this fixture.authorization_required(HTTP 401): Refresh the authorized credential in the same environment and pinned organization; do not switch scope to bypass this refusal.invalid_action_input(HTTP 400): Correct the exact discovered input fields; refused fixtures are not successful requests.nexus_down(HTTP 502): Preserve the error and request id. Inspect configured Auth, Nexus or transport health through authorized operational actions before retrying; no live provider outcome is proved by this fixture.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
Archive an unwanted generated draft through documents.archive. Archival does not undo model cost, provider execution or usage records.
Related actions
- 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.
- List saved Compose document versions: Read the 25 newest saved snapshots of an accessible document. This read can initialize the local workspace mirror and exposes no continuation cursor.
- 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.