Getting started: sending requests via the TeachBoost API

This document outlines how to get started using the TeachBoost Data API. You need to first have an API key before using the API. Please contact us if this is something you're interested in.

Obtaining an API Key

All requests require an API Key to be sent along. You'll see this in the POST body of the example curl requests. Replace YOUR_API_TOKEN with the API token that we give you to perform these requests for your organization.

Data types

Throughout this document, different data types are referenced:

• Integer: a number, 0 or greater
• DateTime: a SQL-formatted datetime string, like 2016-01-02 10:20:00
• String: a normal string value, like "string"
• Date: a SQL-formatted date string, like 2016-01-02
• Time: a SQL-formatted time string, like 10:20:00
• Bool: a value of true or false
• Array: a collection of other data types

Sending requests

The TeachBoost API is a simple HTTP REST API. You can submit queries via the command line by using cURL, or through any other mechanism that can submit HTTP POST requests. Here's an example:

$> curl https://teachboost.com/api/v1/groups --data "token=YOUR_API_TOKEN"

Here's an example where we're also sending in a "flag"—a filter or search parameter that the endpoint accepts. You can add flags by separating them with ampersands (&) like this:

$> curl https://teachboost.com/api/v1/scores --data "token=YOUR_API_TOKEN&start_date=2019-08-20 00:00:00&end_date=2019-12-31 23:59:59"

Note: if you're getting an error sending these flags, try adding the -XPOST flag at the beginning as well to make sure you're sending the data this way:

$> curl -XPOST https://teachboost.com/api/v1/scores ...

Response data format

Data is returned in the JSON format. For more information about JSON please see http://json.org/.

For each API call, you can receive at most 1000 objects at one time. If you have more than 1000 objects to query, you must break your requests up into multiples, and utilize the offset parameter in your queries. The offset corresponds to how many documents from the beginning of the set to start from.

All successful API responses will contain the following fields:

{
    type: String,       // The type of data object
    limit: Integer,     // Maximum amount to be returned
    offset: Integer,    // Offset from the start of the resultset
    total: Integer,     // Total available objects to query
    items: Array        // Response data
}

All failed API requests will respond with the following:

{
    status: 'error',
    message: 'Description of the problem'
}