# 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