• Sana Learn Overview
  • Content Registry Endpoints
  • Real Time Endpoints
  • Analytics Endpoints
  • Object Model
  • Glossary
  • API Semantics
  • Sana Learn Overview

    Sana Learn API allows you to easily customize exercise-based practice sessions, such as review sessions, to the progress and performance of the individual user. You can simply request what exercise should be presented next, given that the outcomes of previously completed exercises have been posted to Sana Learn API. The API allows you to specify a content filter and practice mode for every recommendation. Have a look at our Demo Application to see an example of how the Sana Learn API can be integrated with a generic Quiz app.

    Exercises can be requested one at a time, allowing the system to adapt to the most recent outcome, as visualized below.

    Sana Learn 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. Note that the app should wait for the response of the latest posted event before making a call to the next-assets endpoints, so that it is guaranteed that the Sana backend takes the latest event into account when serving the next recommendation.

    Sana Learn Batch Image

    Content Registry Endpoints

    To get real-time recommendations from the Sana Learn API, it is required that a registry of the available assets is exported to Sana Labs and put into a view.

    The Asset Bank contains a registry of all your content’s metadata, i.e. the content itself does not have to be exported to Sana Labs, just references to the available assets and any available metadata (tags). The tags can be used for filtering and selection as well as for algorithms and analytics.

    A view is a collection of assets from the asset bank. It defines the context in which a user interacts with content. Any real-time modelling happens within a view. Any next asset recommendations happen within a view. Also response submit events should be posted with a view.

    Content Registry Overview

    Asset Management

    In order to work with views, a registry of assets must be created.

    Create / Update an Asset

    Creates or updates the provided asset. If the provided asset_id doesn’t exist in Sana Content Registry, the asset is created, otherwise the asset is updated with the provided parameters in the body.

    Endpoint

    PUT /v1/assets/<asset_id>

    Body Parameters

    Key Mandatory Type Description
    type Yes String The type of asset, either exercise or theory. The asset type defines the expected structure of the properties object.
    tags No Array of Tag objects Any free-form tagging of asset. Can be used for retrieval/filtering in API. Reserved tag names: content_type (with value equal to e.g. mcq, text or video).
    description No String Any free-form description of the asset (maximum 5000 characters). For exercises and shorter theory sections it is recommended to put the whole question or theory text into the asset description. This information can be used for content analysis.
    content_url No String If it is possible to access the actual content by a URL, it is recommended to provide this information.
    attributes No Object An object with fields containing asset metadata (allowed types are String and Number).

    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.

    Delete an Asset

    Endpoint

    DELETE /v1/assets/<asset_id>

    Response

    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.

    Get an Asset

    Endpoint

    GET /v1/assets/<asset_id>

    Response Format

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

    Bulk Create / Update

    Lets you to bulk create or update assets. This is useful if the content registry is large and many elements have to be created / updated.

    Endpoint

    PUT /v1/assets

    Body Parameters

    Key Mandatory Type Description
    assets Yes Array of Asset Definition objects. The items to be created/updated. It is possible to create/update a maximum of 1000 assets per call.

    Response Format

    On success, HTTP Status Code 200 OK with an empty body. This means that all the individual assets have been successfully created / modified. This operation is atomic, meaning that either all individual items are created/updated or none of them are created/updated. On error, the header status code is an error code and the response body contains a list of Error Response objects.

    Bulk Delete

    Lets you delete items in bulk. The items will be deleted if they exist.

    Endpoint

    DELETE /v1/assets

    Query String Parameters

    Key Mandatory Type Description
    asset_ids Yes Array of Strings The asset IDs to be deleted.

    Response Format

    On success, the HTTP Status Code is 200 OK and the response body is as below. This means that all the individual assets have been successfully deleted. This operation is atomic, meaning that on success all individual items are deleted and on failure none of them are deleted. Note that non-existing asset_ids are ignored and not considered an error.

    Key Type Description
    asset_ids Array of Strings The asset IDs that were deleted. If IDs for assets that do not exist are passed in the request body, they will not be found in this list.

    On error, the header status code is an error code and the response body contains a list of Error Response objects.

    Get Multiple Assets

    Lets you get multiple assets.

    Endpoint

    GET /v1/assets

    Query String Parameters

    Key Mandatory Type Description
    asset_ids Yes Array of Strings IDs of the assets to be queried. It is possible to query a maximum of 100 assets in a single call.

    Response Format

    On success, the HTTP Status Code is 200 OK and the response body as below. This means that all the queried assets have been successfully fetched.

    Key Type Description
    assets Array of Asset Definition objects The assets queried.

    On error, the header status code is an error code and the response body contains a list of Error Response objects.

    Views Management

    A view is a collection of assets from your asset bank. A view can represent hierarchical structure as well as (optionally) the default sequential order of the assets. The structure defined in a view is used to express the focus of Sana Learn sessions and is also utilized by the recommendation algorithm. A view defines the context in which a user interacts with content - allowing the recommendation algorithm to model assets differently in different views. Any real-time modelling for next-asset recommendations happens within a view, but content insights can also be transferred between views regularly.

    There is currently a limit of 1000 assets in a view, so it is important to select a reasonable split of your content into different views based on this.

    Create / Update a View

    Lets you create or update a view with the provided assets. If a view with the provided id already exists, the view will be updated, otherwise it will be created. Note that a reference to all assets that belong to this view should be provided when creating or updating a view.

    Endpoint

    PUT /v1/views/<view_id>

    Body Parameters

    Key Mandatory Type Description
    name Yes String The name of the view.
    description No String A description of the view.
    ordered No Boolean Specifies whether there is a default ordering of the assets in the view.
    assets Yes Array of View Item objects The assets in this view. If there is a default sequential ordering of the content it should be represented by the order of assets and ordered should be set to True.

    Response Format

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

    Delete a view

    Deletes the view with the provided id.

    Endpoint

    DELETE /v1/views/<view_id>

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

    Get a view

    Gets the view with the provided id.

    Endpoint

    GET /v1/views/<view_id>

    Response Format

    On success, the HTTP Status Code is 200 OK and the response body is as below.

    Key Type Description
    id String The ID of the view.
    name String The name of the view.
    description String The description of the view.
    ordered Boolean Specifies whether there is a default ordering of the assets in the view.
    assets Array of View Item objects The assets in this view.

    On error, the header status code is an error code and the response body contains a list of Error Response objects.

    Real Time Endpoints

    The following set of endpoints should be called with every user interaction as described in the Overview.

    Posting User Events

    Posts user events to Sana. Posting of events is required for Sana to make personalized recommendations of what exercises to display next. The following event types are currently supported in the Sana Learn API:

    Event Type Description
    response_submit Should be sent whenever a user has completed an exercise.
    theory_viewed Should be sent whenever a user has viewed a theory asset.

    All user events are sent through the same API endpoint. However each event has its own unique attributes.

    Endpoint

    POST /v1/user-events

    Body Parameters

    Key Mandatory Type Description
    user_events Yes Array of User Event objects The user events to post (max 1000 per call).

    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

    curl "https://api.sanalabs.com/v1/user-events" \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: $API_KEY" \
      -X "POST" \
      -d '{
        "user_events": [{
                "user": {
                    "id": "123",
                    "type": "learner"
                },
                "type": "theory_viewed",
                "timestamp": "2018-01-05T15:11:30Z",
                "attributes": {
                    "view_id": "ABC",
                    "asset_id": "abc",
                    "time_spent_ms": 7050
                }
            },
            {
                "user": {
                    "id": "123",
                    "type": "learner"
                },
                "type": "response_submit",
                "timestamp": "2018-01-05T15:11:36Z",
                "attributes": {
                    "view_id": "ABC",
                    "asset_id": "abd",
                    "result": "correct",
                    "score": 1,
                    "time_spent_ms": 4100
                }
            }
        ]
    }'
    

    Getting Next Assets

    Obtains a recommended sequence of assets to present next.

    Endpoint

    POST /v1/next-assets

    Body Parameters

    Key Mandatory Type Description
    user Yes User object The User object that uniquely identifies a user.
    view_id Yes String ID of the view for which the practice is carried out.
    filter Yes Asset Filter object Specifying the subset of assets within the view that can be selected from. i.e. the filter expresses the focus of the practice in terms of available content.
    mode Yes Mode object Defines the mode or “purpose” of the session.
    limit Yes Integer The number of assets to return.
    user_events No Array of User Event objects If provided, these user events will be ingested into Sana's recommendation system and will influence which assets will be included in the response.

    Response Format

    On success, the HTTP status code in the response header is 200 OK and the response body is as below.

    Key Type Description
    data An array of Asset Reference objects The recommended sequence of assets to present to the user.

    On error, the header status code is an error code and the response body contains a list of Error Response objects.

    Example

    Request

    curl "https://api.sanalabs.com/v1/next-assets" \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: $API_KEY" \
      -X "POST" \
      -d '{
        "user": {
            "id": "123",
            "type": "learner"
        },
        "view_id": "ABC",
        "filter": {
            "asset_types": ["exercise"],
            "view_paths": ["/math/algebra"],
            "tags": [{
                "name": "exam_year",
                "value": "2017"
            }, {
                "name": "exam_year",
                "value": "2018"
            }]
        },
        "mode": {
            "type": "review",
            "attributes": {}
        },
        "limit": 1
    }'
    

    Response

    '{"data": [{"asset_id": "A1"}, {"asset_id": "A2"}]}'
    

    Getting User Status by Filters

    Get a user's status by view and filters.

    Endpoint

    POST /v1/user-filter-status

    Body Parameters

    Key Mandatory Type Description
    user_id Yes String ID of the user.
    view_id Yes String ID of the view for which the status is queried.
    filters Yes Array of Filter objects Filters specifying assets within the view for which the user statuses are queried.

    Response Format

    On success, the HTTP status code in the response header is 200 OK and the response body is as below.

    Key Type Description
    data Array of User Status objects. The status of the user for each queried filter, in the same order as the filters parameter.

    On error, the header status code is an error code and the response body contains a list of Error Response objects.

    Example

    Request

    curl "https://api.sanalabs.com/v1/user-filter-status" \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: $API_KEY" \
      -X "POST" \
      -d '{
      "user_id": "123",
      "view_id": "ABC",
      "filters": [
        {
          "asset_types": ["theory", "exercise"],
          "view_paths": ["/math/algebra", "/math/calculus"],
          "tags": [
            {
              "name": "exam_year",
              "value": "2017"
            },
            {
              "name": "exam_year",
              "value": "2018"
            }
          ]
        },
        {
          "asset_types": ["theory"],
          "view_paths": ["/math/algebra"]
        }
      ]
    }'
    

    Response

    '{"data": [{"skill_level": 0, "progress": 0}]}'
    

    Getting User Status by View Paths

    Get a user's status by view and view paths.

    Endpoint

    GET /v1/user-status

    Query String Parameters

    Key Mandatory Type Description
    user_id Yes String ID of the user.
    view_id Yes String ID of the view for which the status is queried.
    view_paths Yes Array of Strings Paths within the view for which the user statuses are queried.

    Response Format

    On success, the HTTP status code in the response header is 200 OK and the response body is as below.

    Key Type Description
    data Array of User-Path Status objects. The status of the user for the respective path within the view queried.

    On error, the header status code is an error code and the response body contains a list of Error Response objects.

    Analytics Endpoints

    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.

    Asset Definition

    Key Mandatory Type Description
    id Yes String An ID that uniquely identifies the asset.
    type Yes String The type of asset, one of exercise or theory. The asset type defines the expected structure of the properties object.
    tags No Array of Tag objects Any free-form tagging of asset. Can be used for retrieval/filtering in API. Reserved tag names: content_type (with value equal to e.g. video, text or mixed).
    description No String Any free-form description of the asset (maximum 5000 characters). For exercises and shorter theory sections it is recommended to put the whole question or theory text into the asset description. This information can be used for content analysis.
    content_url No String If it is possible to access the actual content by a URL, it is recommended to provide this information.
    attributes No Object An object with fields containing asset metadata (allowed types are String and Number).
    Reserved attributes fields

    Fields in the attributes object that have a special meaning.

    Key Mandatory Type Description
    variability No Integer The number of unique ways the exercise can be generated, in case of variable exercises. Defaults to 1 meaning the the exercise is always displayed the same way. If the exercise is "generated" in such a way that it is not displayed the exact same way to the user (e.g. by using a template with variable fields), variablity should be greater than 1. The value should be capped at 1000 (in case of larger, or infinite, number of unique instances).

    View Item

    Key Mandatory Type Description
    asset_id Yes String ID of the asset.
    view_path Yes String Defines the location of the asset in the view's content hierarchy using the same standard as for location of files in a file system: /path/to/location, i.e. / is used as separator between parent "directories".
    attributes No View Item Attributes Object Additional attributes describing the asset's role within the view.

    View Item Attributes

    Key Mandatory Type Description
    partner_difficulty No Number If there is metadata expressing the difficulty of exercises, this can be provided in the View Item. It can be utilized by the recommendation algorithm in cold-start scenarios when there is little or no historical interaction data available. The partner_difficulty should be a number between 0 and 1, scaled so that 0 corresponds to the lowest difficulty level and 1 to the highest.

    User Event

    Key Mandatory Type Description
    user Yes User Object The relevant user for the event.
    type Yes String The event type, one of response_submit and theory_viewed.
    attributes Yes User Event Attributes Object The attributes of the event. The expected fields of attributes are tied to the specific event type.
    timestamp Yes String ISO 8601 timestamp of when the exercise was completed.
    is_offline_event No Boolean Specifies whether the event ocurred offline and is being sent to the API at a later point in time. Defaults to false.

    User

    Key Mandatory Type Description
    id Yes String An ID that uniquely identifies the user.
    type Yes String The type of user. Either learner or tester.
    test_cell No String The test cell the user belongs to. Used within analytics and reporting to split users.

    Response-Submit Event Attributes

    Expected structure of User Event attributes when type is response_submit.

    Key Mandatory Type Description
    view_id Yes String The ID of the relevant View for the event.
    asset_id Yes String The ID of the asset.
    result Yes String Denotes if the exercise was successfully completed. One of correct, incorrect, partially_correct or skipped.
    score No Float The score of the given response (if exercises support partial scoring). The score should be normalized to a value between 0 and 1, based on the minimum and maximum score of the exercise.
    time_spent_ms No Integer The time spent on solving the exercise in milliseconds.
    tags No Array of Tag objects Used to provide analytics. Reserved tag names: school, course, grade, class.

    Theory-Viewed Event Attributes

    Expected structure of User Event attributes when type is theory_viewed.

    Key Mandatory Type Description
    view_id Yes String The ID of the relevant View for the event.
    asset_id Yes String The ID of the asset.
    time_spent_ms No Integer The time spent viewing the theory content.
    fraction_completed No Float The fraction of the theory content the user consumed. The value must be in between 0 and 1. For example, if a user has viewed 3 minutes of a 10 minute theory video fraction_completed would be 0.3. If the user views another minute of the video then the next event would have a fraction_completed of 0.4.
    tags No Array of Tag objects Used to provide analytics. Reserved tag names: school, course, grade, class.

    Asset Filter

    Key Mandatory Type Description
    asset_types Yes Array of Strings Only assets with at least one of specified types will be returned.
    view_paths Yes Array of Strings The location of the asset in the view hierarchy (as specified by view_path parameter of Asset Definition). The returned assets will be from one of the paths specified. It is possible to specify the path to any level in the hierarchy. If, for example there are three topics under a specific subject "/subject_1/" 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 Tag objects Only assets with at least one of specified tags will be returned.

    Mode

    The mode parameter expresses the purpose of the session. The Sana Learn API supports two modes: learn and review.

    The learn mode guides the learner through the content specified by the filter object with an adaptive rate of progress and also seamlessly integrates previously covered concepts when deemed necessary.

    The review mode recommends assets by focusing on learner knowledge gaps within previously covered concepts with the aim of maximizing content recall. This means that the learner will be provided with more questions on the concepts where the skill level is low. In the case when the learner has not covered sufficient content within the specified filter, the review mode prioritizes questions with high discriminitve power.

    Key Mandatory Type Description
    type Yes String The mode of the Sana Learn session. Either review or learn.
    attributes Yes Object Any attributes further parameterizing the practice mode.

    Asset Reference

    Key Type Description
    asset_id String The ID of the asset referenced.
    asset_type String The type of the asset referenced.

    User-Path Status

    Key Type Description
    user_id String The ID of the user for which the status is valid.
    view_path String The path within the view for which the status is valid.
    status User Status object The status of the user for the given view and view_path.

    User Status

    Key Type Description
    skill_level Number The skill level of the user, a value between 0 and 1.
    progress Number The progress of the user, a value between 0 and 1.

    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.

    Glossary

    Concept Description
    Asset An asset is the smallest unit a user interacts with. An asset can be an “exercise” or a section of “theory”.
    AssetBank The collection of all the assets of a partner constitutes the AssetBank of the partner.
    View A view is a collection of assets from the Asset Bank. It defines the context in which a user interacts with content. Any real-time modelling happens within a view.

    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 the 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 the relevant HTTP status code and an Error Response object in case of an error. See the Error Status Codes section for the HTTP Status Codes the 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.
    402 Payment Required Your API Key expired.
    404 Not Found The specified resource could not be found.
    405 Method Not Allowed You tried to access a resource with an invalid method.
    429 Too many requests You have exceeded your rate limit.
    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.