Ask a question

POST /api/v1/questions

Asks a question as the bearer of the key. The author is never read from the body. The bearer must follow programId with an enrollment that is pending or active — find it with the bearer's enrollments. The question starts to_do, assigned to the oldest OWNER of the school.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed only when enrolled in the program
`ADMIN`	Allowed only when enrolled in the program
`MEMBER`	Allowed when enrolled in the program; otherwise refused — `403`

Requirement	Rule for this endpoint
Business role	None
Resource scope	Program of the key's organization
Participation	An enrollment of the bearer in `programId`, `pending` or `active` — `paused` and closed enrollments are refused
Resource state	None

Request headers

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

Request body

Field	Type	Required	Nullable	Description
`programId`	UUID	yes	no	A program the bearer follows
`title`	string	yes	no	1 to 200 characters
`body`	string	no	no	HTML or Markdown description, up to 10000 characters; absent or without visible text, stored as `""`

json

{
  "programId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
  "title": "Where should validation live?",
  "body": "I hesitate between the server action and the service."
}

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/questions" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: question-validation-001" \
  -H "Content-Type: application/json" \
  -d '{"programId":"3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b","title":"Where should validation live?","body":"I hesitate between the server action and the service."}'

Response

201 Created — the question, to_do.
200 OK — replayed: true: the key was already used, the original question comes back.
400 Bad Request — missing Idempotency-Key, invalid JSON, a field out of bounds, or a school without an owner to receive it.
401 Unauthorized — missing, unknown or expired key.
403 Forbidden — the bearer does not follow this program with an open enrollment.

Response fields

The fields of one item of List received questions.

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "programId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
    "programName": "Agentic AI Developer",
    "title": "Where should validation live?",
    "body": "I hesitate between the server action and the service.",
    "status": "to_do",
    "authorUserId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "authorName": "Léa Vasseur",
    "assigneeUserId": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
    "assigneeName": "Mike Codeur",
    "answer": null,
    "cancellation": null,
    "createdAt": "2026-10-18T10:00:00.000Z",
    "updatedAt": "2026-10-18T10:00:00.000Z"
  },
  "correlationId": "c0ffee00-1111-4222-8333-444455556666"
}

Notes

Asking records the question, its audit line and a video_question.asked event. No email and no in-app notification are sent.
A replay with the same Idempotency-Key creates no second question.

POST /api/v1/questions

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed only when enrolled in the program
`ADMIN`	Allowed only when enrolled in the program
`MEMBER`	Allowed when enrolled in the program; otherwise refused — `403`

Requirement	Rule for this endpoint
Business role	None
Resource scope	Program of the key's organization
Participation	An enrollment of the bearer in `programId`, `pending` or `active` — `paused` and closed enrollments are refused
Resource state	None

Request headers

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

Request body

Field	Type	Required	Nullable	Description
`programId`	UUID	yes	no	A program the bearer follows
`title`	string	yes	no	1 to 200 characters
`body`	string	no	no	HTML or Markdown description, up to 10000 characters; absent or without visible text, stored as `""`

json

{
  "programId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
  "title": "Where should validation live?",
  "body": "I hesitate between the server action and the service."
}

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/questions" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: question-validation-001" \
  -H "Content-Type: application/json" \
  -d '{"programId":"3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b","title":"Where should validation live?","body":"I hesitate between the server action and the service."}'

Response

201 Created — the question, to_do.
200 OK — replayed: true: the key was already used, the original question comes back.
400 Bad Request — missing Idempotency-Key, invalid JSON, a field out of bounds, or a school without an owner to receive it.
401 Unauthorized — missing, unknown or expired key.
403 Forbidden — the bearer does not follow this program with an open enrollment.

Response fields

The fields of one item of List received questions.

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "programId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
    "programName": "Agentic AI Developer",
    "title": "Where should validation live?",
    "body": "I hesitate between the server action and the service.",
    "status": "to_do",
    "authorUserId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "authorName": "Léa Vasseur",
    "assigneeUserId": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
    "assigneeName": "Mike Codeur",
    "answer": null,
    "cancellation": null,
    "createdAt": "2026-10-18T10:00:00.000Z",
    "updatedAt": "2026-10-18T10:00:00.000Z"
  },
  "correlationId": "c0ffee00-1111-4222-8333-444455556666"
}

Notes

Asking records the question, its audit line and a video_question.asked event. No email and no in-app notification are sent.
A replay with the same Idempotency-Key creates no second question.

Ask a question

Ask a question

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