SchoolKeep API Documentation

Introduction

The SchoolKeep API is organized around REST and JSON-API. JSON is returned by all API responses, including errors.

Authentication

To use your API key, append to any API request.

GET https://api.schoolkeep.com/v1/courses?api_key=API_KEY

All API requests must be made over HTTPS. API requests without authentication will also fail.


Errors

SchoolKeep uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided. SchoolKeep will follow the JSON-API error spec when encountering an error.

An example error response is as follows:

Status

422

Body

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid Attribute",
      "detail": "Uh oh, that name has already been added",
      "source": {
        "pointer": "/data/attributes/name"
      }
    }
  ]
}

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance you can list people, courses, and groups. These list API methods share a common structure, taking at least these two parameters: page and limit. SchoolKeep utilizes offset-based pagination via the page and limit parameters.

To use pagination, append to any "list" API request.

GET https://api.schoolkeep.com/v1/courses?page=2&limit=10

Pagination links appear in the links object that corresponds to a collection, as described by JSON-API. Pagination keys will be omitted to indicate that a particular link is unavailable.

An example of pagination links included in the returned JSON is as follows:

{
  "links": {
    "self": "https://api.schoolkeep.com/v1/courses?page=2",
    "prev": "https://api.schoolkeep.com/v1/courses",
    "next": "https://api.schoolkeep.com/v1/courses?page=3"
  }
}


Filtering

Any index/listing endpoint will allow filtering of the results. All filtering is done by using the filter query param. Any attribute that is returned in the result for a resource should be able to be used for filtering (eq uuid, or anything listed under attributes).

For brevity, all the examples do not use the full url, but it should be added back when using.

people?filter[name]=foo
should be expanded to
https://api.schoolkeep.com/v2/people?filter[name]=foo

Note, you should "url encode" all values. I am skipping this step here for readability.

Some examples are shown with no trailing [] and examples with a trailing []. The trailing [] is required when providing a list of values (eg see IN usage). When only providing one value, the trailing [] can be used or not, either is supported. For example, the following are identical:

people?filter[email][eq][email protected]
people?filter[email][eq][][email protected]

Equality filtering

Attribute must match value exactly

people?filter[email][eq][email protected]

Contains filtering

Attribute must contain the provided value

people?filter[email][cont]=example.com

One of many filtering

Attribute must match one of the requested values exactly

people?filter[email][in][][email protected]&filter[email][in][][email protected]

Comparison filtering

Compare attribute using provided predicate

groups?filter[membership_count][gteq][]=1

Available predicates: lteq, gteq, lt, gt

Combining filters

For more complex filtering, you may need and or or combinators.

Example, filtering all groups with (membershipcount > 2 and name contains "Admin") or membershipcount = 0

groups?filter[and][or][membership_count][gt]=2&filter[and][or][name][cont]=Admin&filter[and][membership_count][eq]=0


Activities

List activities for a course

Returns a list of activities for a specific course. The activities are returned in sorted order, alphabetically, by activity title.

Endpoint

GET /v2/courses/:course_id/activities

Parameters

Name Description
page Page to view
limit Activities per page
q Query term, filters by activity title

Request

Route

GET https://api.schoolkeep.com/v2/courses/ea210647-aa59-49c1-85d1-5cae0ea6eed0/activities

Response

Status

200

Body

{
  "links": {
    "self": "https://api.schoolkeep.com/v2/courses/ea210647-aa59-49c1-85d1-5cae0ea6eed0/activities"
  },
  "data": [
    {
      "type": "activities",
      "id": "b21fe6b7-8f2b-40e8-a058-f00f1a53e2b5",
      "attributes": {
        "title": "Welcome to SchoolKeep"
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/activities/b21fe6b7-8f2b-40e8-a058-f00f1a53e2b5"
      }
    },
    {
      "type": "activities",
      "id": "95f17021-4a9b-4578-877c-0edb2f092097",
      "attributes": {
        "title": "How to build an effective course"
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/activities/95f17021-4a9b-4578-877c-0edb2f092097"
      }
    }
  ]
}

List activities

Returns a list of activities. The activities are returned in sorted order, alphabetically, by activity title.

Endpoint

GET /v2/activities

Parameters

Name Description
page Page to view
limit Activities per page
q Query term, filters by activity title

Request

Route

GET https://api.schoolkeep.com/v2/activities

Response

Status

200

Body

{
  "links": {
    "self": "https://api.schoolkeep.com/v2/activities"
  },
  "data": [
    {
      "type": "activities",
      "id": "a5537258-0873-4da3-98c2-805d7d31a23d",
      "attributes": {
        "title": "Optimal price point"
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/activities/a5537258-0873-4da3-98c2-805d7d31a23d"
      }
    },
    {
      "type": "activities",
      "id": "b21fe6b7-8f2b-40e8-a058-f00f1a53e2b5",
      "attributes": {
        "title": "Welcome to SchoolKeep"
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/activities/b21fe6b7-8f2b-40e8-a058-f00f1a53e2b5"
      }
    },
    {
      "type": "activities",
      "id": "eb6be363-eef1-4235-aae1-46cf5851c6e5",
      "attributes": {
        "title": "Why design matters"
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/activities/eb6be363-eef1-4235-aae1-46cf5851c6e5"
      }
    },
    {
      "type": "activities",
      "id": "95f17021-4a9b-4578-877c-0edb2f092097",
      "attributes": {
        "title": "How to build an effective course"
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/activities/95f17021-4a9b-4578-877c-0edb2f092097"
      }
    }
  ]
}

Retrieve an activity

Retrieves the details of an activity. You only need to supply the unique activity identifier.

Endpoint

GET /v2/activities/:id

Parameters

Name Description
id Required id

Request

Route

GET https://api.schoolkeep.com/v2/activities/b21fe6b7-8f2b-40e8-a058-f00f1a53e2b5

Response

Status

200

Body

{
  "data": {
    "type": "activities",
    "id": "b21fe6b7-8f2b-40e8-a058-f00f1a53e2b5",
    "attributes": {
      "title": "Welcome to SchoolKeep"
    },
    "links": {
      "self": "https://api.schoolkeep.com/v2/activities/b21fe6b7-8f2b-40e8-a058-f00f1a53e2b5"
    }
  }
}

Assignment Submissions

List assignment submissions for an assignment

Returns a list of assignment submissions for a specific assignment. The assignment submissions are returned in sorted order, with the most recently submitted assignment submissions appearing first.

Endpoint

GET /v2/assignments/:assignment_uuid/submissions

Parameters

Name Description
page Page to view
limit Assignment submissions per page
q Query term, filters by assignment submissions name

Request

Route

GET https://api.schoolkeep.com/v2/assignments/277f4d79-72eb-4c5c-9f40-25b6e94ca49a/submissions

Response

Status

200

Body

{
  "links": {
    "self": "https://api.schoolkeep.com/v2/assignments/277f4d79-72eb-4c5c-9f40-25b6e94ca49a/submissions"
  },
  "data": [
    {
      "type": "assignment_submissions",
      "id": "1a75f5ad-890a-4f24-9d1f-0e4ff135b7fb",
      "attributes": {
        "created_at": "2016-01-02T03:04:05Z"
      },
      "relationships": {
        "assignment": {
          "data": {
            "type": "assignments",
            "id": "277f4d79-72eb-4c5c-9f40-25b6e94ca49a"
          }
        },
        "course": {
          "data": {
            "type": "courses",
            "id": "ea210647-aa59-49c1-85d1-5cae0ea6eed0"
          }
        },
        "person": {
          "data": {
            "type": "people",
            "id": "0a5318a7-72fc-488b-af0f-7b82991dabbe"
          }
        },
        "course_attempt": {
          "data": {
            "type": "course_attempts",
            "id": "f4f3b20a-eb90-4b3c-a8c2-942b49712982"
          }
        }
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/submissions/1a75f5ad-890a-4f24-9d1f-0e4ff135b7fb",
        "download": "http://filepicker.io/assignment.pdf"
      }
    },
    {
      "type": "assignment_submissions",
      "id": "22e71d93-6f57-4b8d-b5fb-b2010d1ccce8",
      "attributes": {
        "created_at": "2016-01-02T03:04:05Z"
      },
      "relationships": {
        "assignment": {
          "data": {
            "type": "assignments",
            "id": "277f4d79-72eb-4c5c-9f40-25b6e94ca49a"
          }
        },
        "course": {
          "data": {
            "type": "courses",
            "id": "ea210647-aa59-49c1-85d1-5cae0ea6eed0"
          }
        },
        "person": {
          "data": {
            "type": "people",
            "id": "dba33949-18d3-4f7d-83ee-8de8c1370b31"
          }
        },
        "course_attempt": {
          "data": {
            "type": "course_attempts",
            "id": "e000dc08-97a7-43e6-b231-1a4575aea8ed"
          }
        }
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/submissions/22e71d93-6f57-4b8d-b5fb-b2010d1ccce8",
        "download": "http://filepicker.io/assignment.pdf"
      }
    }
  ]
}

List all assignment submissions

Returns a list of assignment submissions for all assignments. The assignment submissions are returned in sorted order, with the most recently submitted assignment submissions appearing first.

Endpoint

GET /v2/submissions

Parameters

Name Description
page Page to view
limit Assignment submissions per page
q Query term, filters by assignment submissions name

Request

Route

GET https://api.schoolkeep.com/v2/submissions

Response

Status

200

Body

{
  "links": {
    "self": "https://api.schoolkeep.com/v2/submissions"
  },
  "data": [
    {
      "type": "assignment_submissions",
      "id": "270c5a53-c033-459f-8801-b08787f1e5d0",
      "attributes": {
        "created_at": "2016-01-02T03:04:05Z"
      },
      "relationships": {
        "assignment": {
          "data": {
            "type": "assignments",
            "id": "0a932514-57b1-4d05-927e-47878a842fe2"
          }
        },
        "course": {
          "data": {
            "type": "courses",
            "id": "b685091b-6f65-4c20-9ba8-132b5ffbddde"
          }
        },
        "person": {
          "data": {
            "type": "people",
            "id": "0a5318a7-72fc-488b-af0f-7b82991dabbe"
          }
        },
        "course_attempt": {
          "data": {
            "type": "course_attempts",
            "id": "ee5c12ab-77ce-41f3-8db9-753fa7bfae60"
          }
        }
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/submissions/270c5a53-c033-459f-8801-b08787f1e5d0",
        "download": "http://filepicker.io/assignment.pdf"
      }
    },
    {
      "type": "assignment_submissions",
      "id": "1a75f5ad-890a-4f24-9d1f-0e4ff135b7fb",
      "attributes": {
        "created_at": "2016-01-02T03:04:05Z"
      },
      "relationships": {
        "assignment": {
          "data": {
            "type": "assignments",
            "id": "277f4d79-72eb-4c5c-9f40-25b6e94ca49a"
          }
        },
        "course": {
          "data": {
            "type": "courses",
            "id": "ea210647-aa59-49c1-85d1-5cae0ea6eed0"
          }
        },
        "person": {
          "data": {
            "type": "people",
            "id": "0a5318a7-72fc-488b-af0f-7b82991dabbe"
          }
        },
        "course_attempt": {
          "data": {
            "type": "course_attempts",
            "id": "f4f3b20a-eb90-4b3c-a8c2-942b49712982"
          }
        }
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/submissions/1a75f5ad-890a-4f24-9d1f-0e4ff135b7fb",
        "download": "http://filepicker.io/assignment.pdf"
      }
    },
    {
      "type": "assignment_submissions",
      "id": "22e71d93-6f57-4b8d-b5fb-b2010d1ccce8",
      "attributes": {
        "created_at": "2016-01-02T03:04:05Z"
      },
      "relationships": {
        "assignment": {
          "data": {
            "type": "assignments",
            "id": "277f4d79-72eb-4c5c-9f40-25b6e94ca49a"
          }
        },
        "course": {
          "data": {
            "type": "courses",
            "id": "ea210647-aa59-49c1-85d1-5cae0ea6eed0"
          }
        },
        "person": {
          "data": {
            "type": "people",
            "id": "dba33949-18d3-4f7d-83ee-8de8c1370b31"
          }
        },
        "course_attempt": {
          "data": {
            "type": "course_attempts",
            "id": "e000dc08-97a7-43e6-b231-1a4575aea8ed"
          }
        }
      },
      "links": {
        "self": "https://api.schoolkeep.com/v2/submissions/22e71d93-6f57-4b8d-b5fb-b2010d1ccce8",
        "download": "http://filepicker.io/assignment.pdf"
      }
    }
  ]
}

Events

List events

Returns a list of events. The events are returned in sorted order, chronologically, by creation date.

Endpoint

GET /v2/events

Parameters

Name Description
page Page to view
limit Events per page

Request

Route

GET https://api.schoolkeep.com/v2/events

Response

Status

200

Body

{
  "links": {
    "self": "https://api.schoolkeep.com/v2/events"
  },
  "data": [
    {
      "type": "learner_viewed_activity_events",
      "attributes": {
        "created_at": "2016-01-02T03:04:05Z"
      },
      "relationships": {
        "person": {
          "data": {
            "type": "people",
            "id": "0a5318a7-72fc-488b-af0f-7b82991dabbe"
          }
        },
        "activity": {
          "data": {
            "type": "activities",
            "id": "b21fe6b7-8f2b-40e8-a058-f00f1a53e2b5"
          }
        }
      }
    },
    {
      "type": "learner_viewed_video_activity_events",
      "attributes": {
        "created_at": "2016-01-02T03:04:05Z",
        "percentage_watched": 0.5
      },
      "relationships": {
        "person": {
          "data": {
            "type": "people",
            "id": "dba33949-18d3-4f7d-83ee-8de8c1370b31"
          }
        },
        "activity": {
          "data": {
            "type": "activities",
            "id": "95f17021-4a9b-4578-877c-0edb2f092097"
          }
        }
      }
    }
  ]
}

People

List people

Returns a list of people. The people are returned in sorted order, alphabetically, by full name.

Endpoint

GET /v2/people

Parameters

Name Description
page Page to view
limit People per page
q Query term, filters by people name

Request

Route

GET https://api.schoolkeep.com/v2/people

Response

Status

200

Body

{
  "links": {
    "self": "https://api.schoolkeep.com/v2/people"
  },
  "data": [
    {
      "type": "people",
      "id": "dba33949-18d3-4f7d-83ee-8de8c1370b31",
      "attributes": {
        "activated_at": "2016-02-03T05:00:00.000Z",
        "created_at": "2016-01-02T03:04:05Z",
        "custom_avatar_url": "https://secure.gravatar.com/avatar/0c6a133b99d05036bd6c7ee15bcee2f1?d=identicon&s=200",
        "email": "[email protected]",
        "full_name": "Albert Einstein",
        "registration_status": "activated",
        "unsubscribed": false,
        "updated_at": "2017-06-23T18:27:45Z"
      },
      "links": {
        "self": {
          "href": "https://api.schoolkeep.com/v1/people/dba33949-18d3-4f7d-83ee-8de8c1370b31",
          "methods": [
            "get",
            "delete"
          ]
        },
        "teaching": {
          "href": "https://app.schoolkeep.com/people/dba33949-18d3-4f7d-83ee-8de8c1370b31",
          "methods": [
            "get",
            "patch"
          ]
        }
      },
      "relationships": {
        "partnerships": {
          "data": [
            {
              "type": "partnerships",
              "id": "5914811c-b4c5-4ac4-9e6d-294c3b77d024"
            },
            {
              "type": "partnerships",
              "id": "04aca00c-57f4-4b5f-abc7-cdb587683b9b"
            }
          ]
        },
        "school": {
          "data": {
            "type": "schools",
            "id": "5f72a658-292b-4cc1-8507-0f1c5b820427"
          }
        }
      }
    },
    {
      "type": "people",
      "id": "0a5318a7-72fc-488b-af0f-7b82991dabbe",
      "attributes": {
        "activated_at": "2016-02-03T05:00:00.000Z",
        "created_at": "2016-01-02T03:04:05Z",
        "custom_avatar_url": "https://secure.gravatar.com/avatar/5db98633b984fca1d7e506e28d6f71a8?d=identicon&s=200",
        "email": "[email protected]",
        "full_name": "Marie Curie",
        "registration_status": "activated",
        "unsubscribed": false,
        "updated_at": "2017-06-23T18:27:45Z"
      },
      "links": {
        "self": {
          "href": "https://api.schoolkeep.com/v1/people/0a5318a7-72fc-488b-af0f-7b82991dabbe",
          "methods": [
            "get",
            "delete"
          ]
        },
        "teaching": {
          "href": "https://app.schoolkeep.com/people/0a5318a7-72fc-488b-af0f-7b82991dabbe",
          "methods": [
            "get",
            "patch"
          ]
        }
      },
      "relationships": {
        "partnerships": {
          "data": [
            {
              "type": "partnerships",
              "id": "bfbe773f-e2bf-49ac-ab6b-05166848c2cb"
            },
            {
              "type": "partnerships",
              "id": "ad727cdf-d74e-4924-b0b7-73bfe7da2c00"
            }
          ]
        },
        "school": {
          "data": {
            "type": "schools",
            "id": "5f72a658-292b-4cc1-8507-0f1c5b820427"
          }
        }
      }
    },
    {
      "type": "people",
      "id": "e598cb5b-d172-464b-93ec-0631fb491f1d",
      "attributes": {
        "activated_at": "2017-06-23T18:27:45.498Z",
        "created_at": "2016-01-02T03:04:05Z",
        "custom_avatar_url": "https://secure.gravatar.com/avatar/ec72c16a8303b3108cf5d4d32a2ccb28?d=identicon&s=200",
        "email": "[email protected]",
        "full_name": "Nikola Tesla",
        "registration_status": "activated",
        "unsubscribed": false,
        "updated_at": "2017-06-23T18:27:45Z"
      },
      "links": {
        "self": {
          "href": "https://api.schoolkeep.com/v1/people/e598cb5b-d172-464b-93ec-0631fb491f1d",
          "methods": [
            "get"
          ]
        },
        "teaching": {
          "href": "https://app.schoolkeep.com/people/e598cb5b-d172-464b-93ec-0631fb491f1d",
          "methods": [
            "get",
            "patch"
          ]
        }
      },
      "relationships": {
        "partnerships": {
          "data": [
            {
              "type": "partnerships",
              "id": "41cad80f-dafa-4b5a-861e-aab58278d096"
            },
            {
              "type": "partnerships",
              "id": "5a7c127e-bd97-40af-96f3-06ff26deee31"
            }
          ]
        },
        "school": {
          "data": {
            "type": "schools",
            "id": "5f72a658-292b-4cc1-8507-0f1c5b820427"
          }
        }
      }
    }
  ]
}

Create a person

Creates a new person, and sends an invite.

If your school is using URL Authentication, this request will be forbidden.

Endpoint

POST /v2/people

Parameters

Name Description
data[type] Required Data type
data[attributes][email] Required Data attributes email

Request

Route

POST https://api.schoolkeep.com/v2/people

Body

{
  "data": {
    "type": "people",
    "attributes": {
      "email": "[email protected]"
    }
  }
}

Response

Status

201

Body

{
  "data": {
    "type": "people",
    "id": "216e9db2-e25b-45c8-8b16-25ffa2eabad7",
    "attributes": {
      "created_at": "2016-02-03T04:05:06Z",
      "custom_avatar_url": "https://secure.gravatar.com/avatar/145d91397b5940d06343b51d4761eb08?d=identicon&s=200",
      "email": "[email protected]",
      "registration_status": "not_activated",
      "unsubscribed": false,
      "updated_at": "2016-02-03T04:05:06Z"
    },
    "links": {
      "self": {
        "href": "https://api.schoolkeep.com/v1/people/216e9db2-e25b-45c8-8b16-25ffa2eabad7",
        "methods": [
          "get",
          "delete"
        ]
      },
      "teaching": {
        "href": "https://app.schoolkeep.com/people/216e9db2-e25b-45c8-8b16-25ffa2eabad7",
        "methods": [
          "get",
          "patch"
        ]
      }
    },
    "relationships": {
      "partnerships": {
        "data": [
          {
            "type": "partnerships",
            "id": "abb2cfe0-0fad-4f43-a02e-326ec5a8b3f1"
          }
        ]
      },
      "school": {
        "data": {
          "type": "schools",
          "id": "5f72a658-292b-4cc1-8507-0f1c5b820427"
        }
      }
    }
  }
}