Menu
shell

Introduction

Welcome to the Lessonly API documentation! First you will need to get an API key by signing into your account, navigating to the company settings page and clicking “Show API credentials”.

Currently we only have language bindings for shell, however we are open to providing libraries in other languages. Contact us at info@lessonly.com to let us know what libraries you would like to see.

Authentication

The following pattern authorizes an API request:

# With shell, you can just pass the correct header with each request
curl -u "DOMAIN:API_KEY" "api_endpoint_here"

Make sure to replace DOMAIN with your Lessonly domain and API_KEY with your personal API key.

Lessonly uses API keys and basic HTTP authorization to allow access to the API. All API requests must be sent over HTTPS. You can register a new Lessonly API key by signing into Lessonly and navigating to the settings page. If you do not see the API key link, you may need to request for the feature to be activated: here.

Users

List Users

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/users"

The above command returns JSON structured like this:

{
  "type": "users",
  "resource_type": "user",
  "total_users": 2000,
  "page": 1,
  "per_page": 2,
  "total_pages": 1000,
  "users":[
      {
        "id": 1,
        "name": "User Name",
        "email": "email1@example.com",
        "role": "learner",
        "ext_uid": "ABC123",
        "archived_at": null,
        "archived_by_user_id": null,
        "job_title": "Account Executive",
        "business_unit": "Global",
        "department": "Sales",
        "location": "Illinois",
        "hire_date": "2014-12-25",
        "manager_name": "Mary Doe",
        "custom_user_field_data": [
          {
            "id": 1,
            "custom_user_field_id": 1,
            "name": "Custom Field Name 1",
            "value": "Custom Value 1"
          }
        ]
      },
      {
        "id": 2,
        "name": "User Name",
        "email": "email2@example.com",
        "role": "learner",
        "ext_uid": "DEF456",
        "archived_at": null,
        "archived_by_user_id": null,
        "job_title": "Engineer",
        "business_unit": "Global",
        "department": "IT",
        "location": "California",
        "hire_date": "2014-12-25",
        "manager_name": "Jane Doe",
        "custom_user_field_data": [
          {
            "id": 2,
            "custom_user_field_id": 1,
            "name": "Custom Field Name 1",
            "value": "Custom Value 2"
          }
        ]
      }
    ]
}

This endpoint retrieves all users.

HTTP Request

GET https://api.lessonly.com/api/v1/users?filter[email]=email@example.com

Query Parameters

Parameter Required Type Description
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 5000. Numbers > 5000 are ignored and 5000 will be returned.
filter no String Specified user filter for users list. Supported filters are email, ext_uid, sso_id, and custom_user_field. The SSO ID is the provider ID that we store from a successful SSO request. The format for custom_user_field is filter[custom_user_field][FIELD_ID]=FIELD_VALUE.

Show User Details

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/users/:user_id"

The above command returns JSON structured like this:

{
  "type": "user",
  "resource_type": "user",
  "id": 1,
  "name": "Test User",
  "email": "test@test.com",
  "role": "learner",
  "ext_uid": "ABC123",
  "job_title": "Account Executive",
  "business_unit": "Global",
  "department": "Sales",
  "location": "Illinois",
  "hire_date": "2014-12-25",
  "manager_name": "Mary Doe",
  "custom_user_field_data": [
    {
      "id": 1,
      "custom_user_field_id": 1,
      "name": "Custom Field Name 1",
      "value": "Custom Value 1"
    }
  ],
  "archived_at": null,
  "archived_by_user_id": null
}

This endpoint retrieves all the user’s details including their custom field data. To see the users groups see the user group endpoint.

HTTP Request

GET https://api.lessonly.com/api/v1/users/:user_id

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.

Show User Learning Library Statistics

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/users/:user_id/learning_library_statistics"

The above command returns JSON structured like this:

{
  "type": "user_learning_library_statistics",
  "learning_library_statistics": {
     "total_completed": 3,
     "total_views": 50,
     "unique_lesson_and_course_views": 10
  }
}

This endpoint retrieves all the user’s learning library statistics. Note: this endpoint is available only to customers whose plan includes the Learning Library

HTTP Request

GET https://api.lessonly.com/api/v1/users/:user_id/learning_library_statistics

Query Parameters

Paramter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.

Create User

curl -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/users"

The following are sample parameters for this request:

{
  "name": "User Name",
  "email": "email@example.com",
  "role": "learner",
  "ext_uid": "ABC123",
  "job_title": "Account Executive",
  "business_unit": "Global",
  "department": "Sales",
  "location": "Illinois",
  "hire_date": "2014-12-25",
  "manager_name": "Mary Doe",
  "custom_user_fields": [
    {
      "custom_user_field_id": 1,
      "value": "Custom Value 1"
    },
    {
      "name": "Custom Field Name 2",
      "value": "Custom Value 2"
    }
  ]
}

A successful post returns JSON consisting of the show user detail response

 {
  "type": "create_user",
  "resource_type": "user",
  "id": 1,
  "name": "User Name",
  "email": "email@example.com",
  "role": "learner",
  "ext_uid": "ABC123",
  "job_title": "Account Executive",
  "business_unit": "Global",
  "department": "Sales",
  "location": "Illinois",
  "hire_date": "2014-12-25",
  "manager_name": "Mary Doe",
  "custom_user_field_data":
    [
      {
        "id": 1,
        "custom_user_field_id": 1,
        "name": "Custom Field Name 1",
        "value": "Custom Value 1"
      },
      {
        "id": 2,
        "custom_user_field_id": 2,
        "name": "Custom Field Name 2",
        "value": "Custom Value 2"
      }
    ]
}

This endpoint allows you to create a user in the api.

HTTP Request

POST https://api.lessonly.com/api/v1/users/ -d params

Query Parameters

Parameter Required Type Description
name yes String User full name. Cannot begin with a space and the following characters are restricted: `!@#\$%^&*+=()|[];
email yes String User Email
role yes String User role. Options: admin, manager, creator, learner
ext_uid no String The user’s ID in another system, useful for linking data.
job_title no String User job title
business_unit no String User business unit
department no String User department
location no String User location
hire_date no String User hire date. Must be an ISO8601 formatted date (YYYY-MM-DD).
manager_name no String User manager name
notify no String Whether or not to notify the user. Passing ‘false’ will not send an email notification to the user that their account has been created. Defaults to ‘true’.
custom_user_fields no Array Custom user fields for the user. Hashes must contain a “value” and either a “customer_user_field_id” or “name”. If an unknown custom user field “name” is provided, a new custom user field will be created with that name.

Update User

curl -X PUT -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/users/:user_id"

The following are sample parameters for this request.

{
  "name": "User Name",
  "email": "email@example.com",
  "role": "learner",
  "ext_uid": "ABC123",
  "job_title": "Account Executive",
  "business_unit": "Global",
  "department": "Sales",
  "location": "Illinois",
  "hire_date": "2014-12-25",
  "manager_name": "Mary Doe",
  "custom_user_fields": [
    {
      "custom_user_field_id": 1,
      "value": "Custom Value 1"
    },
    {
      "name": "Custom Field Name 2",
      "value": "Custom Value 2"
    }
  ]
}

A successful update returns JSON consisting of the show user detail response

 {
  "type": "update_user",
  "resource_type": "user",
  "id": 1,
  "name": "User Name",
  "email": "email@example.com",
  "role": "learner",
  "ext_uid": "ABC123",
  "job_title": "Account Executive",
  "business_unit": "Global",
  "department": "Sales",
  "location": "Illinois",
  "hire_date": "2014-12-25",
  "manager_name": "Mary Doe",
  "custom_user_field_data":
    [
      {
        "id": 1,
        "custom_user_field_id": 1,
        "name": "Custom Field Name 1",
        "value": "Custom Value 1"
      },
      {
        "id": 2,
        "custom_user_field_id": 2,
        "name": "Custom Field Name 2",
        "value": "Custom Value 2"
      }
    ]
}

This endpoint allows you to update a user in the api.

HTTP Request

PUT https://api.lessonly.com/api/v1/users/:user_id -d params

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.
name no String User name to change user to
email no String User Email to change user to
role no String User role to change user to. Options: admin, manager, creator, learner
ext_uid no String The user’s ID in another system, useful for linking data.
job_title no String User job title
business_unit no String User business unit
department no String User department
location no String User location
hire_date no String User hire date. Must be an ISO8601 formatted date (YYYY-MM-DD).
manager_name no String User manager name
custom_user_fields no Array Custom user fields for the user. Hashes must contain a “value” and either a “customer_user_field_id” or “name”. If an unknown custom user field “name” is provided, a new custom user field will be created with that name. If the user does not have a value for the specified customer user field it will be added, otherwise it will be updated to the specified “value”.

Archive User

curl -X PUT -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/users/:user_id/archive"

The above command returns JSON structured like this:

{
    "archived_at": "2016-10-13T09:34:24.151-04:00",
    "archived_by_user_id": null,
    "custom_user_field_data": [],
    "email": "learner@example.com",
    "ext_uid": null,
    "job_title": "Account Executive",
    "business_unit": "Global",
    "department": "Sales",
    "location": "Illinois",
    "hire_date": "2014-12-25",
    "manager_name": "Mary Doe",
    "id": 739413,
    "name": "Beta Learner",
    "resource_type": "user",
    "role": "learner",
    "type": "user"
}

This endpoint allows the archiving of a single user.

HTTP Request

PUT https://api.lessonly.com/api/v1/users/:user_id/archive

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to archive. The company must have access to the user.

Restore User

curl -X PUT -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/users/:user_id/restore"

The above command returns JSON structured like this:

{
    "archived_at": null,
    "archived_by_user_id": null,
    "custom_user_field_data": [],
    "email": "learner@example.com",
    "ext_uid": null,
    "job_title": "Account Executive",
    "business_unit": "Global",
    "department": "Sales",
    "location": "Illinois",
    "hire_date": "2014-12-25",
    "manager_name": "Mary Doe",
    "id": 739413,
    "name": "Beta Learner",
    "resource_type": "user",
    "role": "learner",
    "type": "user"
}

This endpoint allows the restoring of a single archived user.

HTTP Request

PUT https://api.lessonly.com/api/v1/users/:user_id/restore

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to restore. The company must have access to the user.

Delete User

curl -X DELETE -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/users/:user_id"

A successful update returns JSON consisting of the id of the deleted user

{
  "type": "delete_user",
  "id": "3"
}

This endpoint allows you to delete a user in the API.

HTTP Request

DELETE https://api.lessonly.com/api/v1/users/:user_id

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to delete. The company must have access to the user.

User Groups

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/users/:user_id/groups"

The above command returns JSON structured like this:


{"type": "user_groups",
 "memberships":
    [
        {"id": 1, "name": "Test Group"},
        {"id": 3, "name": "Test Group 3"},
    ],
  "managing":
    [
        {"id": 1, "name": "Test Group5"},
    ]
}

This endpoint allows you to list out a user’s group memberships and groups they are managing.

HTTP Request

GET https://api.lessonly.com/api/v1/users/:user_id/groups

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.

Update User Groups

curl -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/users/:user_id/groups"

The following are sample parameters for this request:

{
  "memberships":
    [
      {"id": 1 },
      {"id": 2, "remove": "true"}

    ],
  "managing":
    [
      {"id":  3, "remove": "true" },
      {"id":  4 }
    ]

}

A successful update will return JSON consisting of the user group repsonse:

{
  "type": "update_user_groups",
  "memberships":
    [
        {"id": 1, "name": "Test Group"},
        {"id": 3, "name": "Test Group 3"},
    ],
  "managing":
    [
        {"id": 1, "name": "Test Group5"},
    ]
}

This endpoint allows you to update a user’s involvement in various groups.

HTTP Request

PUT https://api.lessonly.com/api/v1/users/:user_id/groups

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.
memberships no Array The groups in which the user is a member. Passing “remove”: “true” will remove this association.
managing no Array The groups in which the user is managing. Passing “remove”: “true” will remove this association.

User Assignments

curl -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/users/:user_id/assignments"

The above command returns JSON structured like this:

{
  "type": "user_assignments",
  "assignments":[
    {
      "type": "Assignment",
      "resource_type": "assignment",
      "id": 1,
      "assignee_id": 1,
      "ext_uid": "ABC123",
      "assignable_id": 1,
      "assignable_type": "Lesson",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": "2020-09-30T00:00:00Z",
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Completed",
      "score": 20
    },
    {
      "type": "Assignment",
      "resource_type": "assigment",
      "id": 2,
      "assignee_id": 1,
      "ext_uid": "DEF456",
      "assignable_id": 2,
      "assignable_type": "LearningPaths::Path",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": null,
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint returns a list of assignments for a given user.

HTTP Request

GET https://api.lessonly.com/api/v1/users/:user_id/assignments

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.

Create User Assignments

curl -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/users/:user_id/assignments"

The following are sample parameters for this request:

{
  "assignments":
    [
      {
        "assignable_id": 1,
        "assignable_type": "Lesson",
        "due_by": "2020-09-30",
        "notify": false
      },
      {
        "assignable_id": 3,
        "assignable_type": "LearningPaths::Path",
        "due_by": "2020-09-30",
        "notify": false
      }
    ]
}

A successful update will return JSON consisting of the user assignment repsonse:

{
  "type": "create_user_assignments",
  "assignments":[
    {
      "type": "Assignment",
      "resource_type": "assignment",
      "id": 1,
      "assignee_id": 1,
      "ext_uid": "ABC123",
      "assignable_id": 1,
      "assignable_type": "Lesson",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": null,
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": 20
    },
    {
      "type": "Assignment",
      "resource_type": "assignment",
      "id": 3,
      "assignee_id": 2,
      "ext_uid": "DEF456",
      "assignable_id": 2,
      "assignable_type": "LearningPaths::Path",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": null,
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint allows you to create assignments for a user.

HTTP Request

POST https://api.lessonly.com/api/v1/users/:user_id/assignments

Query Parameters

Parameter Required Type Description
user_id yes Positive Integer The user to access. The company must have access to the user.
assignments yes Array Array of assignments to be made to the user. Each requires an assignable_id and assignable_type of “Lesson” or “LearningPaths::Path”. By default, an email will be sent to the assignee; it will come from notifications@lessonly.com. To suppress the email notification set notify to false.

Groups

List Groups

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/groups"

The above command returns JSON structured like this:

{
  "type": "groups",
  "groups": [
    {
      "id": 1,
      "name": "Group 1",
      "archived_at": null,
      "archived_by_user_id": null
    },
    {
      "id": 2,
      "name": "Group 2",
      "archived_at": null,
      "archived_by_user_id": null
    },
  ]
}

This endpoint retrieves all groups.

HTTP Request

GET https://api.lessonly.com/api/v1/groups

Show Group Details

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/groups/:group_id"

The above command returns JSON structured like this:

{
  "type": "group",
  "resource_type": "group",
  "id": 12345,
  "name": "Test Group",
  "members": [
         {"id": 1, "ext_uid": "ABC123", "name": "Test Name"},
         {"id": 2, "ext_uid": "DEF456", "name": "Test Name 2"}
    ],
  "managers":  [
         {"id": 1, "ext_uid": "ABC123", "name": "Test Name"},
   ],
   "archived_at": null,
   "archived_by_user_id": null
}

This endpoint retrieves a listing of a groups members and managers.

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group to access. The company must have access to the group.

HTTP Request

GET https://api.lessonly.com/api/v1/groups/:group_id

Create Group

curl -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/groups"

The following are sample parameters for this request:

{
  "name": "create_group",
  "members":
    [
      {"id": 1 },
      {"id": 2 }

    ],
  "managers":
    [
      {"id":  3 },
      {"id":  4 }
    ]

}

A successful update will return JSON consisting of the group details repsonse:

{
  "type": "create_group",
  "resource_type": "group",
  "id": 12345,
  "name": "New Name",
  "members": [
         {"id": 1, "ext_uid": "ABC123", "name": "Test Name 1"},
         {"id": 2, "ext_uid": "ABC123", "name": "Test Name 2"}
    ],
  "managers":  [
         {"id": 3, "ext_uid": "JKL012", "name": "Test Name 3"},
         {"id": 4, "ext_uid": "JKL012", "name": "Test Name 4"}
   ]
}

This endpoint allows you to create a group and its members and managers.

HTTP Request

POST https://api.lessonly.com/api/v1/groups/ -d params

Query Parameters

Parameter Required Type Description
name yes String The name of the group
members no Array The members of a group.
managers no Array The managers of a group.

Update Group

curl -X PUT -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/groups/:group_id"

The following are sample parameters for this request:

{
  "name": "New Name",
  "members":
    [
      {"id": 1 },
      {"id": 2, "remove": "true"}

    ],
  "managers":
    [
      {"id":  3, "remove": "true" },
      {"id":  4 }
    ]

}

A successful update will return JSON consisting of the group details repsonse:

{
  "type": "update_group",
  "resource_type": "group",
  "id": 12345,
  "name": "New Name",
  "members": [
         {"id": 1, "ext_uid": "ABC123", "name": "Test Name 1"},
    ],
  "managers":  [
         {"id": 4, "ext_uid": "JKL012", "name": "Test Name 4"},
   ]
}

This endpoint allows you to update a group and its members and managers.

HTTP Request

PUT https://api.lessonly.com/api/v1/groups/:group_id/ -d params

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group to access. The company must have access to the group.
name no String The name of the group.
members no Array The members of a group. Passing “remove”: “true” will remove this association.
managers no Array The managers of a group. Passing “remove”: “true” will remove this association.

Archive Group

curl -X PUT -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/groups/:group_id/archive"

The above command returns JSON structured like this:

{
    "archived_at": "2016-09-26T13:05:01.174-04:00",
    "archived_by_user_id": null,
    "id": 12631,
    "members": [
           {"id": 1, "ext_uid": "ABC123", "name": "Test Name 1"}
      ],
    "managers":  [
           {"id": 4, "ext_uid": "JKL012", "name": "Test Name 4"}
     ],
    "name": "/",
    "resource_type": "group",
    "type": "group"
}

This endpoint allows the archiving of a single group.

HTTP Request

PUT https://api.lessonly.com/api/v1/groups/:group_id/archive

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group to archive. The company must have access to the group.

Restore Group

curl -X PUT -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/groups/:group_id/restore"

The above command returns JSON structured like this:

{
    "archived_at": null,
    "archived_by_user_id": null,
    "id": 12631,
    "members": [
           {"id": 1, "ext_uid": "ABC123", "name": "Test Name 1"}
      ],
    "managers":  [
           {"id": 4, "ext_uid": "JKL012", "name": "Test Name 4"}
     ],
    "name": "/",
    "resource_type": "group",
    "type": "group"
}

This endpoint allows the restoring of a single archived group.

HTTP Request

PUT https://api.lessonly.com/api/v1/groups/:group_id/restore

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group to restore. The company must have access to the group.

Delete Group

curl -X DELETE -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/groups/:group_id"

A successful update returns JSON consisting of the id of the deleted group

{
  "type": "delete_group",
  "id": "3",
  "name": "Group 3",
  "archived_at": null,
  "archived_by_user_id": null
}

This endpoint allows you to delete a group in the API.

HTTP Request

DELETE https://api.lessonly.com/api/v1/groups/:group_id

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group to delete. The company must have access to the group.

Group Assignments

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/groups/:group_id/assignments"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "assignable_id": 10,
    "assignable_type": "Lesson",
    "group_id": 5
  },
  {
    "id": 2,
    "assignable_id": 15,
    "assignable_type": "LearningPaths::Path",
    "group_id": 5
  }
]

This endpoint returns a list of all lessons and paths that have been assigned to the given group, in no particular order. Results include both archived and unarchived learning content.

HTTP Request

GET https://api.lessonly.com/api/v1/groups/:group_id/assignments

Query Parameters

Parameter Required Type Description
group_id yes Positive Integer The group whose assignments to access

Lessons

List Lessons

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/lessons"

The above command returns JSON structured like this:

{
  "type": "lessons",
  "lessons":[
      {
        "id": 1,
        "title": "First Lesson",
        "archived_at": null,
        "archived_by_user_id": null,
        "retake_score": 80,
        "public": false,
        "created_at": "2020-09-30T00:00:00Z",
        "last_updated_at": "2020-09-30T00:00:00Z",
        "tags": [
          {
            "id": 1,
            "name": "test_tag",
            "resource_type": "tag"
          }
        ],
        "links": {
          "overview": "https://mycompany.lessonly.com/lessons/1-first-lesson"
        }
      },
      {
        "id": 2,
        "title": "Second Lesson",
        "archived_at": null,
        "archived_by_user_id": null,
        "retake_score": 95,
        "public": true,
        "created_at": "2020-09-30T00:00:00Z",
        "last_updated_at": "2020-09-30T00:00:00Z",
        "tags": [
          {
            "id": 1,
            "name": "test_tag",
            "resource_type": "tag"
          }
        ],
        "links": {
          "overview": "https://mycompany.lessonly.com/lessons/2-second-lesson",
          "shareable": "https://mycompany.lessonly.com/lesson/2-second-lesson"
        }
      }
    ]
}

This endpoint retrieves all lessons.

HTTP Request

GET https://api.lessonly.com/api/v1/lessons

Show Lesson Details

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/lessons/:lesson_id

The above command returns JSON structured like this:

{
  "type": "lesson",
  "resource_type": "lesson",
  "id": 1,
  "title": "Lesson 1",
  "assignees_count": 10,
  "completed_count": 5,
  "retake_score": 80,
  "public": false,
  "created_at": "2020-09-30T00:00:00Z",
  "last_updated_at": "2020-09-30T00:00:00Z",
  "tags": [
    {
      "id": 1,
      "name": "test_tag",
      "resource_type": "tag"
    }
  ],
  "links": {
    "overview": "https://mycompany.lessonly.com/lessons/1-lesson-1",
    "shareable": "https://mycompany.lessonly.com/lesson/1-lesson-1"
  },
  "archived_at": null,
  "archived_by_user_id": null
}

This endpoint retrieves all the lesson details including statistics about the completion of the lesson.

HTTP Request

GET https://api.lessonly.com/api/v1/lessons/:lesson_id

Show Lesson Details (v1.1)

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1.1/lessons/:lesson_id

The above command returns JSON structured like this:

{
  "type": "lesson",
  "resource_type": "lesson",
  "id": 1,
  "title": "Lesson 1",
  "retake_score": 80,
  "public": false,
  "created_at": "2020-09-30T00:00:00Z",
  "last_updated_at": "2020-09-30T00:00:00Z",
  "tags": [
    {
      "id": 1,
      "name": "test_tag"
    }
  ],
  "links": {
    "shareable": "https://lesson-shareable-link"
  }
}

This endpoint retrieves the lesson’s information. For a count of completed assignments, please see Lesson Completed Assignments.

HTTP Request

GET https://api.lessonly.com/api/v1.1/lessons/:lesson_id

Update Lesson

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/lessons/:lesson_id -d params

The above command returns JSON structured like this:

{
  "type": "update_lesson",
  "resource_type": "lesson",
  "id": 1,
  "title": "Lesson 1",
  "assignees_count": 10,
  "completed_count": 5,
  "retake_score": 80,
  "public": false,
  "created_at": "2020-09-30T00:00:00Z",
  "last_updated_at": "2020-09-30T00:00:00Z",
  "tags": [
    {
      "id": 1,
      "name": "test_tag"
    }
  ],
  "links": {
    "overview": "https://mycompany.lessonly.com/lessons/1-lesson-1",
    "shareable": "https://mycompany.lessonly.com/lesson/1-lesson-1"
  }
}

This endpoint allows the updating of a single lesson and its attributes.

HTTP Request

PUT https://api.lessonly.com/api/v1/lessons/:lesson_id -d params

Query Parameters

Parameter Required Type Description
lesson_id yes Positive Integer The lesson to access. The company must have access to the lesson.
title no String The title of the lesson.
retake_score no Positive Integer The retake score of the lesson.
public no Boolean Whether or not the lesson is public

Archive Lesson

curl -X PUT -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/lessons/:lesson_id/archive"

The above command returns JSON structured like this:

{
    "archived_at": "2016-10-12T16:12:09.850-04:00",
    "archived_by_user_id": null,
    "assignees_count": 0,
    "completed_count": 0,
    "created_at": "2016-10-06T16:09:41Z",
    "description": null,
    "id": 43530,
    "last_updated_at": "2016-10-06T16:18:01Z",
    "links": {
      "overview": "https://mycompany.lessonly.com/lessons/43530-untitled-lesson",
      "shareable": "https://mycompany.lessonly.com/lesson/43530-untitled-lesson"
    },
    "public": false,
    "resource_type": "lesson",
    "retake_score": 90,
    "tags": [
      {
        "id": 1,
        "name": "test_tag"
      }
    ],
    "title": "Untitled Lesson",
    "type": "lesson"
}

This endpoint allows the archiving of a single lesson.

HTTP Request

PUT https://api.lessonly.com/api/v1/lessons/:lesson_id/archive

Query Parameters

Parameter Required Type Description
lesson_id yes Positive Integer The lesson to archive. The company must have access to the lesson.

Restore Lesson

curl -X PUT -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/lessons/:lesson_id/restore"

The above command returns JSON structured like this:

{
    "archived_at": null,
    "archived_by_user_id": null,
    "assignees_count": 0,
    "completed_count": 0,
    "created_at": "2016-10-06T16:09:41Z",
    "description": null,
    "id": 43530,
    "last_updated_at": "2016-10-06T16:18:01Z",
    "links": {
      "overview": "https://mycompany.lessonly.com/lessons/43530-untitled-lesson",
      "shareable": "https://mycompany.lessonly.com/lesson/43530-untitled-lesson"
    },
    "public": false,
    "resource_type": "lesson",
    "retake_score": 90,
    "tags": [
      {
        "id": 1,
        "name": "test_tag"
      }
    ],
    "title": "Untitled Lesson",
    "type": "lesson"
}

This endpoint allows the restoring of a single archived lesson.

HTTP Request

PUT https://api.lessonly.com/api/v1/lessons/:lesson_id/restore

Query Parameters

Parameter Required Type Description
lesson_id yes Positive Integer The lesson to restore. The company must have access to the lesson.

Lesson Assignments

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/lessons/:lesson_id/assignments

The above command returns JSON structured like this:

{
  "type": "lesson_assignments",
  "total_assignments": 2000,
  "page": 1,
  "per_page": 2,
  "total_pages": 1000,
  "assignments":[
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "assigned_at": "2020-03-20T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": "2020-09-30T00:00:00Z",
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Completed",
      "score": 20
    },
    {
      "id": 2,
      "resource_type": "assignment",
      "assignee_id": 2,
      "ext_uid": "DEF456",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": null,
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint retrieves all the assignments for a particular lesson.

HTTP Request

GET https://api.lessonly.com/api/v1/lessons/:lesson_id/assignments

Query Parameters

Parameter Required Type Description
lesson_id yes Positive Integer The lesson to access. The company must have access to the lesson.
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 5000. Numbers > 5000 are ignored and 5000 will be returned.

Lesson Completed Assignments (v1.1)

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1.1/lessons/:lesson_id/assignments/completed"

The above command returns JSON structured like this:

{
  "type": "lesson_assignments_completed",
  "completed_count": 13
}

This endpoint retrieves the number of completed assignments for a given lesson.

HTTP Request

GET https://api.lessonly.com/api/v1.1/lessons/:lesson_id/assignments/completed

Assign Lesson

curl -X PUT -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/lessons/:lesson_id/assignments"

The following are sample parameters for this request:

{
  "assignments":[
    {
      "assignee_id": 1,
      "due_by": "2020-09-30T00:00:00Z",
      "notify": false
    }
  ]
}

A successful update returns JSON formatted version of the assignments made

{
  "type": "update_lesson_assignments",
  "assignments": [
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "assignable_type": "Lesson",
      "assignable_id": 3,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": "2020-09-30T00:00:00Z",
      "updated_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint allows you to make assignments to a particular lesson in the API.

HTTP Request

PUT https://api.lessonly.com/api/v1/lessons/:lesson_id/assignments -d params

Query Parameters

Parameter Required Type Description
lesson_id yes Positive Integer The lesson to access. The company must have access to the user.
assignments no Hash A hash of assignments to be made to the lesson. If the assignment for a particular user already exists, the user will be reassigned the lesson. By default, an email will be sent to the assignee; it will come from notifications@lessonly.com. To suppress the email notification set notify to false.

Courses

List Courses

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/courses"

The above command returns JSON structured like this:

{
  "type": "courses",
  "courses":[
    {
      "id": 1,
      "title": "Course 1",
      "archived_at": null,
      "archived_by_user_id": null
    },
    {
      "id": 2,
      "title": "Course 2",
      "archived_at": null,
      "archived_by_user_id": null
    }
  ]
}

This endpoint retrieves all courses.

HTTP Request

GET https://api.lessonly.com/api/v1/courses

Show Course Details

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/courses/:course_id

The above command returns JSON structured like this:

{
  "type": "course",
  "resource_type": "course",
  "id": 1,
  "title": "Course 1",
  "assignees_count": 10,
  "completed_count": 4,
  "description": "Test Description of Course 1",
  "lessons": [
    {
      "id": 1,
      "title": "First Lesson"
    },
    {
      "id": 2,
      "title": "Second Lesson"
    }
  ],
  "public": false,
  "created_at": "2020-09-30T00:00:00Z",
  "last_updated_at": "2020-09-30T00:00:00Z",
  "tags" : [
    {
      "id": 1,
      "name": "test_tag",
      "resource_type": "tag"
    }
  ],
  "links": {
    "overview": "https://mycompany.lessonly.com/lessons/48804-course-1",
    "shareable": "https://mycompany.lessonly.com/lesson/48804-course-1"
  },
  "archived_at": null,
  "archived_by_user_id": null
}

This endpoint retrieves all the courses details including their lessons and some other statistics about the completion of the course and its assignees.

HTTP Request

GET https://api.lessonly.com/api/v1/courses/:course_id

Query Parameters

Parameter Required Type Description
course_id yes Positive Integer The course to access. The company must have access to the course.

Show Course Details (v1.1)

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1.1/courses/:course_id"
{
  "type": "course",
  "resource_type": "course",
  "id": 1,
  "owner_id": 12,
  "title": "Course 1",
  "description": "Test Description of Course 1",
  "lessons": [
    {
      "id": 1,
      "title": "First Lesson"
    },
    {
      "id": 1,
      "title": "Second Lesson"
    }
  ]
}

This endpoint retrieves all the details of the course, including its lessons. For completed assignments information, please see Completed Course Assignments.

HTTP Request

GET https://api.lessonly.com/api/v1/courses/:course_id

Query Parameters

Paramter Required Type Description
course_id yes Positive Integer The course to access. The company must have access to the course.

Archive Course

curl -X PUT -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/courses/:course_id/archive"

The above command returns JSON structured like this: json { "archived_at": "2016-10-13T09:51:13.549-04:00", "archived_by_user_id": null, "assignees_count": 4, "completed_count": 0, "created_at": "2016-04-30T15:23:12Z", "description": "", "id": 3934, "last_updated_at": null, "lessons": [ { "id": 1, "title": "First Lesson" }, { "id": 1, "title": "Second Lesson" } ], "links": { "overview": "https://mycompany.lessonly.com/courses/3934-empty-course", "shareable": "https://mycompany.lessonly.com/course/3934-empty-course" }, "public": false, "resource_type": "course", "tags": [ { "id": 1, "name": "test_tag" } ], "title": "Empty Course", "type": "course" }

This endpoint allows the archiving of a single course.

HTTP Request

PUT https://api.lessonly.com/api/v1/courses/:course_id/archive

Query Parameters

Parameter Required Type Description
course_id yes Positive Integer The course to archive. The company must have access to the course.

Restore Course

curl -X PUT -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/courses/:course_id/restore"

The above command returns JSON structured like this:

{
    "archived_at": null,
    "archived_by_user_id": null,
    "assignees_count": 4,
    "completed_count": 0,
    "created_at": "2016-04-30T15:23:12Z",
    "description": "",
    "id": 3934,
    "last_updated_at": null,
    "lessons": [
      {
        "id": 1,
        "title": "First Lesson"
      },
      {
        "id": 1,
        "title": "Second Lesson"
      }
    ],
    "links": {
      "overview": "https://mycompany.lessonly.com/courses/3934-empty-course",
      "shareable": "https://mycompany.lessonly.com/course/3934-empty-course"
    },
    "public": false,
    "resource_type": "course",
    "tags": [
      {
        "id": 1,
        "name": "test_tag"
      }
    ],
    "title": "Empty Course",
    "type": "course"
}

This endpoint allows the restoring of a single archived course.

HTTP Request

PUT https://api.lessonly.com/api/v1/courses/:course_id/restore

Query Parameters

Parameter Required Type Description
course_id yes Positive Integer The course to restore. The company must have access to the course.

Course Assignments

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/courses/:course_id/assignments

The above command returns JSON structured like this:

{
  "type": "course_assignments",
  "total_assignments": 2000,
  "page": 1,
  "per_page": 2,
  "total_pages": 1000,
  "assignments":[
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "assignable_type": "Course",
      "assignable_id": 1,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "assigned_at": "2020-03-20T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Completed",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": "2016-03-28T18:20:06Z",
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 2,
      "resource_type": "assignment",
      "assignee_id": 2,
      "assignable_type": "Course",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    }
  ]
}

This endpoint retrieves all the assignments for a particular course.

HTTP Request

GET https://api.lessonly.com/api/v1/courses/:course_id/assignments

Query Parameters

Parameter Required Type Description
course_id yes Positive Integer The course to access. The company must have access to the lesson.
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 5000. Numbers > 5000 are ignored and 5000 will be returned.

Course Assignments Completed (v1.1)

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1.1/courses/:course_id/assignments/completed

The above command returns JSON structured like this:

{
  "type": "course_assignments_completed",
  "completed_count": 12
}

This endpoint retrieves the count of completed assignments for a particular course.

HTTP Request

GET https://api.lessonly.com/api/v1.1/courses/:course_id/assignments

Assign Course

curl -X PUT -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/courses/:course_id/assignments"

The following are sample parameters for this request:

{
  "assignments":[
    {
      "assignee_id": 1,
      "due_by": "2020-09-30T00:00:00Z",
      "notify": false
    }
  ]
}

A successful update returns JSON formatted version of the assignments made

{
  "type": "update_course_assignments",
  "assignments": [
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "assignable_type": "Course",
      "assignable_id": 3,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint allows you to make assignments to a particular course in the API.

HTTP Request

PUT https://api.lessonly.com/api/v1/courses/:course_id/assignments -d params

Query Parameters

Parameter Required Type Description
course_id yes Positive Integer The course to access. The company must have access to the user.
assignments no Hash A hash of assignments to be made to the course. If the assignment for a particular user already exists, the user will be reassigned the course. By default, an email will be sent to the assignee; it will come from notifications@lessonly.com. To suppress the email notification set notify to false.

Paths

List Paths

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/paths"

The above command returns JSON structured like this:

{
  "type": "paths",
  "paths": [
    {
      "id": 1,
      "title": "Path 1",
      "archived_at": null,
      "archived_by_user_id": null,
      "public": false,
      "created_at": "2017-07-24T10:47:23Z",
      "last_updated_at": "2017-07-24T10:49:10Z",
      "published_at": null,
      "publisher_id": null,
      "tags": [
        {
          "id": 1,
          "resource_type": "tag",
          "name": "Engineering"
        }
      ],
      "links": {
        "overview": "https://mycompany.lessonly.com/paths/1-path-1"
      }
    },
    {
      "id": 2,
      "title": "Path 2",
      "archived_at": "2017-06-28T10:46:03.467-04:00",
      "archived_by_user_id": 123,
      "public": true,
      "created_at": "2017-07-24T10:47:23Z",
      "last_updated_at": "2017-07-24T10:49:10Z",
      "published_at": "2017-08-21T11:16:22Z",
      "publisher_id": 1234,
      "tags": [
        {
          "id": 1,
          "resource_type": "tag",
          "name": "Engineering"
        }
      ],
      "links": {
        "shareable": "https://mycompany.lessonly.com/path/2-path-2",
        "overview": "https://mycompany.lessonly.com/paths/2-path-2"
      }
    }
  ]
}

This endpoint retrieves all paths.

HTTP Request

GET https://api.lessonly.com/api/v1/paths

Show Path Details

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/paths/:path_id"

The above command returns JSON structured like this:

{
  "type": "path",
  "id": 1,
  "resource_type": "path",
  "title": "Developer Onboarding",
  "description": "All you need to know to get up-and-running.",
  "enforced_order": true,
  "public": false,
  "created_at": "2017-07-24T10:47:23Z",
  "last_updated_at": "2017-07-24T10:49:10Z",
  "published_at": null,
  "publisher_id": null,
  "tags": [
    {
      "id": 1,
      "resource_type": "tag",
      "name": "Engineering"
    }
  ],
  "links": {
    "shareable": "https://mycompany.lessonly.com/path/1-developer-onboarding",
    "overview": "https://mycompany.lessonly.com/paths/1-developer-onboarding"
  },
  "archived_at": null,
  "archived_by_user_id": null,
  "contents": [
    {
      "id": 10,
      "resource_type": "lesson",
      "title": "Setting up a development environment",
      "archived_at": null,
      "archived_by_user_id": null
    },
    {
      "id": 2,
      "resource_type": "wait_step",
      "effect": "locked",
      "condition": "prev_step_finished",
      "unit": "days",
      "amount": 3
    },
    {
      "id": 20,
      "resource_type": "path",
      "title": "Know Your Tools",
      "archived_at": null,
      "archived_by_user_id": null,
      "contents": [
        {
          "id": 4,
          "type": "lesson",
          "title": "Clubhouse 101",
          "archived_at": null,
          "archived_by_user_id": null
        },
        {
          "id": 5,
          "resource_type": "placeholder",
          "description": "Add a lesson about Github"
        }
      ]
    }
  ]
}

This endpoint retrieves all the path’s details including their steps.

The "resource_type" of Paths’ "contents" will be one of "lesson", "wait_step", "path", or "placeholder".

Paths’ "contents" may be nested.

HTTP Request

GET https://api.lessonly.com/api/v1/paths/:path_id

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to access. The company must have access to the path.

Archive Path

curl -X PUT -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/paths/:path_id/archive"

The above command returns JSON structured like this:

{
  "type": "path",
  "id": 1,
  "resource_type": "path",
  "title": "Developer Onboarding",
  "description": "All you need to know to get up-and-running.",
  "enforced_order": true,
  "public": false,
  "created_at": "2017-07-24T10:47:23Z",
  "last_updated_at": "2017-07-24T10:49:10Z",
  "published_at": null,
  "publisher_id": null,
  "tags": [
    {
      "id": 1,
      "resource_type": "tag",
      "name": "Engineering"
    }
  ],
  "links": {
    "shareable": "https://mycompany.lessonly.com/path/1-developer-onboarding",
    "overview": "https://mycompany.lessonly.com/paths/1-developer-onboarding"
  },
  "archived_at": "2016-10-13T09:51:13.549-04:00",
  "archived_by_user_id": 1,
  "contents": [
    {
      "id": 10,
      "resource_type": "lesson",
      "title": "Setting up a development environment",
      "archived_at": null,
      "archived_by_user_id": null
    },
    {
      "id": 2,
      "resource_type": "wait_step",
      "effect": "locked",
      "condition": "prev_step_finished",
      "unit": "days",
      "amount": 3
    },
    {
      "id": 20,
      "resource_type": "path",
      "title": "Know Your Tools",
      "archived_at": null,
      "archived_by_user_id": null,
      "contents": [
        {
          "id": 4,
          "type": "lesson",
          "title": "Clubhouse 101",
          "archived_at": null,
          "archived_by_user_id": null
        },
        {
          "id": 5,
          "resource_type": "placeholder",
          "description": "Add a lesson about Github"
        }
      ]
    }
  ]
}

This endpoint allows the archiving of a single path.

HTTP Request

PUT https://api.lessonly.com/api/v1/paths/:path_id/archive

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to archive. The company must have access to the path.

Restore Path

curl -X PUT -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/paths/:path_id/restore"

The above command returns JSON structured like this:

{
  "type": "path",
  "id": 1,
  "resource_type": "path",
  "title": "Developer Onboarding",
  "description": "All you need to know to get up-and-running.",
  "enforced_order": true,
  "public": false,
  "created_at": "2017-07-24T10:47:23Z",
  "last_updated_at": "2017-07-24T10:49:10Z",
  "published_at": null,
  "publisher_id": null,
  "tags": [
    {
      "id": 1,
      "resource_type": "tag",
      "name": "Engineering"
    }
  ],
  "links": {
    "shareable": "https://mycompany.lessonly.com/path/1-developer-onboarding",
    "overview": "https://mycompany.lessonly.com/paths/1-developer-onboarding"
  },
  "archived_at": null,
  "archived_by_user_id": null,
  "contents": [
    {
      "id": 10,
      "resource_type": "lesson",
      "title": "Setting up a development environment",
      "archived_at": null,
      "archived_by_user_id": null
    },
    {
      "id": 2,
      "resource_type": "wait_step",
      "effect": "locked",
      "condition": "prev_step_finished",
      "unit": "days",
      "amount": 3
    },
    {
      "id": 20,
      "resource_type": "path",
      "title": "Know Your Tools",
      "archived_at": null,
      "archived_by_user_id": null,
      "contents": [
        {
          "id": 4,
          "type": "lesson",
          "title": "Clubhouse 101",
          "archived_at": null,
          "archived_by_user_id": null
        },
        {
          "id": 5,
          "resource_type": "placeholder",
          "description": "Add a lesson about Github"
        }
      ]
    }
  ]
}

This endpoint allows the restoring of a single archived path.

HTTP Request

PUT https://api.lessonly.com/api/v1/paths/:path_id/restore

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to restore. The company must have access to the path.

Assigning a Path

curl -X PUT -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/paths/:path_id/assignments"

The following are sample parameters for this request:

{
  "assignments":[
    {
      "assignee_id": 1,
      "due_by": "2020-09-30T00:00:00Z",
      "notify": false
    }
  ]
}

A successful update returns a JSON formatted version of the assignments made:

{
  "type": "update_path_assignments",
  "assignments": [
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "completed_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "score": null
    }
  ]
}

This endpoint allows you to make assignments to a particular path in the API.

HTTP Request

PUT https://api.lessonly.com/api/v1/paths/:path_id/assignments -d params

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to access. The company must have access to the path.
assignments no Hash A hash of assignments to be made to the path. If the assignment for a particular user already exists, the user will be reassigned the path. By default, an email will be sent to the assignee; it will come from notifications@lessonly.com. To suppress the email notification set notify to false.

List Path Assignments

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/paths/:path_id/assignments

The above command returns JSON structured like this:

{
  "type": "path_assignments",
  "total_assignments": 2,
  "page": 1,
  "per_page": 10,
  "total_pages": 1,
  "assignments":[
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 2,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "assigned_at": "2020-03-20T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Completed",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": "2016-03-28T18:20:06Z",
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 2,
      "resource_type": "assignment",
      "assignee_id": 3,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    }
  ]
}

This endpoint retrieves all the assignments for a particular path.

HTTP Request

GET https://api.lessonly.com/api/v1/paths/:path_id/assignments

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to access. The company must have access to the path.
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 5000. Numbers > 5000 are ignored and 5000 will be returned.

Path Assignments Completed

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/paths/:path_id/assignments/completed

The above command returns JSON structured like this:

{
  "type": "path_assignments_completed",
  "completed_count": 11
}

This endpoint retrieves the count of completed assignments for a particular path.

HTTP Request

GET https://api.lessonly.com/api/v1/paths/:path_id/assignments/completed

Query Parameters

Parameter Required Type Description
path_id yes Positive Integer The path to access. The company must have access to the path.

Tags

List Tags

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/tags"

The above command returns JSON structured like this:

{
  "type": "tags",
  "tags": [
    {
      "id": 1,
      "resource_type": "tag",
      "name": "Marketing"
    },
    {
      "id": 2,
      "resource_type": "tag",
      "name": "Development"
    }
  ]
}

This endpoint retrieves all tags.

HTTP Request

GET https://api.lessonly.com/api/v1/tags

Show Tag Details

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/tags/:tag_id

The above command returns JSON structured like this:

{
  "type": "tag",
  "resource_type": "tag",
  "id": 1,
  "name": "Marketing"
}

This endpoint retrieves all the tag details.

HTTP Request

GET https://api.lessonly.com/api/v1/tags/:tag_id

Query Parameters

Parameter Required Type Description
tag_id yes Positive Integer The tag to access. The company must have access to the tag.

Tag Lessons

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/tags/:tag_id/lessons

The above command returns JSON structured like this:

{
  "type": "tag_lessons",
  "lessons": [
    {
      "id": 5,
      "resource_type": "lesson",
      "title": "Marketing 101",
      "assignees_count": 21,
      "completed_count": 1,
      "retake_score": 90,
      "description": "A quick overview about how we do marketing."
    },
    {
      "id": 456,
      "resource_type": "lesson",
      "title": "Development 101",
      "assignees_count": 11,
      "completed_count": 5,
      "retake_score": 95,
      "description": "A quick overview about how we do development."
    }
  ]
}

This endpoint retrieves all the lessons tagged with a particular tag.

HTTP Request

GET https://api.lessonly.com/api/v1/tags/:tag_id/lessons

Query Parameters

Parameter Required Type Description
tag_id yes Positive Integer The tag to access. The company must have access to the tag.

Tag Courses

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/tags/:tag_id/courses

The above command returns JSON structured like this:

{
  "type": "tag_courses",
  "courses": [
    {
      "id": 123,
      "resource_type": "course",
      "title": "Onboarding Course",
      "assignees_count": 15,
      "completed_count": 11,
      "description": "This course will get you up to speed in our company.",
      "lessons": [
        {
          "id": 5,
          "resource_type": "lesson",
          "title": "Marketing 101",
          "assignees_count": 21,
          "completed_count": 1,
          "retake_score": 90,
          "description": "A quick overview about how we do marketing."
        },
        {
          "id": 456,
          "resource_type": "lesson",
          "title": "Development 101",
          "assignees_count": 11,
          "completed_count": 5,
          "retake_score": 95,
          "description": "A quick overview about how we do development."
        }
      ]
    }
  ]
}

This endpoint retrieves all the courses tagged with a particular tag.

HTTP Request

GET https://api.lessonly.com/api/v1/tags/:tag_id/courses

Query Parameters

Parameter Required Type Description
tag_id yes Positive Integer The tag to access. The company must have access to the tag.

Tag Paths

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/tags/:tag_id/paths

The above command returns JSON structured like this:

{
  "type": "tag_paths",
  "paths": [
    {
      "id": 123,
      "resource_type": "path",
      "title": "Onboarding Path",
      "description": "This Path will get you up to speed in our company.",
      "enforced_order": true,
      "public": false,
      "created_at": "2017-11-16T14:57:41Z",
      "last_updated_at": null,
      "published_at": "2017-11-16T14:57:42.351-05:00",
      "publisher_id": 1,
      "tags": [
        {
          "id": 1,
          "resource_type": "tag",
          "name": "First Tag"
        },
        {
          "id": 2,
          "resource_type": "tag",
          "name": "Second tag"
        }
      ],
      "links": {
        "shareable": "http://dev123.lessonly.dev/path/9999-onboarding-test",
        "overview": "http://dev123.lessonly.dev/paths/9999-onboarding-test"
      },
      "archived_at": null,
      "archived_by_user_id": null,
      "contents": [
        {
          "id": 1339,
          "resource_type": "lesson",
          "title": "Your first day",
          "archived_at": null,
          "archived_by_user_id": null
        },
        {
          "id": 8,
          "resource_type": "wait_step",
          "effect": "locked",
          "condition": "prev_step_finished",
          "unit": "days",
          "amount": 1
        },
        {
          "id": 1339,
          "resource_type": "lesson",
          "title": "Getting started",
          "archived_at": null,
          "archived_by_user_id": null
        }
      ]
    }
  ]
}

This endpoint retrieves all the paths tagged with a particular tag.

HTTP Request

GET https://api.lessonly.com/api/v1/tags/:tag_id/paths

Query Parameters

Parameter Required Type Description
tag_id yes Positive Integer The tag to access. The company must have access to the tag.

Assignments

List Assignments

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/assignments"

The above command returns JSON structured like this:

{
  "type": "assignments",
  "total_assignments": 2000,
  "page": 1,
  "per_page": 2,
  "total_pages": 1000,
  "assignments":[
    {
      "id": 1,
      "resource_type": "assignment",
      "assignee_id": 1,
      "assignable_type": "Lesson",
      "assignable_id": 1,
      "ext_uid": "ABC123",
      "due_by": "2020-09-30T00:00:00Z",
      "assigned_at": "2020-03-20T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Completed",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": "2016-03-28T18:20:06Z",
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 2,
      "resource_type": "assignment",
      "assignee_id": 2,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 3,
      "resource_type": "assignment",
      "assignee_id": 3,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "due_by": "2016-03-27T14:15:17Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Overdue",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    },
    {
      "id": 4,
      "resource_type": "assignment",
      "assignee_id": 4,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Grade Pending",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    }
  ]
}

This endpoint returns paginated assignments in no particular order across all of your users, lessons, and paths. Optionally, you can filter by assignments with activity after a given ISO8601 timestamp by passing gt[updated_at]=TIMESTAMP in the query string.

To view assignments for a particular user, lesson, or path please use those dedicated endpoints.

HTTP Request

GET https://api.lessonly.com/api/v1/assignments

Query Parameters

Parameter Required Type Description
page no Positive Integer Which page in the pagination to fetch. Default = 1
per_page no Positive Integer How many results to return in each page. Default = 50; Maximum = 5000. Numbers > 5000 are ignored and 5000 will be returned.
gt no String Specified greater than filter for assignments list. Supported filters are (updated_at). Please follow ISO8601 date format.

Show Assignments by Status

curl -u "DOMAIN:API_KEY" "https://api.lessonly.com/api/v1/assignments/:status"

The above command returns JSON structured like this:

{
  "type": "assignments",
  "total_assignments": 2000,
  "page": 1,
  "per_page": 2,
  "total_pages": 1000,
  "assignments":[
    {
      "id": 2,
      "resource_type": "assignment",
      "assignee_id": 2,
      "assignable_type": "LearningPaths::Path",
      "assignable_id": 1,
      "ext_uid": "DEF456",
      "due_by": "2020-09-30T00:00:00Z",
      "reassigned_at": "2020-09-30T00:00:00Z",
      "status": "Incomplete",
      "started_at": "2016-03-28T14:15:17Z",
      "completed_at": null,
      "updated_at": "2016-03-28T18:20:06Z"
    }
  ]
}

This endpoint retrieves all assignments by their status.

HTTP Request

GET https://api.lessonly.com/api/v1/assignments/:status

Query Parameters

Parameter Required Type Description
status yes String An assignment status. Supported statues are: incomplete, completed, overdue, or grade_pending

Company Settings

Update Webhook URL

curl -X PUT -H "Content-Type: application/json" -u "DOMAIN:API_KEY" -d 'JSON_PARAMS' "https://api.lessonly.com/api/v1/company_settings"

The following are sample parameters for this request:

{
  "lesson_completed_callback_url": "https://webhook.mycompany.com",
  "lesson_completed_callback_authorization": "Tm93IGlzIHRo"
}

A successful update returns a JSON representation of the updated webhook configuration:

{
  "lesson_completed_callback_url": "https://webhook.mycompany.com",
  "lesson_completed_callback_authorization": "Tm93IGlzIHRo"
}

This endpoint allows you to update the recipient URL for webhooks sent upon Lesson completion. See the docs for more information on webhooks.

HTTP Request

PUT https://api.lessonly.com/api/v1/company_settings

Query Parameters

Parameter Required Type Description
lesson_completed_callback_url no String the URL to which webhooks should be sent
lesson_completed_callback_authorization no String the optional value of an Authorization: VALUE header to be sent with webhooks

Rate Limiting

Lessonly currently limits the rate of requests made to the API. At the limit of 500 requests per minute the API will return “403 Forbidden (Rate Limit Exceeded)”. To avoid hitting this rate limit, you can adjust your scripts and workflows to add pauses in between subsequent API requests.

Errors

The Lessonly API uses the following error codes:

Error Code Meaning
400 Malformed Request – Verify that the parameters required are being passed in and all parameters have the format specified in the documentation.
401 Unauthorized – Verify that you have passed your company’s domain and API key correctly.
403 Forbidden – The endpoint that you have tried to access you do not have privaleges to.
404 Not Found – The resource in the endpoint could not be found. Verify the resource id.
405 Method Not Allowed – You tried to access an endpoint with an invalid method
406 Not Acceptable – You requested a format that isn’t json
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.