• Overview
  • API Semantics
  • Personalized Practice API
  • Events API
  • Personalization Primitives API
  • Analytics API
  • Object Model
  • Overview

    Sana Web API is the primary way to integrate with Sana to make your learning product more adaptive. With this guide, we explain and provide code examples for use cases like adding personalization to your practice feature or how to take advantage of Sana to gain insights into users behaviours.

    Click one of the API offerings below to get started or continue reading our API semantics.

    API Semantics

    This section explains the semantics of our Rest API. It includes common information that is valid for all the endpoints.

    API Endpoints

    The base URL for all our endpoints is https://api.sanalabs.com. Please note that non-secure access to the API is not available. All HTTP requests will be redirected to HTTPS automatically.

    Authentication

    A valid API key is needed to access the Sana Web API. Contact Sana Labs to get your own API key. Your API keys carry privileges for you to access Sana Web API, be sure to keep them secret. Do not share your API keys in publicly accessible places such as Github or client-side code.

    Sana Web API expects the API key to be included in all API requests to the server in a header that looks like the following:

    X-API-KEY: $API_KEY

    If the key is omitted or is wrong, you will get a 401 Unauthorized response to your request.

    To authorize, pass the X-API-KEY header

    curl 
      -H "X-API-KEY: $API_KEY"
      https://api.sanalabs.com/v1/next-exercises
    
    

    Make sure to replace $API_KEY with your API key.

    Rate Limits

    There is no hard rate limit at the moment where Sana will drop your data. However, if you need to make requests at a rate exceeding 200 req/s, please contact Sana Labs first. Requests include all the endpoints of Sana Web API.

    Max Request Size

    The maximum request size is 16 KB per call without exception. You will get a 400 Bad Request if these limits are exceeded.

    Content-Type

    Sana Web API consumes and produces JSON data. The content-type header must be set to application/json when calling Web API endpoints.

    Errors

    All endpoints either result in success or an error. The API returns 200 or 201 for successful requests and relevant HTTP status code and an ErrorResponse object in case of an error. See the HTTP Error Status Codes section for the HTTP Status Codes Sana Web API returns.

    Error Status Codes

    The Sana Web API uses the following error codes:

    Error Code Error Text Error Description
    400 Bad Request Your request is invalid.
    401 Unauthorized No API Key or your API key is wrong.
    404 Not Found The specified resource could not be found.
    405 Method Not Allowed You tried to access a resource with an invalid method.
    500 Internal Server Error There was a problem on the server side. Please try again later.
    503 Service Unavailable The API is temporarily offline for maintenance. Please try again later.

    Personalized Practice API

    Personalized Practice API allows you to easily customize exercise-based features, such as review sessions, to the progress made by the individual user. You can simply request what exercise to present next, given that the outcomes of previously completed exercises have been posted to Sana. The API allows you to specify constraints and targets for every recommendation.

    Modes of Usage

    The Personalized Practice API allows for different modes of usage. Exercises can be requested one at a time, allowing the system to adapt to the most recent outcome, as visualized below.

    Personalized Practice Single Image

    Another option is to request a sequence of exercises (the next "quiz" or "session") in a single call and post back the outcomes either in one batch or one-by-one as they are completed.

    Personalized Practice Batch Image

    In case the next exercise should be displayed immediately after completion of a previous exercise - when there is no intermediate step where the result is displayed to the user - it is recommended to post the outcome of the previous exercise as part of the request for the next one.

    Personalized Practice Combined Image

    Posting Exercise Outcomes

    Posts the outcomes of completed exercises to Sana. Posting of exercise outcomes is required for Sana to make personalized recommendations of what exercises to display next.

    Endpoint

    POST /v1/exercise-outcomes

    Body Parameters

    Parameter Mandatory Type Description
    user_id Yes string Unique id of the user on the partner side.
    exercise_outcomes Yes array of Exercise Outcome objects The outcome of one or more exercises completed by the user.

    Response Format

    On success, the HTTP status code in the response header is 200 OK and the response body is empty. On error, the header status code is an error code and the response body contains a list of Error Response objects.

    Example

    Note that you need to escape the quotation marks in the JSON body to use it with curl.

    curl "https://api.sanalabs.com/v1/exercise-outcomes"
      -H "Content-Type: application/json"
      -H "X-API-KEY: $API_KEY"
      -X POST
      -d '{
            "user_id": "user",
            "exercise_outcomes": [
              {
                "exercise": {
                  "id": "exercise_id",
                  "path": "/IB/math/vectors/",
                  "tags": ["tag1", "tag2"],
                  "difficulty_level": 1,
                  "max_score": 1.,
                  "metadata": ""
                },
                "outcome": {
                  "timestamp": "2018-01-05T15:11:30Z",
                  "time_spent_ms": 2000,
                  "result": "correct",
                  "score": 1.,
                  "metadata": ""
                }
              }
            ]
          }'
    

    Getting Next Exercises

    Gets recommended sequence of exercises to present next.

    Endpoint

    POST /v1/next-exercises

    Body Parameters

    Parameter Mandatory Type Description
    user_id Yes string Unique id of the user on the partner side.
    num_exercises No int The number of exercises requested. Defaults to 1. Note that with num_exercises > 1, the order of the returned exercises is also optimized. For maximal adaptivity, request one exercise at a time and post back the outcome before requesting the next exercise.
    constraints No Constraint object Constraints specifying the set of exercises that can be selected from.
    target No Target The target that the exercise recommendation is optimized for.
    exercise_outcomes No array of Exercise Outcome objects The outcome of one or more exercises completed by the user. If next-exercises is called immediately after completion of a previous exercise it is recommended to post back the outcome as part of the next-exercises call instead of using the separate exercise-outcomes endpoint.

    Response Format

    On success, the HTTP status code in the response header is 200 OK and the response body is as below. On error, the header status code is an error code and the response body contains a list of ErrorResponse objects.

    Parameter Type Description
    exercises An array of Exercise Objects The recommended (sequence of) exercise(s) to present to the user.

    Example

    Note that you need to escape the quotation marks in the JSON body to use it with curl.

    curl "https://api.sanalabs.com/v1/next-exercises"
      -H "Content-Type: application/json"
      -H "X-API-KEY: $API_KEY"
      -X POST
      -d '{
            "user_id": "user",
            "num_exercises": 5,
            "target": {
              "challenge_level": 0.5
            },
            "constraints": {
              "is_review": false,
              "paths": ["/IB/math/vectors", "/IB/math/algebra/"],
              "tags": ["tag1", "tag2"]
            }
            "exercise_outcomes": []
          }'
    

    Events API

    The Events API lets you send any events describing the interactions between users and your learning product to Sana. All such interactions are taken into account to tailor Sana's recommendations further.

    Personalization Primitives API

    The Personalization Primitives API lets you query the high-level properties that Sana predicts to personalize content to the user. Here are some examples of the information available:

    Analytics API

    The Analytics API lets you retrieve Analytics data to automate complex reporting tasks and build custom dashboards. With the Analytics API you can for example:

    Object Model

    This section describes the objects that are used throughout the different endpoints.

    Exercise Outcome

    key Mandatory Type Description
    exercise Yes Exercise The exercise the user completed.
    outcome Yes Outcome The outcome of the completed exercise.

    Exercise

    key Mandatory Type Description
    id Yes string ID of the exercise.
    path Yes string The location of the exercise in the content hierarchy, e.g. "subject/topic/lesson/unit".
    tags No array of strings Any available tagging of exercises (that does not correspond to other keys of the exercise object) based on which you want to formulate constraints when requesting next-exercises. For example ["NationalExamQuestion", "Year2018"].
    difficulty_level No float Partner's tagging of the exercise's difficulty. Note that Sana automatically models the difficulty with respect to each individual user's knowledge state independent of this property. It can, however, be used as a complementary feature and useful for analytics purposes.
    max_score No float Maximum possible score of exercise (if there is partial scoring of the user's response).
    metadata No string It is recommended to add any available additional metadata about the exercise. Sana makes use of this as features for better predictions and recommendations. Send metadata in a human-readable format such as a JSON string.

    Outcome

    key Mandatory Type Description
    timestamp Yes string ISO 8601 timestamp of when exercise was completed.
    time_spent_ms No int The time spent on solving the exercise in milliseconds.
    result Yes string Denotes if the exercise was successfully completed. One of "correct", "incorrect", "partially_correct" and "skipped".
    score No float The score given if the exercise supports partial scoring.
    metadata No string It is recommended to add any available additional metadata about the outcome of user's completion of the exercise. Sana makes use of this as features for better predictions and recommendations. Send metadata in a human-readable format such as a JSON string.

    Constraint

    key Mandatory Type Description
    is_review No bool Set to true if only exercises related to concepts already covered by the user should be selected. Defaults to false. Note that with review false, previously completed exercises might still be returned if deemed the optimal next step.
    paths No Array of strings The location of the exercise in the content hierarchy (as specified by path parameter of Exercise). The recommended exercises will be from one of the paths specified. It is possible to specify the path to any level in the hierarchy. If there for example are three topics under a specific subject "/subject_1/topic_{1,2,3}/" you can get exercises recommended from subject_1 either by specifying ["/subject_1/"] or ["/subject_1/topic_1", "/subject_1/topic_2", "/subject_1/topic_3"].
    tags No Array of strings Only exercises with at least one of the tags specified will be recommended.

    Target

    The purpose of the target object is to allow the learning experience developer (or potentially the user) to express what aspects to optimise recommendations for. The properties are intrinsically "abstract" and "subjective" in their nature and are used as guidance for the recommendation strategy. Any property can be left unspecified indicating "fully personalized", leaving the decision to Sana.

    Besides this specification of a "temporary" target, the recommendations are over time optimized towards increased user engagement and learning efficacy - and potentially towards your specific Key Performance Indicators as agreed upon with Sana Labs.

    key Mandatory Type Description
    challenge_level No float Value between 0.0 and 1.0 indicating the level of challenge for the user.

    Error

    Key Type Description
    status int HTTP Status code related to this error
    detail string Details of the error
    link string URL to read more about this error

    Error Response

    Key Type Description
    errors An array of Error Objects Errors associated with this request