Outcome
Remove the provider hostname and local connection in order, keeping DNS, public data and uncertain effects separate.
DELETE /api/domains/{domainId}
Before you start
Use the original authorized organization and a discovered canonical Forms workspace, bound separately. List needs workspace:read; writes need workspace:write. Bearer requests resolve minimum read for list and admin for domain writes. API-key authority comes through original Auth introspection of its binding and the app permission check; do not invent an additional local role check.
Only connect a hostname and DNS zone you are authorized to administer. Organization visibility does not transfer ownership or mutation authority. The projection does not identify its owning workspace. An ownership TXT token is not an Auth credential or platform grant.
These actions return planned DNS instructions; they do not publish DNS records. Preserve unrelated mail/TXT records during any separately approved DNS administration. Syntax validity is not global hostname registry custody, reserved-hostname enforcement, exclusive ownership or correct provider origin. Those surrounding contracts remain with their existing owners.
All examples are complete source-derived synthetic responses, unrun. Names, ids, ownership token and example.test URLs are fictional. The exact published domain-connections0.4.4 artifact matches the checked lock integrity and was inspected without import/execution. No real DNS lookup/write, Cloudflare, form/subject/Auth/provider/model/notification operation or browser navigation occurred.
Request and effects
Action: app_topolo_forms.domains.delete. Validate current input and, for a real mutation, obtain applicable approval and a confirmed executable plan for the exact owner-scoped target and provider/public effects.
Requires a separately approved discovered domainId and original owner-workspace mutation authority. Organization-visible rows owned elsewhere return404 domain_not_found; list visibility does not authorize disconnect.
Published helper reads the provider and deletes a matching custom hostname, or reports deleted:false when absent. The app does not expose that helper result: after it resolves, local SQL deletion returns200 {deleted:true,id}. This is not proof a provider object existed or independent post-delete verification.
Provider removal precedes local deletion without a transaction. A network/JSON/provider or later DB failure can leave partial/unknown effects. Preserve original hostname,id,provider and request evidence before any repeat; never reconnect to force a successful result.
No DNS records,form/submissions or every external copy are removed by this sequence. MX/SPF/DKIM/TXT and prior public responses remain separate. Actual DNS cleanup, provider absence and local record absence require their approved owner evidence.
No exact restore is established. Re-creation uses new local/token ids and appropriate verification; it cannot restore previous identity,timestamps,external state or history. Do not automatically recreate as rollback.
Complete worked responses
Provider helper resolved and local row removed
Complete source-derived synthetic, unrun HTTP200. Assumes original ownership and provider read/delete helper resolves, including its no-match branch, followed by local SQL deletion. No actual hostname,provider,DNS or form was removed.
Input:
{
"domainId": "domain_00000000-0000-4000-8000-000000000004"
}
Response:
{
"deleted": true,
"id": "domain_00000000-0000-4000-8000-000000000004"
}
Preserve actual original target/request evidence and follow verification/recovery; the fixture authorizes no operation.
No owned row
Complete source-derived synthetic, unrun HTTP404. Assumes original authorization but no owned row. This alone does not settle effects of an earlier lost deletion.
Input:
{
"domainId": "domain_absent_docs_fixture"
}
Response:
{
"error": "domain_not_found"
}
Preserve actual original target/request evidence and follow verification/recovery; the fixture authorizes no operation.
Verify and recover
-
Read domains.list in the original context and reconcile expected id/hostname absence with actual provider/request evidence; local absence does not prove DNS cleanup.
-
Have the existing owner reconcile uncertain provider/local state before a repeat. Do not change credential,workspace or hostname spelling to evade a refusal.
Preserve actual outcomes and unknown effects for the existing owner. Any reconnection is separately approved new setup and ownership verification, not exact rollback; DNS and form-data effects remain distinct.
Refusals and uncertainty
400 / workspace_required: Discover/bind the original authorized canonical workspace through Auth; input is not a grant.
403 / forbidden: Preserve actual permission denial and use its owner for legitimate access.
404 / domain_not_found: Reconcile discovered domain and owner workspace; organization visibility is not mutation authority.
422 / invalid_hostname: Use the actual legitimate plain hostname/plan, without bypassing policy or publishing fictional records.
422 / edge_not_configured: Refer actual public-base/provider configuration evidence to the existing owner; do not provision or change credentials as a workaround.
422 / edge_attach_failed: This helper class also covers provider read/delete errors. Reconcile possible provider effects and original evidence before a repeat.
Concrete branches differ from shared runtime failures. DNS,provider,local state and read-back can disagree after interrupted work; a response is not a complete external effect or rollback receipt.
Related actions
Change log
- 2026-10-21: Added owner-workspace/organization visibility, exact published DNS plans, provider/local sequencing, complete illustrative responses and scoped recovery. All examples remain synthetic and unrun.