# Courses API

The Course API allows users to verify which of their courses are available at Classert, as well as insert, update and delete their courses.

It's important to note that every course inserted via API is subject to our approval before being shown at Classpert. You can check the approval process of a given course by checking the approval_status attribute.

# API Key

All requests require a correct API Key, and failing to provide a valid API Key will return Error 401

$ curl 'https://api.classpert.com/developer/v1/courses' \
   -H 'X-Api-Key:  some_invalid_key'

HTTP/2 401
{"hint":"Invalid API Key","details":"Check if your API Key is correct or generate a new one"}

If the API is called without passing any API Key header at all, it will also return Error 401.

$ curl -i 'https://api.classpert.com/developer/v1/courses'

HTTP/2 401
{"hint":"No API Key provided","details":"Missing API Key value in the X-API-Key header"}

# Course Attributes

The Course attributes available for the user to insert, read and update using the Course API are listed in this section.

A detailed explanation for each field can be found in the Course Attributes Documentation page.

# Required attributes

This are the minimum required attributes to insert a new course via the API.

attribute name attribute type
id uuid
name string
url string
slug string
short_description array
long_description json
audio string array
provider_id uuid
pace string
published boolean

# Optional attributes

attribute name attribute type
assessments boolean
assignments boolean
certificate json
duration_in_hours number
free_content boolean
image_url string
instructors json
level string array
number_of_lessons number
offered_by json
paid_content boolean
prices json
provider_rating json
subtitles_text string array
syllabus json
video json
what_you_will_learn json

# GET

Use GET to view the all courses from providers owned by the user. This basic API call will return at most 10 results.

Example:

curl 'https://api.classpert.com/developer/v1/courses' \
   -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

An well formed request will return the HTTP response code 200, an a body containing up to 10 courses, all belonging to the API key defined in the header, in the JSON format.

Example response:

[
  {
    "approval_status": "pending",
    "assessments": false,
    "assignments": false,
    "audio": ["en"],
    "certificate": null,
    "duration_in_hours": null,
    "free_content": false,
    "id": "1a2e35e0-bca3-11ea-98a7-02571a05b831",
    "instructors": [
      {
        "main": true,
        "name": "Jonh Skillo",
        "distinguished": false
      }
    ],
    "image_url": null,
    "last_fetched_at": "2021-08-17T00:00:00+00:00",
    "level": [],
    "long_description": "My course's long description",
    "name": "My course name",
    "number_of_lessons": 1,
    "offered_by": null,
    "pace": "self_paced",
    "paid_content": true,
    "prices": [ { "type": "single_course", "price": "9.99", "currency": "USD", "plan_type": "regular" } ],
    "provider_id": "73c8a601-13d6-4640-a880-e19e13a2ae76",
    "provider_rating": null,
    "published": true,
    "schema_version": "1.0.0",
    "short_description": "My course's short description",
    "slug": "my-course-s-name-1234",
    "subtitles_text": ["en"],
    "syllabus": null,
    "url": "https://www.mywebsite.com/courses/mycourse",
    "video": {
      "id": "987654321",
      "type": "vimeo",
      "thumbnail_url": "https://i.vimeocdn.com/video/1234567890.jpg"
    },
    "what_you_will_learn": null
  }
]

As shown in the example output, the approval_status attribute can be read by the user, but it cannot be set nor changed via API.

# Pagination

You can use the limit and offset query params to the URL to control the pagination of the output.

# Limit

Use the limit param to limit the number of results of the GET. The limit param cannot exceed 100. If no limit param is sent on the API call, it will use limit=10 as default

Example:

curl 'https://api.classpert.com/developer/v1/courses?limit=50' \
   -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

Limits outside the allowed values will return errors. For example, sending a GET request whit limit=9999 in the params:

curl -i 'https://api.classpert.com/developer/v1/courses?limit=9999' \
     -H 'X-Api-Key:  pkWPXMAbTQWBgLsFxlALHg._eEupAZTS5yJck3VaLKwHw4gR1Sd5HS0aO75PE6HkVqAY2E6ZM7JT1aG-FNbey7m3gHegSIiuOSJmfKM9nK5Y-rw'

HTTP/2 500
{"hint":"Limit Too High","details":"Limit should equal at most 100"}

Sending a GET request whit limit=-32 in the params:

curl -i 'https://api.classpert.com/developer/v1/courses?limit=-32' \
     -H 'X-Api-Key:  pkWPXMAbTQWBgLsFxlALHg._eEupAZTS5yJck3VaLKwHw4gR1Sd5HS0aO75PE6HkVqAY2E6ZM7JT1aG-FNbey7m3gHegSIiuOSJmfKM9nK5Y-rw'

HTTP/2 500
{"hint":"Limit Too Low","details":"Limit should equal at least 1"}

# Offset

Use the offset param for pagination, in combination with the limit param.

Example:

curl 'https://api.classpert.com/developer/v1/courses?limit=30&offset=5' \
   -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

Offsets must be a positive number, otherwise an error is returned:

curl -i 'https://api.classpert.com/developer/v1/courses?limit=30&offset=-5' \
   -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

HTTP/2 500
{"hint":"Offset Too Low","details":"Offset should equal at least 0"}

# Filters

The following Query Params can be passed for filtering results:

# Id

Use the id param for searching for a specific course by it's id.

Example:

curl 'https://api.classpert.com/developer/v1/courses?id=85ba6038-f1af-4967-b3d1-fe4c9afc4393' \
   -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

The id param must be an valid UUID, otherwise error 400 is returned

curl -i 'https://api.classpert.com/developer/v1/courses?id=12345' \
    -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

HTTP/2 400
{"hint":null,"details":null,"code":"22P02","message":"invalid input syntax for type uuid: \"12345\""}

# Provider Id

Use the provider_id param to filter for courses from a specific provider_id, for the case when there API Key is linked to more than one provider.

Example:

curl 'https://api.classpert.com/developer/v1/courses?provider_id=d59d9f43-509a-492f-ac2c-b2f67f0edd8a' \
   -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

The provider_id param must be an valid UUID, otherwise error 400 is returned

curl -i 'https://api.classpert.com/developer/v1/courses?provider_id=99999' \
    -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

HTTP/2 400
{"hint":null,"details":null,"code":"22P02","message":"invalid input syntax for type uuid: \"99999\""}

# Name

Use the name param to filter for courses by name. This param is case sensitive and the call will return every course which name that contains the parameter's value.

Example:

curl 'https://api.classpert.com/developer/v1/courses?name=python' \
   -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

The above call will return all courses with python in the name.

# Published

Use the published param to filter for courses by it's published status. It shoulb be adn boolean value, that is, eigther true or false.

Example:

curl 'https://api.classpert.com/developer/v1/courses?published=true' \
   -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

If the published param is not a valid boolen value, the request will return error 400.

curl 'https://api.classpert.com/developer/v1/courses?published=12' \
   -H 'X-Api-Key:  2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

HTTP/2 400
{"hint":null,"details":null,"code":"22P02","message":"invalid input syntax for type boolean: \"12\""}

# POST

Use POST to insert courses. It's required to send a JSON body with at least the course required attributes to create a new course.

Each attribute should follow the specifications defined in the Course Attributes Documentation, otherwise the call will return an error.

Example:

curl -d '{
    "id": "ef1b4a4d-a45b-4fc8-87d4-6e2e1c40f0c2",
    "name": "Example Course",
    "provider_id": "73c8a601-13d6-4640-a880-e19e13a2ae76" ,
    "short_description":  "This is an example course",
    "long_description":  "This is an example course",
    "audio": ["en-US", "pt-BR"],
    "url": "mywebsite.com/example-course",
    "pace": "self_paced"
    }' \
  -H 'Content-Type: application/json' \
  -X POST -i  'https://api.classpert.com/developer/v1/courses' \
  -H 'X-Api-Key: 2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

# Troubleshooting

# A required attribute is not present

All required attributes must be present in the JSON for the POST request to be successful. If any of the required attributes are missing, the API will return error 400:

curl -d '{
    "id": "ef1b4a4d-a45b-4fc8-87d4-6e2e1c40f0c2",
    "name": "Example Course",
    "provider_id": "73c8a601-13d6-4640-a880-e19e13a2ae76" ,
    "short_description":  "This is an example course",
    "long_description":  "This is an example course",
    "audio": ["en-US", "pt-BR"],
    "url": "mywebsite.com/example-course",
    "pace": "self_paced"
    }' \
  -H 'Content-Type: application/json' \
  -X POST -i  'https://api.classpert.com/developer/v1/courses' \
  -H 'X-Api-Key: 2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

HTTP/2 400
{"hint":"url is blank","details":null}

# "Content-Type: application/json" Header is absent

Failing to pass the header Content-Type: application/json will also result in the API returning error 400.

# An attribute is defined incorrectly

If any attribute is incorrect, the API will reject the POST request and return error 400, detailing the mistake. In the bellow example, an invalid syllabus is sent:

curl -d '{
     "id": "ef1b4a4d-a45b-4fc8-87d4-6e2e1c40f0c2",
     "name": "Example Course",
     "provider_id": "73c8a601-13d6-4640-a880-e19e13a2ae76" ,
     "short_description":  "This is an example course",
     "long_description":  "This is an example course",
     "syllabus":  [{"something_wrong": "This is an incorrect long description"}],
     "audio": ["en-US", "pt-BR"],
     "url": "mywebsite.com/example-course",
     "pace": "self_paced"
     }' \
   -H 'Content-Type: application/json' \
   -X POST -i  'https://api.classpert.com/developer/v1/courses' \
   -H 'X-Api-Key: pkWPXMAbTQWBgLsFxlALHg._eEupAZTS5yJck3VaLKwHw4gR1Sd5HS0aO75PE6HkVqAY2E6ZM7JT1aG-FNbey7m3gHegSIiuOSJmfKM9nK5Y-rw'

HTTP/2 400
{"hint":"syllabus should not contain the folowing keys: something_wrong","details":null}

Please check the Course Attributes Documentation page for the definitions and examples of all course attributes

# DELETE

Use DELETE to delete courses. The only required parameter is the course's id.

Example:

curl -X DELETE -i 'https://api.classpert.com/developer/v1/courses?id=ef1b4a4d-a45b-4fc8-87d4-6e2e1c40f0c2' \
  -H 'X-Api-Key: 2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

This call will return 204 even if the course does not exist. Therefore, it's reccomended to the header Accept: application/vnd.pgrst.object+json in order to receive more informative response codes.

curl -X DELETE -i 'https://api.classpert.com/developer/v1/courses?id=ef1b4a4d-a45b-4fc8-87d4-6e2e1c40f0c2' \
  -H 'Accept: application/vnd.pgrst.object+json' \
  -H 'X-Api-Key: 2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

With this header, a well formed request will return the following HTTP response codes:

204 - The course with the id as defined in the url param was deleted

406 - The course with the id as defined in the url param was not deleted, since it does not exist or does not belong to the API Key defined in the headers.

# PATCH

Use PATCH to update courses. It's required to send the course's id on the query parameters and a JSON body with the attributes to be updated.

Each attribute should follow the specifications defined in the Course Attributes Documentation, otherwise the call will return an error.

The request must also include the Content-Type: application/json header.

Example:

curl -d '{
    "short_description":  "This is an updated example course",
    "long_description":  "This is an updated example course",
    "url": "mywebsite.com/example-course-new-url"
    }' \
  -H 'Content-Type: application/json' \
  -X PATCH -i  'https://api.classpert.com/developer/v1/courses?id=ef1b4a4d-a45b-4fc8-87d4-6e2e1c40f0c2' \
  -H 'X-Api-Key: 2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

An well formed request will return the HTTP response code 204.

# Troubleshooting

# The id param was not set

If no id param is sent, the

curl -d '{
    "short_description":  "This is an updated example course",
    "long_description":  "This is an updated example course",
    "url": "mywebsite.com/example-course-new-url"
    }' \
  -H 'Content-Type: application/json' \
  -X PATCH -i  'https://api.classpert.com/developer/v1/courses?id=ef1b4a4d-a45b-4fc8-87d4-6e2e1c40f0c2' \
  -H 'X-Api-Key: 2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

HTTP/2 500
{"hint":"Missing ID","details":"You should provide an id as a query parameter"}

# The id param is incorrect

Trying to pass an incorrect id in the Query Param will result in the API return error 404:

curl -d '{
    "short_description":  "This is an updated example course",
    "long_description":  "This is an updated example course",
    "url": "mywebsite.com/example-course-new-url"
    }' \
  -H 'Content-Type: application/json' \
  -X PATCH -i  'https://api.classpert.com/developer/v1/courses?id=fd929877-0046-4b68-83e8-322fbd0eb31b' \
  -H 'X-Api-Key: pkWPXMAbTQWBgLsFxlALHg._eEupAZTS5yJck3VaLKwHw4gR1Sd5HS0aO75PE6HkVqAY2E6ZM7JT1aG-FNbey7m3gHegSIiuOSJmfKM9nK5Y-rw'

HTTP/2 404

# "Content-Type: application/json" Header is absent

Failing to pass the header Content-Type: application/json will also result in the API returning error 400.

# An attribute is defined incorrectly

If any attribute is incorrect, the API will reject the POST request and return error 400, detailing the mistake. In the bellow example, an invalid syllabus is sent:

curl -d '{
    "short_description":  "This is an updated example course",
    "syllabus":  [{"p": "This is an updated example course"}],
    "url": "mywebsite.com/example-course-new-url"
    }' \
  -H 'Content-Type: application/json' \
  -X PATCH -i  'https://api.classpert.com/developer/v1/courses?id=ef1b4a4d-a45b-4fc8-87d4-6e2e1c40f0c2' \
  -H 'X-Api-Key: 2DG13IFKQQWDhxE5qc0rgw.SH6VJJelRIWSENihKwAKIwVQGVHNLvSW-_Ii2x6-75KgO70MIJyXSBGnXr1Qt8iESgcFdzlZxjT4m0dgE4BPtAdA'

HTTP/2 400
{"hint":"syllabus should not contain the folowing keys: something_wrong","details":null}

Please check the Course Attributes Documentation page for the definitions and examples of all course attributes