Edit a path session: Migration guide

This guide details how the Edit a path session endpoint has changed (previously known as updatePathSession in v1).

💡
Key changes

Endpoint structure: The v2 endpoint now requires both the pathId and sessionId as path parameters, whereas v1 only required the session_id.

Instructor management: Instructor assignment now uses unique IDs instead of email addresses and differentiates between a single mainInstructorId and multiple instructorIds.

Open access support: API v2 introduced enhanced support for open access registrations (including a new input parameter for user limits).

Documentation links

Here are the links to the API reference for:

Endpoint mapping

Here's the direct correlation between the v1 and v2 endpoint URLs:

API v1: /api/v1/paths/sessions/:session_id
API v2: /api/v2/paths/{pathId}/sessions/{sessionId}

Behavior changes

In API v1, if registrationRequest was not included in the query, validation of open access registrations was deactivated by default. In API v2, registrationRequestValidation explicitly uses disabled for this purpose, and new options like adminsAndManagers and adminsCoachesInstructorsManagers have been added for more granular control over registration validation.
API v1 automatically removed the user limit for self-registration if an API call was made to this endpoint, and there was no way to set or restore it via the API. API v2 introduces a userLimit body parameter, allowing explicit control over the maximum number of learners for self-enrollment.

Input changes

This section details the specific alterations to the input requirements between API versions.

API v1 input example

curl --location -g --request PATCH 'https://app.360learning.com/api/v1/paths/sessions/5bead809990d8862f3c514aa?company={{company}}&apiKey={{apiKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sessionName": "Onboarding session",
    "sessionOwnerGroup": "62bdbc00293a604543f44387",
    "instructorsMails": [
        "[email protected]",
        "[email protected]"
    ],
    "startDate": "2025-06-20T08:55:28.495Z",
    "endDate": "2025-06-20T08:55:28.495Z",
    "registrationRequest": "instructors"
}'

API v2 input example

curl --request PATCH \
     --url https://app.360learning.com/api/v2/paths/6854284dde395b87af7657c6/sessions/5bead809990d8862f3c514aa \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer your_access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "additionalInformation": "A0015221",
  "instructorIds": [
    "507f1f77bcf86cd799439011"
  ],
  "mainInstructorId": "507f1f77bcf86cd799439011",
  "name": "Onboarding session",
  "groupId": "507f1f77bcf86cd799439011",
  "registrationRequestValidation": "disabled",
  "startDate": "2025-06-20T08:55:28.495Z",
  "endDate": "2025-06-20T08:55:28.495Z",
  "userLimit": 0
}
'

Main input differences

Change type	API v1	API v2
Removed Body parameter	`instructorsMails`(Optional): Array of email addresses belonging to the instructors for this session, with the main instructor as the first item.	(Now handled by `mainInstructorId` and `instructorIds` using unique IDs)
Modified Body parameter	`sessionName` (Required): Name of the path session.	`name` (Optional): Renamed and now non-required.
Modified Body parameter	`sessionOwnerGroup` (Required): ID of the group owning the session.	`groupId` (Optional): Renamed and now non-required.
Modified Body parameter	`sessionAdditionalInformation` (Optional): Additional information for the path session.	`additionalInformation` (Optional): Modified name.
Modified Body parameter	`registrationRequest` (Optional): The registration request validation options for open access registrations. If `registrationRequest` is not included in the query, validation of open access registrations is deactivated by default. Possible values: `disabled`, `instructors`, `managers`.	`registrationRequestValidation`(Optional): Modified name. Possible values: `disabled`, `instructors`, `managers`, `adminsAndManagers`, and `adminsCoachesInstructorsManagers`.
Added Path parameter		`pathId` (Required): The unique ID of the path.
Added Body parameter		`mainInstructorId` (Optional): The unique ID of the main instructor.
Added Body parameter		`instructorIds` (Optional): List of unique IDs for co-instructors (array of strings, length ≤ 100).
Added Body parameter	(If a user limit for self-registration seats was already set, any API call to this endpoint would automatically remove it.)	`userLimit` (Optional): The maximum number of learners that can self-enroll in the path session.

Output changes

This section details the specific alterations to the successful output returned between API versions.

API v1 output example

{
  "status": "session_updated"
}

API v2 output example

{
  "mainInstructorId": "507f1f77bcf86cd799439011",
  "registrationRequestValidation": "disabled",
  "startDate": "2025-06-20T08:55:28.495Z",
  "endDate": "2025-06-20T08:55:28.495Z",
  "userLimit": 0,
  "_id": "507f1f77bcf86cd799439011",
  "createdAt": "2025-06-20T08:55:28.495Z",
  "groupId": "507f1f77bcf86cd799439011",
  "instructorIds": [
    "507f1f77bcf86cd799439011"
  ],
  "isAudienceBuilder": true,
  "modifiedAt": "2025-06-20T08:55:28.495Z",
  "name": "Onboarding session",
  "pathId": "507f1f77bcf86cd799439011",
  "translations": [
    {
      "lang": "fr",
      "published": true,
      "translatorIds": [
        "507f1f77bcf86cd799439011"
      ],
      "translatedFields": {
        "name": "Accueil des employés Session de juin"
      }
    }
  ],
  "additionalInformation": "A0015221",
  "automaticReenrollment": {
    "type": "certificationExpiryDate",
    "delayDays": 90
  },
  "rootSessionId": "507f1f77bcf86cd799439011"
}

Main output differences

API v2 provides a more detailed response object, including the full session details, whereas v1 returned only a status message.

Change type	API v1	API v2
Removed Output property	`status` (Required): Indicates the status of the session update (e.g., `"session_updated"`). Removed from the endpoint v2 version, not replaced.
Modified Success output	`200`: A simple JSON object with a status.	`200`: The successful response now returns a comprehensive JSON object containing the full details of the updated path session, including system-generated and associated properties.
Added Output property		`mainInstructorId` (Required): The unique ID of the main instructor of the path session.
Added Output property		`registrationRequestValidation` (Required): The registration request validation options for open access registrations.
Added Output property		`startDate` (Required): The date and time when the path session starts, in ISO 8601 UTC format.
Added Output property		`endDate` (Optional): The date and time when the path session ends, in ISO 8601 UTC format.
Added Output property		`userLimit` (Optional): The maximum number of learners that can self-enroll in the path session.
Added Output property		`_id` (Required): The unique ID of the path session.
Added Output property		`createdAt` (Required): The date and time when the path session was created, in ISO 8601 UTC format.
Added Output property		`groupId` (Required): The unique ID of the path session owner group. This replaces the input `sessionOwnerGroup` from v1.
Added Output property		`instructorIds` (Required): The list of unique IDs of the co-instructors of the path session.
Added Output property		`isAudienceBuilder` (Required): True if the path session is an audience builder session; false otherwise.
Added Output property		`modifiedAt`(Required): The date and time when the path session was last updated, in ISO 8601 UTC format.
Added Output property		`name` (Required): The title of the path session. This corresponds to v1's `sessionName`.
Added Output property		`pathId` (Required): The unique ID of the path the session belongs to.
Added Output property		`translations` (Required): An array of objects detailing the different translations available for the path session, including language, publication status, translator IDs, and translated fields. This is returned for all sessions to provide a complete multilingual data structure.
Added Output property		`additionalInformation` (Optional): The additional information of the path session. This corresponds to v1's `sessionAdditionalInformation`.
Added Output property		`automaticReenrollment` (Optional): The automatic reenrollment settings if enabled for the path session.
Added Output property		`rootSessionId` (Optional): The unique ID of the root session.