Introduction

To test your connection to our API please use

curl https://partners.cerego.com/v3/my/profile \
    -H "Authorization: Bearer <API_KEY>"

Welcome to the Cerego API! You can use our API to access Cerego endpoints, which you can use to manage the users in your courses.

Our API follows the JSON API standard. Please take note how objects within a certain resource are in the included section.

All endpoints will start with the following URL and follow standard RESTful practices.

https://partners.cerego.com/v3/

All requests should be made over SSL and it is recommend to use JSON to format your requests.

Authentication

To authenticate to the Cerego API, first you will need to create an API key. Login to Cerego as an admin for your partner and then visit the API Keys page.

Cerego expects the API key to be included in all API requests to the server in a header. The header should look like:

Authorization: Bearer cDPuiaEQrttyDpGU8a1aJtltFUDJY9W31Hi/K+SY9c2WuqHio3dBVtBjagLxyh6U

You must replace cDPuiaEQrttyDpGU8a1aJtltFUDJY9W31Hi/K+SY9c2WuqHio3dBVtBjagLxyh6U with your API key.

Assignments

Get the assignments in a course

curl https://partners.cerego.com/v3/courses/:id/assignments
    -H "Content-Type: application/json"
    -H "Authorization: Bearer <API_KEY>"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "1002204",
      "type": "sets",
      "attributes": {
        "created-at": "2021-02-02T19:48:36.000Z",
        "slug": "introduction-e199d4e9-fa2a-42c2-9e01-b03992cb99ff",
        "name": "Introduction",
        "description": null,
        "description-html": null,
        "is-featured": false,
        "items-count": 4,
        "memories-count": 4,
        "studiable-items-count": 4,
        "studiable-memories-count": 4,
        "content-updated-at": "2021-02-02T19:48:42.000Z",
        "remixable-type": null,
        "remixed-only": null,
        "ic-items-count": 1,
        "study-time-in-sec": 80,
        "scorm-package-id": null,
        "course-information": null,
        "learn-version": 4,
        "goal-type": "set",
        "is-shared": false
      },
      "relationships": {
        "privacy-type": {
          "data": {
            "id": 1,
            "name": "Private"
          }
        },
        "image": {
          "data": null
        },
        "language": {
          "data": {
            "id": "1819",
            "type": "languages"
          }
        },
        "response-language": {
          "data": {
            "id": "1819",
            "type": "languages"
          }
        },
        "creator": {
          "data": {
            "id": "21",
            "type": "partners"
          }
        },
        "characteristics": {
          "data": []
        },
        "parent-set": {
          "data": null
        }
      },
      "links": {
        "self": "/v3/courses/okdxe9m7/sets/1002204"
      },
      "meta": {
        "can-edit": true,
        "due-at": null,
        "course-set-created-at": "2021-02-02T19:48:37.000Z",
        "level-goal": 1.0,
        "position": 1,
        "published": false,
        "publish-at": null,
        "prereq-assignment-id": null,
        "prereq-type": null,
        "prereq-value": null,
        "assignment-id": 2855792,
        "course-id": 208786,
        "percent-started": 0,
        "memory-aggregate": {
          "difficulty-bucket": null,
          "last-study-time": null,
          "see-next-at": null,
          "total-study-time-millis": 0,
          "accuracy": 0,
          "level": 0.0,
          "presentations-count": 0,
          "average-review-interval": 0,
          "average-current-retention": 0,
          "average-easiness-modifier": 0,
          "studied-items-count": 0,
          "unstarted-items-count": 4,
          "eligible-items-count": 0,
          "percent-correct": 0.0,
          "score": 0.0,
          "progress": 0.0
        },
        "learn-messaging": {
          "primary-text": "Get started!",
          "image": "milestone_complete_any_started",
          "button-primary-text": "Let's do this!"
        }
      }
    }
  ],
  "links": {},
  "meta": {
    "total-pages": 1,
    "total-count": 1
  }
}

This endpoint retrieves the assignments in a course.

HTTP Request

GET https://partners.cerego.com/v3/courses/:id/assignments

Query Parameters

Parameter	Description
user_id	Specify a user id to retrieve data related to the user's progress in each assignment.

Assignment Object

- Attributes

Attribute	type	Description
name	string	The name of the assignment
goal-type	integer	Specifies the type of assignment. Can be `set`, `assessment`, or `survey`

- Meta

Attribute	type	Description
assessment-score	float	The user's score on this assessment (`0.0` is 0%, `1.0` is 100%)
can-read	boolean	Whether the user has read permissions to this assignment. Will be false if the user has not cleared a prerequisite and the user wasn't granted access by other means such as being an instructor or admin
memory-aggregate.last-study-time	datetime	The time which the user last studied this assignment
memory-aggregate.progress	float	The progress on this assignment (`0.0` is unstarted, `1.0` is complete)
memory-aggregate.score	float	This is the "mastery level" the user has reached on the assignment
prereq-assignment-id	int	The id of the assignment that is a prerequisite to this assignment
prereq-type	int	The type of prerequisite. Currently 'Level' is the only valid value. This means for the user to access this assignment, the prereq-assignment's `memory-aggregate.score` must be greater or equal to prereq-value
prereq-value	int	The value needed to be achieved to pass the prerequisite.

Courses

Get courses

curl https://partners.cerego.com/v3/courses
    -H "Content-Type: application/json"
    -H "Authorization: Bearer <API_KEY>"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "123456",
      "type": "courses",
      "attributes": {
        "created-at": "2016-07-26T04:10:32.000Z",
        "name": "Introduction to the Cerego API",
        "description": null,
        "slug": "introduction-to-the-cerego-api",
        "users-count": 3,
        "admin-users-count": 1,
        "student-users-count": 2,
        "goal-list-count": 0,
        "goals-count": 12,
        "reports-count": 0,
        "state": "published",
        "state-updated-at": null,
        "instructor-names": ["Mr. Professor"],
        "ic-items-count": 0,
        "assignments-count": 12,
        "external-id": "654321"
      },
      "relationships": {
        "partner": {
          "data": {
            "id": "21",
            "type": "partners"
          }
        },
        "image": {
          "data": {
            "id": "123456",
            "type": "images"
          }
        }
      },
      "links": {
        "self": "/v3/courses/introduction-to-the-cerego-api"
      },
      "meta": {
        "settings": null,
        "role": "instructor",
        "can-edit": true,
        "lti": true,
        "progress": null,
        "percent-started": null,
        "last-study-time": null,
        "payment-required": null,
        "cost": null
      }
    },
    {
      "id": "123457",
      "type": "courses",
      "attributes": {
        "created-at": "2016-07-26T06:01:10.000Z",
        "name": "The learning science behind the banana revolution",
        "description": null,
        "slug": "the-learning-science-behind-the-banana-revolution",
        "users-count": 2,
        "admin-users-count": 1,
        "student-users-count": 1,
        "goal-list-count": 0,
        "goals-count": 1,
        "reports-count": 0,
        "state": "published",
        "state-updated-at": null,
        "instructor-names": ["Dr. Knowitall"],
        "ic-items-count": 0,
        "assignments-count": 1,
        "external-id": "666666"
      },
      "relationships": {
        "partner": {
          "data": {
            "id": "21",
            "type": "partners"
          }
        },
        "image": {
          "data": null
        }
      },
      "links": {
        "self": "/v3/courses/the-learning-science-behind-the-banana-revolution"
      },
      "meta": {
        "settings": null,
        "role": "instructor",
        "can-edit": true,
        "lti": true,
        "progress": null,
        "percent-started": null,
        "last-study-time": null,
        "payment-required": null,
        "cost": null
      }
    }
  ],
  "included": [
    {
      "id": "123456",
      "type": "images",
      "attributes": {
        "created-at": "2016-04-04T22:06:29.000Z",
        "url": "https://assets.cerego.com/uploads/image/uploader/123456/h3ll0m473.jpg",
        "orig-url": null,
        "orig-owner": null,
        "license-id": null,
        "alt-tag": null
      },
      "links": {
        "self": "/v3/images/123456"
      }
    }
  ],
  "links": {
    "self": "http://localhost:3001/v3/courses?page%5Bnumber%5D=1&page%5Bsize%5D=15",
    "next": "http://localhost:3001/v3/courses?page%5Bnumber%5D=2&page%5Bsize%5D=15",
    "last": "http://localhost:3001/v3/courses?page%5Bnumber%5D=2510&page%5Bsize%5D=15"
  },
  "meta": {
    "total-pages": 2510,
    "total-count": 37641
  }
}

This endpoint retrieves courses in a partner. By default it returns courses in the partner that the user is enrolled in as a student.

HTTP Request

GET https://partners.cerego.com/v3/courses

Query Parameters

Parameter	Description
filter[partner_id]	Required. Scopes the courses returned to the partner specified.
user_id	Specify a user id to get the courses that the user is enrolled in as a student. Defaults to the currently signed in user
include_department_courses	If specified, courses in departments of `partner_id` that the user is enrolled in will also be returned
filter[in_library]	Specify this filter to get courses in libraries that the user has access to (i.e., courses that the user can enroll in).
sort	Orders the results based on the param. Example: `name` - sort in alphabetical order
page[number]	Courses are paginated, use this to choose which page you want
filter[role]	Set to `instructor` to return all courses in the partner.

Course Object

Attribute	type	Description
created_at	datetime	When the course was created
name	string	The name of the course
description	string	The description of the course
slug	string	Unique name for the course
users-count	integer	The number of users in the course
admin-users-count	integer	The number of admins (instructors) in the course
student-users-count	integer	The number of students in the course
goals-count	integer	The number of sets in the course
state	string	`published` Course is viewable `unpublished` Course is hidden `archived` Course is no longer in use
state-updated-at	datetime	The most recent time that state was changed
instructor-names	array[string]	A list of instructor names for the course
ic-items-count	integer	The number of instructional items in the course
assignments-count	integer	The number of sets and series in course
external-id	integer	The LTI user associated with the course

Attribute	type	Description
role	string	`learner` You are a student in the course `instructor` You are teaching the course
can-edit	boolean	Determines if you are allowed to edit this content
progress	float	Your progress on this specific course (`0.0` is unstarted, `1.0` is complete)
percent-started	float	The percentage of concepts you have started (`0.0` to `1.0`)
last-study-time	datetime	The time which you last studied this course
payment-required	boolean	You need to pay money to enable this course
cost	integer	Cost in cents to enable the course

Users

Get all users in a course

curl https://partners.cerego.com/v3/courses/:id/users \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <API_KEY>"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "1158898",
      "type": "users",
      "attributes": {
        "created-at": "2014-05-25T03:06:08.000Z",
        "name": "Abraham Lincoln",
        "username": "bowtoabe",
        "email": "bow.to.abe@example.com",
        "last-logged-in-at": "2017-12-14T18:55:14.000Z",
        "guid": "bff7431b-b099-4995-8b63-3b10a20223ab",
        "status": "courses.course_manager.members.studied_via_lti"
      },
      "relationships": {
        "user-partner-id": {
          "data": null
        }
      },
      "meta": {
        "settings": {
          "notifications": {
            "daily-new-assignments": true,
            "signup-nudges": true,
            "daily-new-students": true,
            "daily-goals-reached": true,
            "weekly-stale-invitations": true
          }
        },
        "role": "instructor",
        "can-edit": true,
        "lti": true,
        "progress": 0,
        "percent-started": 0,
        "last-study-time": null,
        "payment-required": false,
        "cost": null
      }
    }
  ],
  "meta": {
    "total-pages": 1,
    "total-count": 1
  }
}

This endpoint retrieves all users that are connected to a specific course.

HTTP Request

GET https://partners.cerego.com/v3/courses/:id/users

User Object

Attribute	type	Description
created_at	datetime	When the user was created
name	string	The name of the user
username	string	The username of the user
email	string	The email of the user
last-logged-in-at	datetime	Time of last log in by the user
guid	string	An identifier for users that can be used across apps
status	string	`courses.course_manager.members.studied_via_lti` Student is connected to the course via LTI `courses.course_manager.members.studied` Student has studied the course, but is not an LTI user `courses.course_manager.members.invited` Student has received an invitation to join the course, but has not yet studied `courses.course_manager.members.no_invitation_sent` No invitation has been sent to the user yet

Attribute	type	Description
role	string	`learner` You are a student in the course `instructor` You are teaching the course without permission to edit `editor` Can edit: some content (only assigned sets and series) `content_manager` Can manage (add/delete/edit): all content (sets and series) `course_manager` Can manage (add/delete/edit): all content (sets and series) + all courses and assignments `admin` Can manage (add/delete/edit): all content (sets and series) + all courses and assignments + organization level features and users
lti	boolean	The user has an LTI account connected
progress	float	The user's progress on this specific course (`0.0` is unstarted, `1.0` is complete)
percent-started	float	The percentage of concepts the user has started (`0.0` to `1.0`)
last-study-time	datetime	The time which the user last studied this course
payment-required	boolean	The user needs money to enable this course
cost	integer	Cost in cents to enable this course

Add a user to a course

curl https://partners.cerego.com/v3/courses/:id/users \
    -d '{"email": "developers@cerego.com", "name": "Sarah Gough"}' \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <API_KEY>"

If you successfully make your POST request you should receive a response that looks like this:

{
  "data": {
    "id": "123460",
    "type": "users",
    "attributes": {
      "created-at": "2017-12-14T19:24:24.000Z",
      "name": "Julius Caesar",
      "username": "allhailtheromanempire@example.com",
      "email": "all.hail.the.roman.empire@example.com",
      "last-logged-in-at": null,
      "guid": "55d22545-92f2-40eb-9037-f9770c3516a9",
      "status": "courses.course_manager.members.invited"
    },
    "relationships": {
      "user-partner-id": {
        "data": null
      }
    },
    "meta": {
      "settings": {
        "notifications": {
          "daily-new-assignments": true
        }
      },
      "role": "student",
      "can-edit": false,
      "lti": false,
      "progress": 0,
      "percent-started": 0,
      "last-study-time": null,
      "payment-required": false,
      "cost": null
    }
  }
}

This endpoint adds a user to a course (or creates a new user if one does not exist)

HTTP Request

POST https://partners.cerego.com/v3/courses/:id/users

Request Parameters

Parameter	Type	Required?	Description
email	string	no	The email of the user you wish to add to the course. Required unless you specify member_id.
member_id	string	no	The member ID of the user you wish to add to the course. A member ID is a unique and unchanging identifier for the user that you have, for example an employee ID. If you specify this, then you must also specify name, and not specify email.
name	string	no	The name of the user you wish to add

Get a user in a course

curl https://partners.cerego.com/v3/courses/:id/users/:id \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <API_KEY>"

If you successfully make your GET request you should receive a response that looks like this:

{
  "data": {
    "id": "1849768",
    "type": "users",
    "attributes": {
      "created-at": "2017-12-14T19:24:24.000Z",
      "name": "Marie Antionette",
      "username": "cakeeaters",
      "email": "cake.eaters@example.com",
      "last-logged-in-at": "2017-12-14T20:33:31.000Z",
      "guid": "55d22545-92f2-40eb-9037-f9770c3516a9",
      "status": "courses.course_manager.members.invited"
    },
    "relationships": {
      "user-partner-id": {
        "data": null
      }
    },
    "meta": {
      "settings": {
        "notifications": {
          "daily-new-assignments": true
        }
      },
      "role": "student",
      "can-edit": false,
      "lti": false,
      "progress": 0,
      "percent-started": 0,
      "last-study-time": null,
      "payment-required": false,
      "cost": null
    }
  }
}

This endpoint gets information about a user within a course

HTTP Request

GET https://partners.cerego.com/v3/courses/:id/users/:id

Remove a user from a course

curl https://partners.cerego.com/v3/courses/:id/users/:id \
    -X DELETE \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <API_KEY>"

If you successfully make your DELETE request you should receive a 204 No Content

This endpoint deletes a user from a course

HTTP Request

DELETE https://partners.cerego.com/v3/courses/:id/users/:id

Get users in a partner

This endpoint retrieves users in a partner.

curl GET https://partners.cerego.com/v3/partners/:partner_id/users?query=:member_id \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <API_KEY>"

If you successfully make your GET request you should receive a response that looks like this:

{
    "data": [
        {
            "id": "1234567",
            "type": "users",
            "attributes": {
                "created-at": "2020-10-16T00:24:54.000Z",
                "name": "name",
                "username": "username",
                "email": null,
                "last-logged-in-at": null,
                "guid": "f105f8e0-122b-479d-98c7-97as65869de7a",
                "has-password": false
            },
            "relationships": {
                "image": {
                    "data": null
                },
                "emails": {
                    "data": []
                },
                "user-partner-id": {
                  "data": null
                },
                "partner-user-tags": {
                    "data": []
                }
            },
            "meta": {
                "role": null,
                "can-edit-partner": false,
                "can-create-course": false,
                "can-edit-course": false,
                "can-create-content": false,
                "can-manage-content": false,
                "can-read-content": false,
                "can-edit-content": false,
                "can-manage-learners": false
            }
        }
    ],
    "meta": {
        "total-pages": 1,
        "total-count": 1
    }
}

HTTP Request

GET https://partners.cerego.com/v3/partners/:partner_id/users

Query Parameters

Parameter	Description
query	Specify a query if you are looking for a single user. The value should be either the member_id or email of the user.
include_department_users	If specified, users in departments of the partner will also be included.
page[number]	Results are paginated, use this to choose which page you want

User Tags

About user tags

User tags can be used to assign custom tag values to a user. Smart Groups can then use these tags to automatically enroll users into courses based on the tag values.

For example, you might set up a "Country" tag type for your account and then for each user set it to their country of residence. Then you could set up smart groups to automatically enroll users in the United States in one course, and users in Canada in a different course.

Set a user's tags

curl https://partners.cerego.com/v3/users/:userid/partner_user_tags \
    -d '{ 
          "tags": [{"partner_user_tag_type_id": "5", "value": "California"}, 
                   {"partner_user_tag_type_id": "9", "value": "Marketing"}] 
        }' \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <API_KEY>"

This endpoint allows you to set tag values for a user. When using this you specify an array of objects, each object having a partner_user_tag_type_id and a value that should be set for that tag type.

Tag types must be set up for your account ahead of time. Contact your customer support representative to know the ids for your account's tag types.

HTTP Request

POST https://partners.cerego.com/v3/users/:userid/partner_user_tags

Request Parameters

Parameter	Type	Required?	Description
tags	array	yes	An array of objects. Each object should have a `partner_user_tag_type_id` and a `value`. For example, if your account has a tag type of "Country" which has an ID of "12" and also a tag type of "Employee ID" which has an ID of "13" then you could set both of them with: [{"partner_user_tag_type_id": "12", "value": "United States"}, {"partner_user_tag_type_id": "13", "value": "B893247"}]

Errors

Cerego uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your Bearer token is wrong.
403	Forbidden -- The resource you requested is not available given your permissions.
404	Not Found -- The specified resource could not be found.
410	Gone -- The resource requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many resources! Slow down!
500	Internal Server Error -- We had a problem with our server. If the problem persists, please email us at support@cerego.com.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.