> Production API availability: use /api/v1/help?view=guides and the resource operations catalog before following a recipe. Some localhost capabilities are not deployed yet; an absent operation is unavailable.
What this module owns
Form authoring, submission contracts, workflow configuration and publication to generated sites.
Inspect, patch, preview, sync
GET /api/v1/forms/{hash} returns the current settings_sha256. PATCH the same resource with expected_settings_sha256 and a settings_patch object. Supported top-level settings include website_contract, payment, application_errors, login, link, membership and workflow. Copy the current nested contract before revising it; these keys are not interchangeable.
{
"expected_settings_sha256": "REPLACE_WITH_CURRENT_64_CHARACTER_HASH",
"settings_patch": {
"workflow": { "enabled": false }
}
}This example is the request envelope for disabling a workflow, not a command to run as a smoke test. Missing or malformed hashes and unsupported patch keys are rejected with 400. A changed settings hash is rejected with 409. Fetch again and review the difference instead of forcing a write. The hash comparison and save are separate operations in this handler; it is not proof of an atomic compare-and-swap under concurrent writes.
GET /api/v1/forms/{hash}/diagnostics traces Databoard connections. POST /api/v1/forms/{hash}/workflow-preview renders without queuing or sending. Its inputs object supplies example form fields and its optional workflow object previews a proposed workflow. POST /workflow-run processes scheduled work and can send messages; it is not a dry-run. Sync through POST /api/v1/forms/{hash}/sync after confirming the target.
The older POST /api/v1/forms save path is broader than settings PATCH. Prefer PATCH for settings-only edits; do not send a partial form replacement that discards its fields.
First read
Use API_URL with /api/v1, for example http://localhost/api/v1. Set API_KEY privately. Replace any resource placeholder with an ID returned by discovery.
curl --fail-with-body "$API_URL/forms" \
-H "Authorization: Bearer $API_KEY"Registered agent routes
The entries below are extracted from the current route and handler source. Scope tokens can represent alternatives or different method branches, not a requirement to grant every listed scope. Body fields are observed inputs, not a complete required-field schema. Follow the resource guide and the deployed validation response for a write.
/api/v1/forms
Intended request methods: GET, POST. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: databoard:read, databoard:write, forms:read, forms:write
Observed JSON fields: componentarray, components, desc, description, form_code, group_id, groups_category, hash, name, settings, topology.
Selected rejection messages:
- Form name is required
- Form not found
- Form save failed
/api/v1/forms/{hash}
Intended request methods: GET, PATCH. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: databoard:read, forms:read, forms:write
Observed JSON fields: expected_settings_sha256, settings_patch.
Selected rejection messages:
- GET or PATCH required
- Missing form hash
- Form not found
- Expected settings hash and non-empty settings_patch object required
- Setting is not patchable:
- Form settings changed; fetch again
- Existing Form settings are not a JSON object
/api/v1/forms/{hash}/workflow-preview
Intended request methods: POST. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: forms:write
Observed JSON fields: inputs, workflow.
Selected rejection messages:
- POST required
- Form not found
/api/v1/forms/{hash}/sync
Unavailable in this production release. This reference describes a pending capability. Do not call this endpoint; use deployed discovery to check availability. Intended request methods: POST. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: databoard:deploy, forms:write
Observed JSON fields: databoard_id, group_id.
Selected rejection messages:
- Missing scope: databoard:deploy
- POST required
- databoard_id and group_id are required
- Unable to sync Form
- Invalid Databoard or Form hash
- Form group does not belong to this Databoard
- Form not found in this group
/api/v1/forms/{hash}/workflow-run
Intended request methods: POST. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: forms:write
Selected rejection messages:
- POST required
- Form not found
- Workflow processing unavailable
/api/v1/forms/{hash}/diagnostics
Unavailable in this production release. This reference describes a pending capability. Do not call this endpoint; use deployed discovery to check availability. Intended request methods: GET. Confirm allowed_methods and method_evidence in the deployed operations catalog; documented methods do not grant access.
Scope tokens in the implementation: databoard:read
Selected rejection messages:
- GET required
- Form not found
- Scan unavailable. No completeness claim can be made.
Access boundary
External agents use only the versioned operations documented above and returned by the deployed catalog. Browser actions and internal controllers are not substitutes for missing API operations.
Verification before automation
Read back the owned record after a write. On a dedicated local fixture, test missing input, wrong owner, missing scope and stale revisions where supported. Confirm the request did not change state when rejected. Check the generated projection separately from the source record. Never replay sends, payments or deletion requests merely to test connectivity.
See API validation and remaining gaps for the shared test strategy.
HTTP discovery and safety contract
Read GET /api/v1/help?view=guide&resource=forms for this module's machine-readable guidance. Discover supported operations through its discovery_url when present. A null discovery_url means no direct resource API is documented; related endpoints, when provided, have their own ownership and scope requirements.
Use GET /api/v1/me with your key to confirm identity and scopes. Only request methods and fields supported by this deployment. The shared transport boundary rejects unsupported methods and malformed JSON on covered routes, but field schemas and revision checks remain resource-specific. Notes and Carousels expose typed save schemas and payload-only validation; other modules must not be assumed to share that contract.
Create, update, replace, patch, delete, send and publish are distinct capabilities. An operation absent from the returned catalog is unavailable, not permission to guess a URL. Read back after writes; after a timeout inspect the result before retrying. Never automatically replay a payment, message, deployment or deletion.