Outcome
Read the authorized form label, publication state and optional public/embed URLs without creating a placement.
GET /api/forms/references/{id}
Before you start
Use the original authorized organization and discovered canonical Forms workspace, bound separately as a resource. The action needs workspace:read and verified read workspace access; a form/reference id or optional workspaceId input is not a grant.
These authenticated Connected Apps reads include drafts and are distinct from public form access. A returned reference projection, URL or embed URL does not create a placement, join a workspace, grant a recipient access or authorize publication/submission.
All examples are complete source-derived synthetic responses, unrun. Fictional ids and reserved example.test URLs authorize no operation. No real form/subject/placement/Auth/resource/provider/model/notification call or browser navigation was performed. Source declaration provenance, actual serving, domains, protection health and browser rendering remain separate.
Request and response
Action: app_topolo_forms.forms.references.get.
Input requires id, the discovered plain form identifier; it is not formId or a canonical URI field in this action. Keep the separately verified workspace binding consistent with any optional workspaceId input.
The source queries organization/workspace/id together through getForm and returns404 {error:not_found} when absent/out of scope. Otherwise HTTP200 is {form:<projection>}, a singular object distinct from forms.get’s plural forms envelope.
Both draft and published records can be returned to an authorized reader. The projection does not expose form fields or respondent answers, but getForm still decodes protected form content and counts submissions before projecting. There is no placement or public-availability side effect.
The source first reads full scoped form models through the existing protected content/count path, then projects only id,label,status,updatedAt,publishedAt,workspace,url,embedUrl. Projection does not mean the underlying work is a cheap metadata-only query. Protection, auth or database errors are not an empty result.
Label is stored title with id fallback. Published status plus a nonempty configured public base produces /public/<encoded form id> and /embed/<encoded form id>; otherwise both URLs are null. Drafts remain discoverable with draft status and null URLs. A published record can also have null URLs when no public base is configured.
The projection carries plain form id, not a returned topolo: reference URI. The source canonical format is topolo:<appId>/<workspaceId>/forms.form/<formId> for validated components, but actual placement/reference discovery must use supported credential-scoped Connected Apps actions and resolved identities; never manufacture cross-context ids or invent a placement grant.
Reading these actions performs no form edit, publication, placement mutation, respondent submission or reference notification. Conditional change/removal events occur in separate mutation paths; their source declarations do not prove a consumer received an event or rendered an embed.
Complete worked responses
Published projection
Complete source-derived synthetic, unrun HTTP200. Assumes a readable scoped fictional published form and configured public base https://forms.example.test. The shown URLs are illustrative; they were not opened or probed.
Input:
{
"id": "forms_docs_fixture"
}
Response:
{
"form": {
"id": "forms_docs_fixture",
"label": "Fixture feedback",
"status": "published",
"updatedAt": "2026-10-21T01:00:00.000Z",
"publishedAt": "2026-10-02T08:00:00.000Z",
"workspace": "ws_forms_docs_fixture",
"url": "https://forms.example.test/public/forms_docs_fixture",
"embedUrl": "https://forms.example.test/embed/forms_docs_fixture"
}
}
Verify the actual target and publication/URL semantics below; this fixture creates no reference placement or access.
Draft projection
Complete source-derived synthetic, unrun HTTP200. Assumes the readable fictional draft exists in the same original workspace. Null URLs express its source projection, not a missing Auth grant or an invitation to publish it.
Input:
{
"id": "forms_draft_docs_fixture"
}
Response:
{
"form": {
"id": "forms_draft_docs_fixture",
"label": "Fixture draft",
"status": "draft",
"updatedAt": "2026-10-20T01:00:00.000Z",
"publishedAt": null,
"workspace": "ws_forms_docs_fixture",
"url": null,
"embedUrl": null
}
}
Verify the actual target and publication/URL semantics below; this fixture creates no reference placement or access.
No matching reference source
Complete source-derived synthetic, unrun HTTP404. Assumes original auth/workspace/read checks pass and no scoped form row exists. It is not proof of another tenant’s existence or a live enumeration attempt.
Input:
{
"id": "forms_absent_docs_fixture"
}
Response:
{
"error": "not_found"
}
Verify the actual target and publication/URL semantics below; this fixture creates no reference placement or access.
Verify and recover
-
Compare actual form.id and form.workspace with the discovered target and original authorized resource. Preserve the singular form envelope.
-
Respect status and nullable URLs. If a real approved placement is required, discover and plan the separate Connected Apps action; no actual submission or placement is needed merely to verify this read.
This read needs no data rollback. On a failure preserve the actual request id and sanitized response for the owner; do not create a workspace, publish a draft, change protection or submit real data as recovery.
Refusals
400 / workspace_required: Resolve the real canonical workspace through supported Auth and bind it separately, without a guessed resource.
403 / forbidden: Retain the original caller/context and actual denial; use the owner for legitimate read access.
404 / not_found: Reconcile the id discovered in this authorized workspace; do not probe another organization or treat a draft as publicly accessible.
Shared runtime/Auth/protection errors require their actual carrier evidence; the success schema does not describe every failure.
Related actions
Change log
- 2026-10-21: Added precise reference projection, original workspace/privacy boundaries, draft/URL semantics, source pagination limits and complete illustrative responses. All examples remain synthetic and unrun.