3.2. EdX Course Catalog API Reference#

The edX Course Catalog API is currently in beta.

You can use the edX Course Catalog API to accomplish the following tasks.

3.2.1. Get a List of All Course Catalogs #

You can use the /catalog/v1/catalogs/ endpoint to get a list of all course catalogs that have been created for you.

3.2.1.1. Method and Endpoint#

Method	Endpoint
GET	`/catalog/v1/catalogs/`

3.2.1.2. Example Request#

curl -X GET -H "Authorization: JWT {access token}" https://api.edx.org/catalog/v1/catalogs/

3.2.1.3. Response Values#

The GET /catalog/v1/catalogs/ request returns the following response values.

Note

Responses to GET requests for the edX Course Catalog API frequently contain the results response value. The results response value is a variable that represents the intended JSON object from the GET request. For the /catalog/v1/catalogs/ endpoint, the results object includes an array of objects that list information about the catalogs that are listed on the current page.

Object	Data Type	Description
`count`	integer	The number of available catalogs.
`next`	string	The URL for the next page of results.
`previous`	string	The URL for the previous page of results.
`results`	array	Information about the current page of catalogs. For more information, see Results Array.

3.2.1.3.1. Results Array#

The results array for the /catalog/v1/catalogs/ endpoint contains the following response values.

Object	Data Type	Description
`id`	integer	The catalog identifier.
`name`	string	The name of the catalog.
`query`	string	The internal query that the server uses to retrieve catalog contents.
`courses_count`	integer	The number of courses this catalog contains.
`viewers`	array[string]	Usernames of users with explicit access to view this catalog.

3.2.1.4. Example Response Showing a List of All Course Catalogs#

The following example response shows a list of all catalogs that are available for a specific user.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "All Courses",
            "query": "*:*",
            "courses_count": 18,
            "viewers": [
                "username1", "username2"
            ]
        }
    ]
}

3.2.2. Get Information about a Specific Catalog #

You can use the /catalog/v1/catalogs/{id}/ endpoint to get information about a specific catalog.

3.2.2.1. Method and Endpoint#

Method	Endpoint
GET	`/catalog/v1/catalogs/{id}/`

3.2.2.2. Example Request#

curl -X GET -H "Authorization: JWT {access token}" https://api.edx.org/catalog/v1/catalogs/1/

3.2.2.3. Response Values#

The GET /catalog/v1/catalogs/{id}/ request returns the following response values.

Object	Data Type	Description
`id`	integer	The catalog identifier.
`name`	string	The name of the catalog.
`query`	string	The query that the server uses to retrieve catalog contents.
`courses_count`	integer	The number of courses this catalog contains.
`viewers`	array[string]	Usernames of users with explicit access to view this catalog.

3.2.2.4. Example Response Showing Information About a Catalog#

The following example response lists information about a single catalog.

{
    "id": 1,
    "name": "All Courses",
    "query": "*:*",
    "courses_count": 18,
    "viewers": [
        "username1", "username2"
            ]
}

3.2.3. Get a List of All Courses in a Catalog #

You can use the /catalog/v1/catalogs/{id}/courses/ endpoint to get a list of all the active courses in a specified catalog, along with details about each course. Active courses are courses that are currently open for enrollment or that will open for enrollment in the future.

3.2.3.1. Method and Endpoint#

Method	Endpoint
GET	/catalog/v1/catalogs/{id}/courses/

3.2.3.2. Example Request#

curl -X GET -H "Authorization: JWT {access token}" https://api.edx.org/catalog/v1/catalogs/1/courses/

3.2.3.3. Response Values#

The GET /catalog/v1/catalogs/{id}/courses/ request returns the following response values.

Note

Responses to GET requests for the edX Course Catalog API frequently contain the results response value. The results response value is a variable that represents the intended object from the GET request. For the /catalog/v1/catalogs/{id}/courses/ endpoint, the results object holds an array of objects that list information about each individual course in the catalog.

Object	Data Type	Description
`count`	integer	The number of active courses in the catalog.
`next`	string	The URL for the next page of results.
`previous`	string	The URL for the previous page of results.
`results`	array	A list of courses in the catalog.

Each JSON object in the results array contains the following response values. Many of these values are also arrays. For more information about these arrays, see Arrays in the Courses Endpoint.

Object	Data Type	Description
`key`	string	The unique identifier for the course.
`title`	string	The title of the course.
`short_description`	string	The short description of the course and its content.
`full_description`	string	The long description of the course and its content.
`level_type`	ENUM string	The course’s level of difficulty. Can be `high_school`, `introductory`, `intermediate`, or `advanced`.
`subjects`	array	Academic subjects that this course covers. See subjects.
`prerequisites`	array	Any courses a learner must complete before enrolling in the current course. See prerequisites.
expected_learning_items`	array	TBA
`image`	array	The About page image for this course. See image.
`video`	array	The course About video. See video.
`owners`	array	The institution that offers the course. See organization.
`sponsors`	array	The corporate sponsor for the course. See organization.
`modified`	datetime	The date and time the course was last modified.
`course_runs`	array	Information about specific runs of the course. See course_runs.
`marketing_url`	string	The URL for the course About page.

3.2.3.3.1. Arrays in the Courses Endpoint#

The response values in the /catalog/v1/catalogs/{id}/courses/ endpoint contain a number of arrays. Some of these arrays contain additional arrays. The following list includes the arrays in the response values for the /catalog/v1/catalogs/{id}/courses/ endpoint.

3.2.3.3.1.1. course_runs#

An array that lists the course runs for each course.

Object	Data Type	Description
`key`	string	The unique identifier for the course.
`title`	string	The title of the course.
`short_description`	string	The short description of the course and its content.
`full_description`	string	The long description of the course and its content.
`start`	datetime	The course start date.
`end`	datetime	The course end date.
`enrollment_start`	datetime	The course enrollment start date.
`enrollment_end`	datetime	The course enrollment end date.
`announcement`	datetime	Day and time when the course will be announced and visible.
`image`	array	See image.
`video`	array	The About video for this course run. See video.
`seats`	array	The available modes for this course. See seats.
`content_language`	string	The language for this course run.
`transcript_languages`	array[string]	ISO codes for languages in which video transcripts are available.
`instructors`	array	Information about the course instructors. See person.
`staff`	array	Information about the course staff. See person.
`pacing_type`	ENUM string	The pacing of the course. May be `self-paced` or `instructor-paced`.
`min_effort`	integer	The minimum number of estimated hours of effort per week.
`max_effort`	integer	The maximum number of estimated hours of effort per week.
`modified`	datetime	The date and time the course was last modified.

3.2.3.3.1.2. image#

The following image objects have identical response values.

image
logo_image
profile_image

The image object has the following response values.

Object	Data Type	Description
`src`	string	The URL where the image is located.
`description`	string	A description of the image.
`height`	integer	The height of the image in pixels.
`width`	integer	The width of the image in pixels.

3.2.3.3.1.3. organization#

The following organization objects have identical response values.

owners
sponsors

The organization object has the following response values.

Object	Data Type	Description
`key`	string	The unique ID for the organization.
`name`	string	The name of the organization.
`description`	string	A description of the organization.
`logo_image`	array	See image.
`homepage_url`	string	The URL of the organization’s home page.

3.2.3.3.1.4. person#

The following person objects have identical response values.

instructor
staff

The person object has the following response values.

Object	Data Type	Description
`key`	string	A unique identifier for the instructor or staff member.
`name`	string	The first and last name of the instructor or staff member.
`title`	string	The official title of the instructor or staff member.
`bio`	string	Biographical information about the instructor or staff member.
`profile_image`	array	See image.

3.2.3.3.1.5. prerequisites#

Any courses a learner must complete before enrolling in the current course.

Object	Data Type	Description
`name`	string	The name of the prerequisite course.

3.2.3.3.1.6. seats#

The available modes for this course.

Object	Data Type	Description
`type`	string	The course mode or modes that the course offers. Possible values are `audit`, `credit`, `honor`, `professional education`, or `verified`.
`price`	string	The cost in USD of a verified certificate, a professional education certificate, or academic credit for the course.
`currency`	string	The currency in which the course accepts payment. This value will always be `USD`.
`upgrade_deadline`	string	The deadline for learners to upgrade from the audit track to the verified certificate track.
`credit_provider`	string	The institution that offers academic credit for learners who pass the course.
`credit_hours`	integer	The number of credit hours that learners who pass the course earn.

3.2.3.3.1.7. subjects#

Academic subjects that this course covers.

Object	Data Type	Description
`name`	string	Name of a subject, such as “computer science” or “history”.

Example values:

Architecture
Chemistry
Computer Science
Economics & Finance
Health & Safety
History
Music
Physics
Social Sciences

3.2.3.3.1.8. video#

Object	Data Type	Description
`src`	string	The URL at which the video is available.
`description`	string	The description of the video.
`image`	array	See image.

3.2.3.4. Example Response Showing Information about a Course#

The following example response shows a single course. A catalog may contain many courses.

{
   "count":123,
   "next":"https://api.edx.org/catalog/v1/catalogs/1/courses/?limit=20&offset=40",
   "previous":"https://api.edx.org/catalog/v1/catalogs/1/courses/?limit=20&offset=0",
   "results":[
      {
         "key":"example_course_key",
         "title":"Title of the Course",
         "short_description":"Short description of course content",
         "full_description":"Longer, more detailed description of course content.",
         "level_type":"Introductory",
         "subjects":[
            {
               "name":"Name of subject"
            }
         ],
         "prerequisites":[

         ],
         "expected_learning_items":[

         ],
         "image":[
            {
               "src":"https://example.com/directory/course_image.jpg",
               "description":"Example image for the Example Title course",
               "height":"300",
               "width":"400"
            }
         ],
         "video":[
            {
               "src":"http://www.youtube.com/watch?v=abcdefghijk",
               "description":null,
               "image":null
            }
         ],
         "owners":[
            {
               "key":"example_institution_key",
               "name":"Example Institution",
               "description":null,
               "logo_image":[
                  {
                     "src":"https://example.com/directory/institution_logo.jpg",
                     "description":null,
                     "height":"200",
                     "width":"200"
                  }
               ],
               "homepage_url":null
            }
         ],
         "sponsors":[

         ],
         "modified":"YYYY-MM-DDTHH:MM:SS.SSSSSSZ",
         "course_runs":[
            {
               "course":"course_number",
               "key":"example_course_key",
               "title":"Title of the Course",
               "short_description":"Short description of course content",
               "full_description":"Longer, more detailed description of course content",
               "start":"YYYY-MM-DDTHH:MM:SSZ",
               "end":"YYYY-MM-DDTHH:MM:SSZ",
               "enrollment_start":"YYYY-MM-DDTHH:MM:SSZ",
               "enrollment_end":"YYYY-MM-DDTHH:MM:SSZ",
               "announcement":null,
               "image":[
                  {
                     "src":"https://example.com/directory/course_image.jpg",
                     "description":null,
                     "height":"200",
                     "width":"300"
                  }
               ],
               "video":null,
               "seats":[
                  {
                     "type":"credit",
                     "price":"100.00",
                     "currency":"USD",
                     "upgrade_deadline":"YYYY-MM-DDTHH:MM:SSZ",
                     "credit_provider":"example institution",
                     "credit_hours":3
                  }
               ],
               "content_language":null,
               "transcript_languages":[

               ],
               "instructors":[

               ],
               "staff":[
                  {
                     "key":"staff_key",
                     "name":"Staff Member Name",
                     "title":"Staff Member Title",
                     "bio":"Example staff member bio.",
                     "profile_image":{
                        "src":"https://example.com/image/staff_member_name.png",
                        "description":null,
                        "height":"150",
                        "width":"150"
                     }
                  }
               ],
               "pacing_type":"instructor_paced",
               "min_effort":null,
               "max_effort":null,
               "modified":"YYYY-MM-DDTHH:MM:SSZ"
            }
         ],
         "marketing_url":"https://example.org/url_for_marketing_materials"
      }
   ]
}