Outcome
Read workspace and organization-visible domain records while keeping visibility, ownership and live verification separate.
GET /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.list. 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.
Returns HTTP200 {domains:[...]} for original-organization rows owned by the selected workspace OR marked organization-visible. Ordering is created_at ascending; no LIMIT,cursor,total or stable tie-breaker appears.
Each projection contains id,hostname,status,verificationToken,dnsTarget,formId,availableAcrossWorkspaces,records,createdAt,updatedAt. Instructions are freshly planned from stored values; status is not rechecked against DNS or Cloudflare. A planning failure is not an empty result.
This read does not attach a provider hostname, perform DNS lookup or assign a form. Organization-visible rows owned elsewhere remain unavailable for selected-workspace mutations.
Complete worked responses
Stored connection
Complete source-derived synthetic, unrun HTTP200. Assumes original read authority and one valid fictional stored row. pending_dns is stored status, not a resolver observation.
Input:
{}
Response:
{
"domains": [
{
"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.
No visible rows
Complete source-derived synthetic, unrun HTTP200. Assumes successful authorized query with no rows, not a suppressed dependency/planning error.
Input:
{}
Response:
{
"domains": []
}
Preserve actual original target/request evidence and follow verification/recovery; the fixture authorizes no operation.
Verify and recover
-
Retain the actual id/hostname and original context; verify owner workspace separately before a mutation.
-
Treat stored status and instructions as data, not a fresh DNS/provider/public-form test. A real verify is a separate approved action.
Read only. Preserve errors for the owner; do not create/verify/delete a domain or broaden access as rollback.
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.
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.