Read one Forms form definition

Outcome

Retrieve the full stored form model in its verified workspace without publishing or changing it.

GET /api/forms/{formId}

Before you start

Use the original authorized identity and intended organization. Discover a canonical Forms workspace and bind it as separate workspace resource context. The published application grant is workspace:read; an organization id, form id or arbitrary workspaceId input is not a grant.

These are authenticated administrative reads, distinct from the public form-response route. User bearer requests resolve a required workspace with read access; API-key requests rely on Auth introspection of the same supplied resource binding and require that binding. Preserve any refusal rather than widening context.

Examples are complete source-derived synthetic responses, not captured production reads. No real form, respondent, answer, key material, consent, CRM, delivery, provider/model or notification operation was executed. Source-to-serving association and browser/UI proof remain separate.

Request and response

Action: app_topolo_forms.forms.get. Use {} for a list, or the discovered formId for a form/summary read; bind the authorized workspace separately. Validate current published input before the read. Fixture ids authorize no operation.

Input requires formId. Resolve the real id from forms.list or another supported authorized reference. Optional workspaceId and query.workspaceId fields are not new authorization; keep the separately verified resource binding consistent.

Selected source looks up organization, workspace and id together. Missing/out-of-scope rows return HTTP404 {error:not_found}; the response does not distinguish another tenant’s existence. Found rows are unprotected, mapped and returned as HTTP200 {forms:<one object>}, despite the plural envelope key.

The full model includes stored title/description/thank-you content, fields, creator ids/email, timestamps, draft/published status and a separate submissionCount. Default thank-you translation is used only when stored copy is blank. Fields JSON is parsed, with [] fallback on parse failure; this read does not normalize the stored field definitions.

The response is an authenticated editor model, not a public reference, an embed URL or a response submission. Published status alone does not prove that the public edge, domain, delivery integrations, translation release or downstream CRM/Consent is ready.

Protection and consistency

The original organization and verified workspace scope every selected form and submission query. API-key/bearer handling and required workspace read access precede the concrete route permission check. A permitted read does not authorize edits, publishing, submission, export, delivery retry, erasure or key changes.

The selected source unprotects stored content under its environment-aware protection policy before mapping the response. A protection/key/dependency failure is not an empty result or permission to change environment policy, provision keys, migrate data or expose ciphertext as readable content. The guide does not certify production key health.

Reads can expose decrypted form text, field definitions and author metadata; summaries also load submission records internally. Keep actual returned content within its approved audience. Publishing this technical guide with fictional data does not make the application data public.

Independent form, count and submission reads are not a single cross-store transaction. A missing count row is converted to zero by source; zero by itself is not a protection, collection-health or completeness check. Shared runtime failures can differ from the concrete route errors below; no unique carrier is invented.

Complete worked responses

Read the discovered form

Complete synthetic, unrun HTTP200. Assumes a matching organization/workspace/form row, readable protected fields and separate count3. All content and identifiers are fictional; creator fields are explicitly null and stored thank-you text avoids translation assumptions.

Input:

{
  "formId": "forms_docs_fixture"
}

Response:

{
  "forms": {
    "id": "forms_docs_fixture",
    "organizationId": "org_docs_fixture",
    "workspaceId": "ws_forms_docs_fixture",
    "title": "Fixture feedback",
    "description": "Synthetic documentation example",
    "thankYouTitle": "Thank you",
    "thankYouMessage": "Your fixture response was received.",
    "slug": "fixture-feedback",
    "status": "published",
    "fields": [
      {
        "id": "topics",
        "label": "Topics",
        "type": "multi_select",
        "required": false,
        "options": [
          "Docs",
          "API"
        ],
        "width": "full"
      }
    ],
    "createdByUserId": null,
    "createdByEmail": null,
    "createdAt": "2026-10-01T08:00:00.000Z",
    "updatedAt": "2026-10-20T08:00:00.000Z",
    "publishedAt": "2026-10-02T08:00:00.000Z",
    "submissionCount": 3
  }
}

Confirm the actual id, organization and workspace. Do not turn status or the count into permission to publish, submit or retrieve personal answers.

No matching form in the verified workspace

Complete synthetic, unrun HTTP404 after successful original auth, workspace and route permission checks, with no matching row. It is not a cross-tenant existence probe.

Input:

{
  "formId": "forms_absent_docs_fixture"
}

Response:

{
  "error": "not_found"
}

Reconcile the intended workspace and discovered id. Do not enumerate other organizations or guess ids to bypass this refusal.

Verify and recover

1. Compare actual forms.id, organizationId and workspaceId with the approved target. Keep the plural forms envelope as an object; do not treat it as a collection.

2. Interpret fields, status and timestamps as the stored definition at this read. Use the separate supported reference/public-flow checks only if needed and authorized; do not submit a real response as a documentation test.

3. On an actual shared auth, protection or database failure preserve the request id, status and sanitized error. Do not interpret failure as an empty result, disable protection, migrate/rotate keys or run business actions as a read recovery.

These reads make no form or submission mutation and need no data rollback. A published guide is not a grant to operate on any sample or real record.

Refusals

403 / organization_required: Authenticate in the intended original organization; do not guess a tenant id or change context to force access.

400 / workspace_required: Supply a discovered authorized canonical workspace as separate resource binding; an action input id alone does not grant access.

403 / forbidden: The selected route permission check refused workspace:read. Preserve the actual denial and seek legitimate access from its owner.

404 / not_found: For a single-form/summary read, reconcile the discovered form id and authorized workspace. Do not probe another tenant.

Concrete route carriers are distinguished from generic action metadata and shared runtime errors. Invalid local input is a schema-validation refusal, not a captured server response.

Related actions

• forms.list
• summary.get

Change log

• 2026-10-21: Added exact single-object plural envelope, scoped lookup/refusal, full stored model and protection/publication distinctions with complete illustrative responses. All examples remain synthetic and unrun.