DELETE /api/v1/forms/{formId}
Permanently removes the form and its responses. Use only after explicit confirmation.
Use x-api-key with an active organization-bound API key. Its holder keeps their current Organization, CASL and resource permissions.
| Role in the organization | Access |
|---|
| OWNER | Allowed |
| ADMIN | Allowed |
| MEMBER | Refused — 403 |
| Requirement | Rule |
|---|
| Business role | None; additional setter/closer roles do not grant access |
| Resource scope | Organization bound to the verified key |
| Participation | None |
| Resource state | Published valid draft for publication; otherwise the command determines state |
| Parameter | Type | Required | Description |
|---|
| formId | UUID | yes | Form in the key’s organization |
| Header | Required | Description |
|---|
| x-api-key | yes | Organization-bound key |
| Idempotency-Key | yes | Stable key for one intention; reuse on retry |
curl -X DELETE "https://your-school.cohorte.app/api/v1/forms/{formId}" \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: form-intention-1"
Success: 200. 400 invalid_request for malformed input or missing key; 401 unauthorized for invalid authentication; 403 forbidden for permission refusal; 404 not_found for missing or other-organization resources; 409 conflict for a conflicting state; 500 internal_error for an unexpected failure.
The envelope has success, data, and correlationId, plus replayed for a retry. data contains the deleted form id.
{
"success": true,
"replayed": false,
"data": {
"id": "00000000-0000-4000-8000-000000000001"
},
"correlationId": "00000000-0000-4000-8000-000000000002"
}
Permanently removes the form and its responses. Use only after explicit confirmation.
Commands claim idempotency before the write. Replays suppress repeat audit/events and return current resource state. New intentions need a new key. Qualification updates do not re-score existing responses automatically.
