Outcome
Configure one future threshold without treating creation or a claim marker as notification delivery.
POST /api/forms/{formId}/thresholds
Before you start
Use the original authorized organization and discovered canonical Forms workspace. Bind that workspace separately from action input, then discover the actual form and threshold as needed. Neither a sample id nor an input workspaceId is a grant.
Technical guide publication does not make actual form/threshold/creator data public. All responses below are complete source-derived synthetic examples, unrun; no real form/subject/threshold read, configuration change, submission, notification, provider/model or delivery operation was executed.
A live mutation needs approval for its real target and effects, current input validation and a confirmed executable plan. Read operations retain original scope without mutation confirmation. Shared auth/runtime/protection failures require their actual request evidence; never bypass them by changing identity, access or environment policy.
Request and behavior
Action: app_topolo_forms.response_thresholds.create.
Requires a separately approved mutation, workspace:write and verified read_write workspace access. The source reads the scoped form first, including protected content; a missing/out-of-scope form returns404 before parsing the creation body.
Input requires a discovered formId and a positive integer responseCount within the current schema maximum. The handler converts the value to Number and checks integer>0, but the strict action input rejects non-integer/string/zero values before execution. Optional workspaceId/query fields do not grant a workspace.
The selected insert creates a fresh formthreshold_UUID, stores original organization/workspace/form, response count, last_triggered_count0, current creator id and timestamps. HTTP201 returns only threshold:{id,responseCount,lastTriggeredCount,createdAt}; it is constructed after the awaited insert, not a separate read-back.
No immediate notification is sent by this creation route and no current submission count is used to mark the threshold reached. A later public-submission processor may count responses and claim eligible rows when Notify/service configuration is present. A threshold already at/below the current count can become eligible on a later submission. Do not create a real submission merely to verify it.
The processor updates the claim marker before notification emission and catches failures. Recipient is the threshold creator, falling back to the form creator when absent; emitted/provider delivery is separate. The route does not guarantee exactly-once receipt. A caught error whose text contains unique returns409 threshold_exists; reconcile a duplicate rather than guessing a different count.
No idempotency key is exposed here. After a timeout or lost response, list existing thresholds in the same original context and compare the intended count before any approved repeat. Do not retry in parallel. Deletion is a separate compensating mutation and cannot recall prior claimed/emitted notifications.
Complete worked responses
Threshold inserted
Complete source-derived synthetic, unrun HTTP201. Assumes a readable authorized fictional form, no conflicting threshold, successful insert, the shown synthetic UUID and clock. No real threshold or notification was created.
Input:
{
"formId": "forms_docs_fixture",
"responseCount": 100
}
Response:
{
"threshold": {
"id": "formthreshold_00000000-0000-4000-8000-000000000001",
"responseCount": 100,
"lastTriggeredCount": 0,
"createdAt": "2026-10-21T01:00:00.000Z"
}
}
Preserve actual original target/context and follow the verification/recovery steps; this fixture authorizes no operation.
Conflicting threshold refused
Complete source-derived synthetic, unrun HTTP409. Assumes a successful form read and an insert error containing unique, mapped by the selected handler. This is not an observed deployed constraint or a live conflict probe.
Input:
{
"formId": "forms_docs_fixture",
"responseCount": 100
}
Response:
{
"error": "threshold_exists"
}
Preserve actual original target/context and follow the verification/recovery steps; this fixture authorizes no operation.
Form absent
Complete source-derived synthetic, unrun HTTP404. Assumes successful original auth/workspace/permission checks and no matching form; no insert is reached.
Input:
{
"formId": "forms_absent_docs_fixture",
"responseCount": 100
}
Response:
{
"error": "not_found"
}
Preserve actual original target/context and follow the verification/recovery steps; this fixture authorizes no operation.
Verify and recover
-
Read response_thresholds.list in the same organization/workspace/form and compare the actual returned id and count exactly once. The mutation’s201 and marker0 are not independent read-back or delivery proof.
-
If execution was uncertain, reconcile the intended count and discovered row before repeating or compensating. Do not change the count merely to bypass a duplicate. Preserve any notification effects separately.
Only when separately approved, delete the verified newly created threshold in the same original form/workspace, then list and verify absence. This cannot recall already claimed/emitted notifications; do not use a guessed id or delete someone else’s configuration.
Refusals
400 / workspace_required: Resolve the canonical workspace through supported Auth resource/workspace discovery and bind it separately. The app bootstrap response is not a workspace catalogue.
403 / forbidden: Preserve the actual route permission refusal in its original context; use the owner for legitimate access.
404 / not_found: Reconcile the actual discovered form/threshold in the same workspace; do not guess another tenant’s ids.
409 / threshold_exists: List and compare the intended existing threshold before any repeat; do not pick a different count merely to force success.
400 / invalid_response_count: The selected handler requires a positive whole number; the published action schema rejects invalid values locally before a call.
400 / invalid_json_body: For direct published HTTP callers provide the documented object body; normal action JSON is schema-validated before transport.
The current output is a broad catalog-derived structural schema. Schema acceptance alone does not identify the actual success carrier or prove that a mutation or notification completed. Preserve concrete status, body and request evidence.
Related actions
Change log
- 2026-10-21: Added original workspace/permission boundaries, exact threshold carrier and claim semantics, complete illustrative responses, uncertainty reconciliation and limits of compensation. All examples are synthetic and unrun.