Introduction

Welcome to the Brainfuse API! You can use our API to access Brainfuse API endpoints, which can get information on various events, subjects, and reports in our database.

The API endpoint for all endpoints mentioned below is https://www.brainfuse.com/api/v1

      ObjectMapper om = new ObjectMapper();
      om.disable(DeserializationFeature.FAIL_ON_IGNORED_PROPERTIES);
      om.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl -X POST "https://www.brainfuse.com/api/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" 
  -d "apiKey=API_KEY"

Make sure to replace API_KEY with your API key.

The above command returns JSON structured like this:

{
"token": "p3~F90EDB437C55411CBFA1DDDCBFA39D93",
"timeZone": "-05:00",
"targetTimeZone": "America/New_York"
}

Brainfuse utilies API keys to obtain authentication tokens. The authentication tokes are short lived tokens that must be passed in the Authorization header of every request. To retrieve an API key please contact your account administrator.

Brainfuse expects the authentication token to be passed in the authorization header of all future API requests that looks like the following:

Authorization: p3~F90EDB437C55411CBFA1DDDCBFA39D93

You must replace API_KEY with your personal API key.

Parameter	Description
apiKey	Your personal API_KEY provided by your Brainfuse account rep.

Grade Topics/Subjects

Get All Grade Topics

curl "https://www.brainfuse.com/api/v1/subjects/gradeTopic" \
  -H "Authorization: TOKEN"

The above command returns JSON structured like this:

{
  "status": "200",
  "gradeLabel": "Topic",
  "subjectLabel": "Subject",
  "gradePlural": "Topics",
  "subjectPlural": "Subjects",
  "grades": [
    {
      "grade": "-1",
      "label": "-- Select Topic --",
      "topics": [
        {
          "id": -1,
          "topic": "-- Select Subject --",
          "subjectID": -1
        }
      ]
    },
    {
      "grade": "Business",
      "label": "Business",
      "topics": [
        {
          "id": -1,
          "topic": "-- Select Subject --",
          "subjectID": -1
        },
        {
          "id": 210,
          "topic": "Accounting",
          "subjectID": 210,
          "categoryID": 150422
        },
        {
          "id": 208,
          "topic": "Economics",
          "subjectID": 208,
          "categoryID": 150423
        },
        {
          "id": 698,
          "topic": "Finance",
          "subjectID": 698,
          "categoryID": 150586
        }
      ]
    }
  ]
}

This endpoint retrieves all available grade topics.

HTTP Request

GET https://www.brainfuse.com/api/v1/subjects/gradeTopic

Reporting

Live Help

curl "/account/{accountID}/reports/usage?startDate={MM/dd/yyyy}&endDate={MM/dd/yyyy} " \
  -H "Authorization: TOKEN"

The above command returns JSON structured like this:

{
  "id": 2,
  "name": "Max",
  "breed": "unknown",
  "fluffiness": 5,
  "cuteness": 10
}

Retrieve the aggregate session stats

HTTP Request

GET /account/{accountID}/reports/usage?startDate={MM/dd/yyyy}&endDate={MM/dd/yyyy}

URL Parameters

Parameter	Description
accountID	accountID provided by Brainfuse for your account
startDate	startDate inclusive for the reporting period in MM/dd/yyyy format
endDate	endDate inclusive for the reporting period in MM/dd/yyyy format

Live Help User Details

curl "/account/{accountID}/usersDetails/liveHelp?startDate={MM/dd/yyyy}&endDate={MM/dd/yyyy}&itemPerPage=100&page=xxx" \
  -H "Authorization: TOKEN"

The above command returns JSON structured like this:

{
  "pages": {
    "numOfPages": 1, /* maximum number of pages available*/
    "__sessionId": "20211103_133052_013",
    "page": 1 /* current page number */
  },
  "LiveSession": [
    {
      "date": "2021-10-29T23:52:11.011Z",
      "username": "Brainfuse username xxxx",
      "subject": "Geometry",
      "account": "Account or Campus Name",
      "collegeID": "College ID",
      "courseName": "Course Name that the student used to login from the LMS",
      "minutes": 10,
      "source": "Brainfuse Instructors/Other",
      "ip": "IP Address used to login",
      "courseId": "courseId that the student used to login from the LMS"
    }
  ]
}

Retrieve the live help details.

HTTP Request

/account/{accountID}/reports/usersDetails/liveHelp?startDate={MM/dd/yyyy}&endDate={MM/dd/yyyy}&itemPerPage=100&page=xxx

URL Parameters

Parameter	Description
accountID	accountID provided by Brainfuse for your account
startDate	startDate inclusive for the reporting period in MM/dd/yyyy format
endDate	endDate inclusive for the reporting period in MM/dd/yyyy format
itemsPerPage	number of items to return
page	the current page to return

Writig Lab User Details

curl "/account/{accountID}/reports/usersDetails/writingLab?startDate={MM/dd/yyyy}&endDate={MM/dd/yyyy}&itemsPerPage=100&page=xxx" \
  -H "Authorization: TOKEN"

The above command returns JSON structured like this:

{
  "pages": {
    "numOfPages": 1, /* number of available pages */
    "__sessionId": "20211103_133626_250",
    "page": 1 /* current page index */
  },
  "WritingLab": [
    {
      "courseName": "Name of the course that the student used to login from the LMS if applicable",
      "account": "Account name or sub campus account",
      "uid": "Brainfuse UID",
      "courseId": "CourseID of the course the student used to login from the LMS if applicable",
      "minutes": 45, /*Number of minutes used for the writing lab*/
      "username": "Brainfuse Username of the student",
      "collegeID": "ID of the student from single sign-on",
      "source": "Brainfuse Instructors/Other",
      "subject": "Subject used ",
      "date": "2021-10-28T04:04:00.000Z"
    }
  ]
}

Retrieve the writing lab details.

HTTP Request

/account/{accountID}/reports/usersDetails/writingLab?startDate={MM/dd/yyyy}&endDate={MM/dd/yyyy}&itemPerPage=100&page=xxx

URL Parameters

Parameter	Description
accountID	accountID provided by Brainfuse for your account
startDate	startDate inclusive for the reporting period in MM/dd/yyyy format
endDate	endDate inclusive for the reporting period in MM/dd/yyyy format
itemsPerPage	number of items to return
page	the current page to return

Boost Attendance

curl "/account/{accountID}/reports/boost/attendance?startDate={MM/dd/yyyy}&endDate={MM/dd/yyyy}&itemsPerPage=100&page=xxx" \
  -H "Authorization: TOKEN"

The above command returns JSON structured like this:

{
  "pages": {
    "numOfPages": 1, /* number of available pages */
    "__sessionId": "20211103_133626_250",
    "page": 1 /* current page index */
  },
  "stats": {
    "overallTotal": 43069,
    "overallAttended": 586,
    "subjects": [
        {
        "attended": 569,
        "total": 40656,
        "absent": 40087,
        "subjectID": 2,
        "subjectName": "Algebra 1"
      },
      {
      "attended": 1,
      "total": 2,
      "absent": 1,
      "subjectID": 3,
      "subjectName": "Geometry"
      }
    ]
  }
  ,"events": [
    {
      "accountID": 206,
      "sisID" : "the sis id if available",
      "eventID": 528940, // the id of the event
      "name": " ", // Student name
      "userName": "AutomationStudent1627451183799", // Brainfuse username
      "userID": 234978, // Brainfuse userID
      "account": "Name of the account or sub account (school or campus name)",
      "startDate": "2021-07-28T05:51:00.000Z", // Start date of the event
      "categoryID": 100,
      "subjectName": "Algebra 1", // Subject name of the event
      "length": 1.2, // optional length of the event only if the student had attended
      "topics": [ // Topics are only included if includeContent is set to true
          {
          "lesson": "AlgebraI1-Packet 1",
          "topic": "Algebraic Applications and Problem Solving"
          },
          {
          "lesson": "AlgebraI1-Packet 1",
          "topic": "Algebraic Applications and Problem Solving"
          },
          {
          "lesson": "AlgebraI10-packetI",
          "topic": "Algebraic Applications and Problem Solving"
          }
        ]
    },
    {
      "accountID": 206,
      "eventID": 528946,
      "name": " ",
      "userName": "AutomationStudent1627451216550",
      "userID": 234980,
      "account": "Tutor Self schedule Test Account (206)",
      "startDate": "2021-07-28T05:51:00.000Z",
      "categoryID": 101,
      "subjectName": "Algebra 1"
    }
  ]
}

Retrieve the list of events that are scheduled for the students along with the attendance of the student.

HTTP Request

/account/{accountID}/reports/boost/attendance?startDate={MM/dd/yyyy}&endDate={MM/dd/yyyy}&itemPerPage=100&page=xxx

URL Parameters

Parameter	Description
accountID	accountID provided by Brainfuse for your account
startDate	startDate inclusive for the reporting period in MM/dd/yyyy format
endDate	endDate inclusive for the reporting period in MM/dd/yyyy format
itemsPerPage	number of items to return
page	the current page to return
includeContent	true/false if true will add the list of content that was completed during the session

Topic Content

Content items are only displayed when includeContent.

Errors

The Brainfuse API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.