Move a lesson to another course

POST /api/v1/lessons/{lessonId}/move

Moves a lesson to another course of the same program, at the rank you give. targetCourseId: null takes it out of every course and files it among the loose lessons of the program — a legal state, not an accident.

targetPosition is required: without it the lesson would land at a rank nobody chose.

Authorization

Path parameters

Request headers

Request body

{"targetCourseId": "9f2c0a1e-0000-4000-8000-000000000000", "targetPosition": 2}

Example

curl -X POST "$COHORTE_API_BASE_URL/api/v1/lessons/$LESSON_ID/move" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"targetCourseId":"'"$COURSE_ID"'","targetPosition":2}'

Response

• 200 OK — the lesson, in its new course and rank.
• 400 Bad Request — missing Idempotency-Key, invalid JSON, targetCourseId omitted (send null to leave every course), a position out of range, or a target course from another 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 program is archived.
• 404 Not Found — the lesson is unknown or belongs to another school.

Example response

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "5d9f3a60-1c2b-4e7d-8f4a-6b7c8d9e0f1a",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "courseId": "6a1d4c27-2e9b-4d3a-a8f6-1b2c3d4e5f60",
    "sectionId": null,
    "title": "Structure a discovery call",
    "content": "## Why it matters\n\nA discovery call decides the rest of the sale.",
    "videoUrl": "https://vimeo.com/912440188",
    "status": "published",
    "position": 2,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-04T17:12:00.000Z"
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

Notes

• Moving a lesson out of a course also takes it out of its section: a section belongs to one course.

Related

• Move a lesson into a section
• Reorder the lessons of a program

With Idempotency-Key, retries of the identical target and payload do not write another mutation, audit or event. A different intention under that key returns 409. Results describe the currently authorized resource state.