POST /api/v1/forms/{formId}/unpublish
Removes public availability immediately, including anonymous resume. Historical versions stay immutable.
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 | Head of Sales only — otherwise 403 |
| Requirement | Rule |
|---|
| Business role | Owner, admin or Head of Sales; setter and 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 POST "https://your-school.cohorte.app/api/v1/forms/{formId}/unpublish" \
-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. A form exposes id, title, description, theme, chrome flags, submissionMode, identityFields, definition, qualification, programIds, cohortIds, isActive, slug, publishedVersion (id, version, publishedAt) and updatedAt. The list is an array and additionally includes responseCount.
{
"success": true,
"replayed": false,
"data": {
"id": "00000000-0000-4000-8000-000000000001",
"title": "Applications",
"description": "Tell us about your goals.",
"theme": "base",
"showChrome": true,
"showPoweredBy": true,
"submissionMode": "partial_submission",
"identityFields": null,
"definition": {
"questions": [
{
"key": "goal",
"type": "long_text",
"label": "Your goal",
"required": true
}
]
},
"qualification": null,
"programIds": [],
"cohortIds": [],
"isActive": true,
"slug": "applications",
"publishedVersion": {
"id": "00000000-0000-4000-8000-000000000003",
"version": 1,
"publishedAt": "2026-10-13T09:00:00.000Z"
},
"updatedAt": "2026-10-13T09:00:00.000Z"
},
"correlationId": "00000000-0000-4000-8000-000000000002"
}
Removes public availability immediately, including anonymous resume. Historical versions stay immutable.
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.
