Create a space

POST /api/v1/community/spaces

Opens a community space. A space is scoped to a program — everyone enrolled in it, whatever their cohort — or to a cohort. A program discussion is a program-scoped space.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — `403`

Requirement	Rule for this endpoint
Business role	None
Resource scope	The program or cohort belongs to the key's organization
Participation	None
Resource state	The program is not archived; the cohort is not `completed` or `archived`

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this organization
`Idempotency-Key`	yes	Stable key for this space; a replay returns the first result
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`name`	string	yes	no	3 to 80 characters
`scopeType`	string	yes	no	`program` or `cohort`
`scopeTargetId`	UUID	yes	no	The program or the cohort, per `scopeType`

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/community/spaces" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: space-autumn-cohort" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Autumn cohort — questions",
    "scopeType": "cohort",
    "scopeTargetId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b"
  }'

Response

201 Created — the space, active, last in the school's order.
200 OK — replayed: true: the key was already used, the original space comes back.
400 Bad Request — missing Idempotency-Key, invalid JSON, a name out of bounds, an unknown scope type, an archived program or a closed cohort.
401 Unauthorized — missing, unknown or expired key.
403 Forbidden — the bearer is not OWNER or ADMIN.
404 Not Found — the program or cohort is unknown or belongs to another school.

Response fields

Field	Type	Description
`data.id`	UUID	Space id
`data.name`	string	Space name
`data.scopeType`	string	`program` or `cohort`
`data.scopeTargetId`	UUID	The program or the cohort
`data.status`	string	`active` at creation
`data.position`	integer	Rank in the school's list of spaces
`data.createdAt`	string	ISO 8601

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "Autumn cohort — questions",
    "scopeType": "cohort",
    "scopeTargetId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
    "status": "active",
    "position": 3,
    "createdAt": "2026-10-01T08:30:00.000Z"
  },
  "correlationId": "c0ffee00-1111-4222-8333-444455556666"
}

Notes

Renaming, reordering and archiving a space are done from the screens today.

POST /api/v1/community/spaces

Opens a community space. A space is scoped to a program — everyone enrolled in it, whatever their cohort — or to a cohort. A program discussion is a program-scoped space.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — `403`

Requirement	Rule for this endpoint
Business role	None
Resource scope	The program or cohort belongs to the key's organization
Participation	None
Resource state	The program is not archived; the cohort is not `completed` or `archived`

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this organization
`Idempotency-Key`	yes	Stable key for this space; a replay returns the first result
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`name`	string	yes	no	3 to 80 characters
`scopeType`	string	yes	no	`program` or `cohort`
`scopeTargetId`	UUID	yes	no	The program or the cohort, per `scopeType`

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/community/spaces" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: space-autumn-cohort" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Autumn cohort — questions",
    "scopeType": "cohort",
    "scopeTargetId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b"
  }'

Response

201 Created — the space, active, last in the school's order.
200 OK — replayed: true: the key was already used, the original space comes back.
400 Bad Request — missing Idempotency-Key, invalid JSON, a name out of bounds, an unknown scope type, an archived program or a closed cohort.
401 Unauthorized — missing, unknown or expired key.
403 Forbidden — the bearer is not OWNER or ADMIN.
404 Not Found — the program or cohort is unknown or belongs to another school.

Response fields

Field	Type	Description
`data.id`	UUID	Space id
`data.name`	string	Space name
`data.scopeType`	string	`program` or `cohort`
`data.scopeTargetId`	UUID	The program or the cohort
`data.status`	string	`active` at creation
`data.position`	integer	Rank in the school's list of spaces
`data.createdAt`	string	ISO 8601

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "Autumn cohort — questions",
    "scopeType": "cohort",
    "scopeTargetId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
    "status": "active",
    "position": 3,
    "createdAt": "2026-10-01T08:30:00.000Z"
  },
  "correlationId": "c0ffee00-1111-4222-8333-444455556666"
}

Notes

Renaming, reordering and archiving a space are done from the screens today.

Create a space

Create a space

Authorization

Request headers

Request body

Example

Response

Response fields

Example response

Notes

Related

Authorization

Request headers

Request body

Example

Response

Response fields

Example response

Notes

Related