Update a course

PATCH /api/v1/courses/{courseId}

Sets the identity of a course: its name, its URL slug and its cover. The three fields travel together, and null erases. That is what distinguishes this command from Rename a course, which is deliberately narrow: renaming must not be able to wipe a URL somebody already shared.

Authorization

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

Requirement	Rule for this endpoint
Business role	None — a course is changed by whoever may change its program
Resource scope	Course of the school attached to the API key
Resource state	An archived course, or a course of an archived program, answers `403`

Path parameters

Parameter	Type	Required	Description
`courseId`	UUID	yes	Course visible from the key's school

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this school
`Idempotency-Key`	yes	Stable key for this change
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`name`	string	yes	no	3 to 100 characters
`slug`	string	yes	yes	Lowercase letters, digits and dashes, up to 100 characters. `null` clears it
`image`	string	yes	yes	Cover URL, up to 2048 characters. `null` clears it

An omitted slug or image is refused with 400: the three fields are the identity of the course, this command submits it whole, and only an explicit null clears a field.

json

{
  "name": "Week 1 — Your first agent",
  "slug": "week-1-first-agent",
  "image": "https://files.example.com/covers/week-1.png"
}

Example

bash

curl -X PATCH "$COHORTE_API_BASE_URL/api/v1/courses/$COURSE_ID" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Week 1 — Your first agent","slug":"week-1-first-agent","image":null}'

Response

200 OK — the course, as it now stands.
400 Bad Request — missing Idempotency-Key, invalid JSON, slug or image omitted, a malformed slug, or a slug already used in the program.
401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
403 Forbidden — the bearer is not OWNER or ADMIN, or the course is archived.
404 Not Found — the course is unknown or belongs to another school.

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "3b8e2d41-7a6c-4f1e-8b25-9c0d1e2f3a4b",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "name": "Week 1 — Your first agent",
    "slug": "week-1-first-agent",
    "image": null,
    "position": 1,
    "status": "active",
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-04T17:12:00.000Z"
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

PATCH /api/v1/courses/{courseId}

Authorization

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

Requirement	Rule for this endpoint
Business role	None — a course is changed by whoever may change its program
Resource scope	Course of the school attached to the API key
Resource state	An archived course, or a course of an archived program, answers `403`

Path parameters

Parameter	Type	Required	Description
`courseId`	UUID	yes	Course visible from the key's school

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this school
`Idempotency-Key`	yes	Stable key for this change
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`name`	string	yes	no	3 to 100 characters
`slug`	string	yes	yes	Lowercase letters, digits and dashes, up to 100 characters. `null` clears it
`image`	string	yes	yes	Cover URL, up to 2048 characters. `null` clears it

An omitted slug or image is refused with 400: the three fields are the identity of the course, this command submits it whole, and only an explicit null clears a field.

json

{
  "name": "Week 1 — Your first agent",
  "slug": "week-1-first-agent",
  "image": "https://files.example.com/covers/week-1.png"
}

Example

bash

curl -X PATCH "$COHORTE_API_BASE_URL/api/v1/courses/$COURSE_ID" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Week 1 — Your first agent","slug":"week-1-first-agent","image":null}'

Response

200 OK — the course, as it now stands.
400 Bad Request — missing Idempotency-Key, invalid JSON, slug or image omitted, a malformed slug, or a slug already used in the program.
401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
403 Forbidden — the bearer is not OWNER or ADMIN, or the course is archived.
404 Not Found — the course is unknown or belongs to another school.

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "3b8e2d41-7a6c-4f1e-8b25-9c0d1e2f3a4b",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "name": "Week 1 — Your first agent",
    "slug": "week-1-first-agent",
    "image": null,
    "position": 1,
    "status": "active",
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-04T17:12:00.000Z"
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

Update a course

Update a course

Authorization

Path parameters

Request headers

Request body

Example

Response

Example response

Related

Authorization

Path parameters

Request headers

Request body

Example

Response

Example response

Related