Outcome
Create a pending domain record and DNS instructions for an approved form, without publishing DNS or attaching a provider hostname.
POST /api/domains
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.create. 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 hostname and a formId in the selected owner workspace; availableAcrossWorkspaces optionally makes it visible across the same organization. The form lookup does not require published status. A missing form returns404 form_not_found.
Selected source trims/lowercases hostname, derives the DNS target from the configured public base, creates fresh token/domain UUIDs and invokes the published planner. It validates hostname syntax/target/token, not actual ownership or registry exclusivity. Use a plain hostname; internationalized names must arrive as punycode A-labels.
The insert stores pending_dns, form association, target/token, availability and timestamps, followed by separate read-back. There is no DNS/provider call in this creation branch. HTTP201 is a local preparation receipt, not DNS,SSL or origin readiness.
No idempotency key or atomic slug reservation/read-back is shown. A uniqueness error containing UNIQUE maps409 hostname_exists; a lost/error response can follow a committed insert. Reconcile actual hostname/id/owner before an approved repeat, without spelling/context variants. The app stores its trimmed/lowercased hostname while the planner also drops a trailing root dot for its calculation; do not assume all variants acquire one global claim.
Complete worked responses
Pending record prepared
Complete source-derived synthetic, unrun HTTP201. Assumes the fictional form exists in the owner workspace, available requested hostname, shown token/id/clock and target edge.example.test; planning,insert,read-back succeed. No DNS/provider step is reached.
Input:
{
"hostname": "forms.example.test",
"formId": "forms_docs_fixture",
"availableAcrossWorkspaces": false
}
Response:
{
"domain": {
"id": "domain_00000000-0000-4000-8000-000000000004",
"hostname": "forms.example.test",
"status": "pending_dns",
"verificationToken": "00000000-0000-4000-8000-000000000003",
"dnsTarget": "edge.example.test",
"formId": "forms_docs_fixture",
"availableAcrossWorkspaces": false,
"records": [
{
"purpose": "routing",
"type": "CNAME",
"host": "forms",
"name": "forms.example.test",
"value": "edge.example.test",
"required": true,
"instruction": "Publish a CNAME from forms to edge.example.test. Leave MX, SPF, and DKIM records unchanged."
},
{
"purpose": "ownership",
"type": "TXT",
"host": "_topolo-verification.forms",
"name": "_topolo-verification.forms.example.test",
"value": "topolo-verification=00000000-0000-4000-8000-000000000003",
"required": true,
"instruction": "Publish a TXT record at _topolo-verification.forms.example.test with this exact value. Leave every other TXT record unchanged."
}
],
"createdAt": "2026-10-21T01:00:00.000Z",
"updatedAt": "2026-10-21T01:00:00.000Z"
}
}
Preserve actual original target/request evidence and follow verification/recovery; the fixture authorizes no operation.
Form absent
Complete source-derived synthetic, unrun HTTP404. Assumes original authority but no matching form; no connection insert or provider call.
Input:
{
"hostname": "forms.example.test",
"formId": "forms_absent_docs_fixture"
}
Response:
{
"error": "form_not_found"
}
Preserve actual original target/request evidence and follow verification/recovery; the fixture authorizes no operation.
Hostname syntax refused
Complete source-derived synthetic, unrun HTTP422. String input is schema-valid but the published planner refuses it after the fictional form lookup. No insert or provider operation.
Input:
{
"hostname": "not a host",
"formId": "forms_docs_fixture"
}
Response:
{
"error": "invalid_hostname",
"message": "Enter a hostname such as example.com or www.example.com."
}
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 compare actual id,hostname,target,form and availability. Confirm actual owner workspace separately for organization-visible records.
-
Only for separately approved real DNS work, use the returned real instructions and then plan the distinct verify action. Never publish these fictional records or treat201 as readiness.
Only after exact target/ownership and effects reconciliation, plan a separately approved disconnect. Generic delete can remove an existing provider hostname; it is not an automatically harmless undo of local preparation.
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.
404 / form_not_found: Discover an actual form in the same owner workspace; do not repoint another workspace to force a match.
422 / edge_not_configured: Refer actual public-base/provider configuration evidence to the existing owner; do not provision or change credentials as a workaround.
409 / hostname_exists: Reconcile existing intended record/owner before any repeat; do not evade collision through spelling/context variants.
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.