Outcome
Delete the approved scoped form with explicit partial-effect and retention boundaries; this is not organization-wide erasure.
DELETE /api/forms/{formId}
Before you start
Use the original authorized organization and discovered canonical Forms workspace, bound separately from input. Discover the real form through an authorized read when applicable. The published action requires workspace:write and the selected route requires read_write workspace access; sample ids are not grants.
Obtain approval for the actual mutation, target content and described effects. Validate the exact current action input and confirmed executable plan before a real call. This guide and its fixtures authorize no form change, public exposure, deletion, submission or notification.
All examples are complete source-derived synthetic responses, unrun. No real form/subject/protection/key/mirror/content/submission/provider/model/delivery/notification operation was executed. Source declaration matches the reviewed immutable revision; loaded runtime, dependency health, public rendering and actual delivery remain unverified.
Request and effects
Action: app_topolo_forms.forms.delete.
Requires a separately approved destructive mutation, formId, workspace:write and verified read_write workspace access. The route first reads the scoped form, including protected content/counts; a missing form returns404. Resolve and retain the actual target/preimage before deletion.
The selected route awaits deletion of the form delivery ledger, then submissions, then delivery settings, then the form control row, scoped by original organization/workspace/form. These operations span control/submissions stores without one cross-store transaction. A failure can leave partial deletion; do not infer atomic rollback from a timeout or error.
It then schedules a forms.form.removed reference event with status/reason deleted and returns200 {ok:true,formId}. No independent removed-row count check or complete post-delete read-back is performed by this route. A concurrent disappearance after the initial read can still reach this response.
The route does not explicitly delete stored response exports in its selected sequence, and it does not establish backup/key/external-recipient/provider deletion or recall previously delivered data. Foreign-key/retention behavior needs the relevant owner evidence; do not describe this action as complete privacy or organization erasure.
Reference emission uses actor or prior owner, requires configured Notify/service identity and is scheduled with ctx.waitUntil when available. Failures are caught/logged and do not restore deleted data. An already in-flight delivery or external copy is not recalled by removing its local ledger.
There is no supported exact restoration action demonstrated here. Recreating a form would have a new id and cannot restore submissions, settings, delivery history, reference identity or timestamps. Preserve uncertain effects and approved recovery records rather than automatically recreating or repeating deletion.
Complete worked responses
Reviewed form removed from the selected local stores
Complete source-derived synthetic, unrun HTTP200. Assumes a matching readable fictional form and all four selected delete steps complete before the conditional reference helper is scheduled. No real form, answers, ledger, settings, provider or notification was deleted or invoked.
Input:
{
"formId": "forms_docs_fixture"
}
Response:
{
"ok": true,
"formId": "forms_docs_fixture"
}
Retain actual original target/request evidence and perform the verification/recovery below. The fixture is not a live outcome or authority.
No form matched before deletion
Complete source-derived synthetic, unrun HTTP404. Assumes successful original auth/workspace/write checks and no scoped form at the initial read. This is not proof of the effects of any earlier lost or interrupted deletion.
Input:
{
"formId": "forms_absent_docs_fixture"
}
Response:
{
"error": "not_found"
}
Retain actual original target/request evidence and perform the verification/recovery below. The fixture is not a live outcome or authority.
Verify and recover
-
Re-read the actual form and form collection in the same authorized workspace; reconcile expected absence with request evidence. For required local submission/delivery/settings checks, use supported authorized readers and preserve their refusals.
-
Assess stored exports, privacy retention, external delivery/reference effects and any partial deletion separately with the relevant owners. Do not erase an organization, change permissions or recreate data to force a clean verification.
No exact reversal is established for this destructive sequence. Preserve approved preimages, actual results and unknown partial effects for the data/application owner. Do not guess a restore, recreate a different form as rollback, or replay uncertain deletion without reconciliation.
Refusals and uncertainty
400 / workspace_required: Discover and bind the canonical authorized workspace through supported Auth resource/workspace actions, not a guessed id or app-bootstrap grant.
403 / forbidden: Preserve the actual write permission refusal. Seek legitimate access through its owner rather than broadening context.
404 / not_found: Reconcile the real discovered form in the same original workspace; for uncertain prior writes/deletion, absence alone does not settle effects.
Protection, database, Auth and shared runtime failures need their actual status/request evidence. Inserts/updates and final read-back are separate; a lost, invalid or missing read-back is not proof of no committed effect. Do not disable protection, replay credentials or probe another tenant to recover.
Related actions
Change log
- 2026-10-21: Added scoped lifecycle behavior, protection/concurrency boundaries, exact illustrative success and refusal bodies, side-effect-aware verification and honest compensation limits. All examples remain synthetic and unrun.