Edit a path: Migration guide

This guide outlines the changes introduced in the Edit a path v2 endpoint (previously known as updatePath in v1).

💡
Key changes

Path created without steps: Fostering the concept of granularity, the API v2 endpoint focuses on creating the main shell of a path, without its steps. To add steps to the newly created path, you should use the endpoint Replace all steps

HTTP Content-Type: The v2 endpoint consumes multipart/form-data as content-type (letting you upload a file to be used as the path's cover picture) whereas v1 consumed application/json

HTTP method: The v2 endpoint uses the PATCH method whereas v1 used PUT method.

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

Input changes

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

API v1 input example

curl --location -g --request PUT 'https://{{host}}/api/v1/paths/65736c4f43842214f65eebb0?company={{company})&apiKey={{apiKey}}' \
--data-raw '{
    "name": "Let'\''s Learn Together!",
    "description": "This is the description of the path.",
    "authorMails": [
        "[email protected]"
    ],
    "ownerGroup": "6234e14c9ce27e1cbe0cebb9",
    "linear": true,
    "mandatoryReplay": false,
    "sendAutomatedReminders": false,
    "defaultLang": "en",
    "sourceLang": "en"
}'

API v2 input example

curl --request PATCH \
     --url https://app.360learning.com/api/v2/paths/507f1f77bcf86cd799439011 \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'content-type: multipart/form-data' \
     --form groupId=507f1f77bcf86cd799439011 \
     --form 'name=Employee Onboarding' \
     --form 'description=This path will teach you how to onboard a new employee!' \
     --form authorId=507f1f77bcf86cd799439011 \
     --form coAuthorIds=507f1f77bcf86cd799439011 \
     --form min=0 \
     --form max=2 \
     --form 'additionalInformation=Training content 203' \
     --form defaultLang=en \
     --form linearProgression=true \
     --form mandatoryReplay=true \
     --form displayForum=false \
     --form displayClassroomMessages=false \
     --form automatedReminders=true \
     --form notificationOnStepCreation=false \
		 --form 'coverPicture=data:image/jpeg;name=photo-1598875793784-55488654fb0b.jpeg;base64,/9j/4AAQSkZJRg[...] \

Main input differences

Change type	API v1	API v2
Removed Body parameter	`skills` : Id of the skills.	This parameter is removed from v2. Use Replace all tags in a path to input path' tags.
Removed Body parameter	`sourceLang` : Source language of the path.	This parameter is removed from v2. `defaultLang` will be used.
Modified Body parameter	`authorMails` : List of authors: main author (first one), co-authors (the rest) for this path, provided by their emails inside an array.	`authorId`: (Required) The unique ID of the main author of the path. `coAuthorIds`: (Required/Optional) The list of co-author IDs in an array.
Modified Body parameter	`uploadedImage` : ID of the media to be used as path's cover image.	`coverPicture (type = File)`: (Optional) The file to be uploaded and used as the cover picture of the path. `coverPicture (type = String)`: (Optional) The unique ID of the media to be used as the cover picture of the path.
Added Body parameter		`notificationOnStepCreation` (Optional): True if an email notification is sent to all learners when a new step is added, updating their path status to On time and moving the path back to the Ongoing tab on their homepage; false otherwise.
Added Header parameter		`360-api-version` (Required): API version identifier. Example: `v2.0`.

Output changes

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

API v1 output example

{
  "status": "path_updated",
  "_id": "59f1fd5cb91bedcf09c77063"
}

API v2 output example

{
  "authorId": "507f1f77bcf86cd799439011",
  "groupId": "507f1f77bcf86cd799439011",
  "estimatedWeeklyCommitment": {
    "min": 0,
    "max": 0
  },
  "_id": "507f1f77bcf86cd799439011",
  "coAuthorIds": [
    "507f1f77bcf86cd799439011"
  ],
  "createdAt": "2025-12-22T15:46:53.795Z",
  "defaultLang": "bg",
  "modifiedAt": "2025-12-22T15:46:53.795Z",
  "name": "Employee Onboarding",
  "options": {
    "linearProgression": true,
    "mandatoryReplay": true,
    "displayForum": true,
    "displayClassroomMessages": true,
    "automatedReminders": true,
    "notificationOnStepCreation": true
  },
  "sourceLang": "bg",
  "status": "archived",
  "steps": [],
  "translations": [],
  "additionalInformation": "Training content 203",
  "coverPicture": "507f1f77bcf86cd799439011",
  "description": "This path will teach you how to onboard a new employee!",
  "estimatedDuration": {
    "unit": "day",
    "value": 0
  }
}

Main output differences

The response is completely different as the API v2 version returns the newly updated path, while API v1 was just acknowledging the path edition and returning the _id, so please refer to the Retrieve a path: Migration guide for more information.

Change type	API v1	API v2
Removed Error code	`404 - group_not_found`
Removed Error code	`404 - path_not_found`
Removed Error code	`400 - invalid_path_name`
Removed Error code	`400 - invalid_path_owner_group`
Removed Error code	`400 - invalid_authors`
Removed Error code	`400 - invalid_skills`
Removed Error code	`400 - invalid_steps`
Removed Error code	`400 - invalid_certificate`
Removed Error code	`400 - invalid_start_date`
Removed Error code	`400 - invalid_end_date`
Removed Error code	`400 - invalid_instructors`
Added Error code		`400 - mainAuthorAsCoAuthor`: The main author is present in the co-authors list.
Added Error code		`400 - mediaNotFound`: The given media ID does not correspond to any existing image media.
Added Error code		`404 - groupNotFound`: The given groupId does not correspond to any existing group.
Added Error code		`404 - usersNotFound`: At least one of the given users does not correspond to any existing and non-deleted user.
Added Error code		`404 - pathNotFound`: The given pathId does not correspond to any existing path.