Create a path: Migration guide

This guide outlines the changes introduced in the Create a path v2 endpoint (previously known as createPath 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

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
API v2: /api/v2/paths

Behavior changes

The key behavior change is the separation of concerns. Instead of creating the path along with its steps, this endpoint will now be used to create the path structure only, deferring the creation of the steps to the endpoint Replace all steps.

Input changes

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

API v1 input example

curl --location -g 'https://{{host}}/api/v1/paths/' \
--data-raw '{
    "name": "Let'\''s Learn Together!",
    "description": "This is the description of the path.",
    "authorMails": [
        "[email protected]"
    ],
    "ownerGroup": "6234e14c9ce27e1cbe0cebb9",
    "steps": [
        {
            "id": "62a6e7d4d4327f989d6ead8a",
            "type": "course"
        },
        {
          "type": "email",
          "bodyHtml": "Libres et isolés sur la surface de la terre, las de s'\''y voir sans cesse dans un état de guerre continuel, fatigués d'\''une liberté que l'\''incertitude de la conserver rendait inutile, les hommes en sacrifièrent une partie pour jouir sûrement et en paix du reste.",
          "title": "Beccaria ftw",
          "headlineHtml" : "Libres et isolés",
          "mainCtaText": "Go to path",
          "scheduling": {
              "relativeTo": "enrollmentDate",
              "relativity": 3,
              "condition": "successful"
          },
          "attachmentIds": ["62a6e7d4d4327f989d6ead8a", "62a6e7d4d4327f989d6ead8b"],
          "coverMediaId": "62a6e7d4d4327f989d6ead8c"
        },
        {
          "type": "assessment",
          "groupId": "62a6e7d4d4327f989d6ead8t",
          "assessmentName": "Build a computer",
          "learnersInstructions": "Do it right.",
          "assessorType": "instructors",
          "assessorInstructions": "Be ruthless.",
          "scoring": {
              "scoreMode":  "scored",
              "minScore": 60
           },
          "isExamination": true
        },
        {
          "type": "classroom",
          "name": "name classroom",
          "medias": [],
          "message": "message",
          "trainingObjective": "trainingObjective",
          "options":{
            "isAutoRegistrationEnabled":false,
            "selfRegistration":{"enabled":true,"delay":{"unit":"day","value":5}},
            "attendanceSheets": { "number": 2, "unit": "day" }
          }
        }
    ],
    "linear": true,
    "mandatoryReplay": false,
    "sendAutomatedReminders": false,
    "defaultLang": "en",
    "sourceLang": "en"
}'

API v2 input example

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

Main input differences

Change type	API v1	API v2
Removed Body parameter	`steps` : Array of step objects.	This parameter is removed from v2. Use Replace all steps to build path' steps.
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.
Removed Body parameter	`certificate` : Id of the certificate.	This parameter is removed from v2.
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	`ownerGroup` : Id of the group owning the path.	`groupId`: (Required) The unique ID of the owner group of the path.
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_created",
  "_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 created path, while API v1 was just acknowledging the path creation 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`
Removed Error code	`400 - invalid_classroom_name`
Removed Error code	`400 - invalid_training_objective`
Removed Error code	`400 - invalid_optional_content`
Removed Error code	`400 - invalid_relativeDueDate`
Removed Error code	`400 - invalid_automaticRegistration`
Removed Error code	`400 - invalid_selfRegistration`
Removed Error code	`400 - invalid_selfRegistrationCutoff`
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.