Create a path session: Migration guide

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

💡
Key changes

Enhanced input: API v2 supports more input parameters for path session creation, including options for registration validation and user limits, offering greater control and detail upon initial creation.

Automated group assignment: Unlike v1 where you explicitly provided the session owner group, API v2 automatically determines the groupId based on the main instructor's group affiliations, streamlining the creation process.

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

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/:pathId/sessions/
API v2: /api/v2/paths/{pathId}/sessions

Behavior changes

In API v2, the session owner group (groupId in the output) is no longer provided as an explicit input parameter. Instead, the session owner group is automatically determined by the backend based on the mainInstructorId provided in the request body. The selection follows this logic:

Identify eligible groups: The system retrieves all groups where the mainInstructorId has at least the author role.
Group selection logic: If eligible groups exist, they are sorted, and the first one in the sorted list is selected as the session owner group. The sorting criteria are applied in this order:
- Public groups first.
- Next, groups are sorted by their hierarchy depth in ascending order (meaning groups higher up in the organizational tree are chosen first).
- Finally, groups are sorted by the number of users they contain in descending order (larger groups come first).
Fallback: If the mainInstructorId does not have the author role in any group, the system defaults to using the path's owner group as the session owner group.

Input changes

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

API v1 input example

curl --location -g 'https://app.360learning.com/api/v1/paths/:pathId/sessions/?company={{company}}&apiKey={{apiKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
        "sessionName": "Employee Onboarding July Session",
        "sessionOwnerGroup": "624c5526204fc7207e603ea6",
        "instructorsMails": [
            "[email protected]"
        ],
        "startDate": "2025-07-01T13:00:00.812Z",
        "endDate": "2025-07-31T13:00:00.812Z",
        "sessionAdditionalInformation": "A0015221"
}'

API v2 input example

curl --request POST \
     --url https://app.360learning.com/api/v2/paths/6853f6de567dc5f80528f80d/sessions \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer your_access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "registrationRequestValidation": "disabled",
  "mainInstructorId": "647098a731a809ed36889ed1",
  "name": "Employee Onboarding July Session",
  "additionalInformation": "A0015221",
  "startDate": "2025-07-01T13:00:00.812Z",
  "endDate": "2025-07-31T13:00:00.812Z",
  "userLimit": 30,
  "instructorIds": [
    "67769f32553f1e9171a186c0"
  ]
}
'

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)
Removed Body parameter	`sessionOwnerGroup`(Required): ID of the group owning the session.	(Not directly replaced as an input parameter; the session owner ID is now an output property (`groupId`), automatically determined by the `mainInstructorId` as detailed in the Behavior changes section).
Modified Body parameter	`sessionName`(Required): Name of the session.	`name` (Required): Modified name.
Modified Body parameter	`sessionAdditionalInformation` (Optional): Additional information about the session.	`additionalInformation` (Optional): Modified name.
Added Body parameter		`mainInstructorId` (Required): 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		`userLimit` (Optional): Maximum number of learners for self-enrollment (integer, ≥ 1).
Added Body parameter		`registrationRequestValidation` (Required): Options for open access registration validation (`disabled`, `instructors`, `managers`, `adminsAndManagers`, `adminsCoachesInstructorsManagers`)

Output changes

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

API v1 output example

{
    "status": "session_created",
    "_id": "6853e37f9bd3525326e240f6"
}

API v2 output example

{
  "_id": "68540b86685753a2d27f42db",
  "createdAt": "2025-06-19T13:07:18.000Z",
  "groupId": "6776986afff311b995274b73",
  "instructorIds": [
    "67769f32553f1e9171a186c0"
  ],
  "isAudienceBuilder": true,
  "mainInstructorId": "647098a731a809ed36889ed1",
  "modifiedAt": "2025-06-19T13:07:18.516Z",
  "name": "Employee Onboarding July Session",
  "pathId": "6853f6de567dc5f80528f80d",
  "registrationRequestValidation": "disabled",
  "startDate": "2025-07-01T13:00:00.812Z",
  "additionalInformation": "A0015221",
  "endDate": "2025-07-31T13:00:00.812Z",
  "userLimit": 30,
  "translations": []
}

Main output differences

API v2's successful response for session creation now provides a comprehensive object containing full details of the newly created path session, including system-generated and associated properties, whereas API v1 only returned a status and ID.

Change type	API v1	API v2
Removed Output property	`status` (Required): Indicates the status of the session creation (e.g., `"session_created"`). Removed from endpoint v2 version, not replaced.
Modified Success output	`200`: A simple JSON object with a status and the session ID.	`200`: The successful response now returns a comprehensive JSON object containing the full details of the created 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		`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, and is automatically determined by the `mainInstructorId` as detailed in the Behavior changes section).
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.