Integrating the Learnosity Feedback Aide API into your system is a simple process.

Prerequisites

In addition to some developer skills, you'll need the following:

• An OAuth key and secret to generate a security token. See Feedback Aide Security Tokens.
• A rubric. You can grab a sample from here: Feedback Aide Rubrics.

Python Short Example

Once you have a security token, the following snippet is the most basic example of how to use the /api/essays/evaluate endpoint using Python's http.client module.

import http.client
import json
conn = http.client.HTTPSConnection("feedbackaide.learnosity.com")
conn.request("POST", "/api/essays/evaluate",
    body=json.dumps({
        "session_uuid": "<your-session-uuid>",
        "stimulus": "<your-stimulus-text>",
        "response": "<your-response-text>",
        "rubric": {"<your-rubric-object>": "see documentation"},
        "model": "standard-essay",
    }),
    headers={
        "Authorization": "Bearer <retrieved-security-token>",
        "Content-Type": "application/json",
    }
)
response = conn.getresponse()
if response.status == 200:
    print(json.loads(response.read()))
else:
    print(f"Unexpected Error: {response.status} {response.read().decode()}")
conn.close()

Making server-side requests to other Feedback Aide API endpoints is done in a similar way. The only difference is the endpoint URL and the request body.

The headers should always include the security token. It's important to note that the security token has to be created with the required scopes for the endpoint.

In the case of the /api/essays/evaluate endpoint, the scope should look like api:feedbackaide feedback_session_uuid::RW state:grade. See Feedback Aide Security Tokens for an explanation of the scopes.

For more detailed information on the API endpoints and parameters, please refer to the Feedback Aide Server-Side Documentation.

Python Full Example

The following is a full example using Python's http.client module to make a request to the /api/essays/evaluate endpoint.

import json
from base64 import b64encode
from http.client import HTTPSConnection
from urllib.parse import urlencode
from uuid import uuid4

# Replace these placeholders with your OAuth keys
YOUR_OAUTH_KEY = "<your-oauth-key>"
YOUR_OAUTH_SECRET = "<your-oauth-secret>"

# Generate a unique session UUID
SESSION_UUID = str(uuid4())

# Step 1: Obtain an access token
def get_access_token(client_id, client_secret, session_uuid):
    conn = HTTPSConnection("feedbackaide.learnosity.com")
    try:
        # Prepare Basic Authentication header
        basic_auth = b64encode(f"{client_id}:{client_secret}".encode()).decode()
        headers = {
            "Content-Type": "application/x-www-form-urlencoded",
            "Authorization": f"Basic {basic_auth}",
        }
        # Prepare request body with scope
        scope = f"api:feedbackaide feedback_session_uuid:{session_uuid}:RW state:grade"
        data = urlencode({"grant_type": "client_credentials", "scope": scope})
        conn.request("POST", "/api/token", body=data, headers=headers)
        response = conn.getresponse()
        if response.status == 200:
            token_data = json.loads(response.read())
            return token_data["access_token"]
        else:
            raise Exception(f"Failed to get access token: {response.status} {response.read().decode()}")
    finally:
        conn.close()

# Step 2: Submit the essay evaluation request
def evaluate_essay(access_token, session_uuid):
    conn = HTTPSConnection("feedbackaide.learnosity.com")
    try:
        payload = {
            "session_uuid": session_uuid,
            "stimulus": "Describe a time when you worked on a team to achieve a goal. What role did you play, and what did you learn from the experience?",
            "response": "Last semester, our science class was tasked with creating a working model of a sustainable city. I was assigned the role of team leader. To ensure success, I divided tasks based on everyone's strengths—design, research, and presentation. At first, disagreements arose, but I mediated and encouraged collaboration. In the end, our city model was not only functional but won an award for creativity. I learned that communication and compromise are key to effective teamwork.",
            "rubric": {
                "title": "Teamwork Reflection Rubric",
                "type": "analytic",
                "criteria": [
                    {
                        "title": "Relevance",
                        "type": "discrete",
                        "levels": [
                            {"score": 3, "description": "Fully addresses the prompt with specific, detailed examples."},
                            {"score": 2,"description": "Mostly addresses the prompt with some relevant examples."},
                            {"score": 1,"description": "Minimally addresses the prompt with vague examples."},
                        ],
                    },
                    {
                        "title": "Clarity",
                        "type": "discrete",
                        "levels": [
                            {"score": 3,"description": "Clear and well-structured with logical flow."},
                            {"score": 2,"description": "Mostly clear, with minor lapses in structure."},
                            {"score": 1,"description": "Lacks clarity, with weak structure or flow."},
                        ],
                    },
                    {
                        "title": "Reflection",
                        "type": "discrete",
                        "levels": [
                            {"score": 3,"description": "Deep insights into teamwork and personal growth."},
                            {"score": 2,"description": "Some insights into teamwork and personal growth."},
                            {"score": 1,"description": "Minimal or no insights into teamwork and personal growth."},
                        ],
                    },
                ],
            },
            "model": "standard-essay",
        }
        headers = {
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
        }
        conn.request("POST", "/api/essays/evaluate", body=json.dumps(payload), headers=headers)
        response = conn.getresponse()
        if response.status == 200:
            results = json.loads(response.read())
            return results
        else:
            raise Exception(f"Unexpected Error: {response.status} {response.read().decode()}")
    finally:
        conn.close()

# Main script
if __name__ == "__main__":
    try:
        print(f"Generated session UUID: {SESSION_UUID}")
        token = get_access_token(YOUR_OAUTH_KEY, YOUR_OAUTH_SECRET, SESSION_UUID)
        results = evaluate_essay(token, SESSION_UUID)
        print("Evaluation Results:")
        for result in results:
            print(f"- {result}")
    except Exception as e:
        print(e)

To run it, copy and save the script to a file evaluate_essay_test.py, replace the placeholders with your OAuth key and secret at the beginning of the script, and run it with:

python evaluate_essay_test.py

Next Steps

There are multiple ways to integrate including this full UI, or a Headless mode, or a backend Restful API - this article gives more detail: Feedback Aide API Integration Options

Developer documentation for the JS API is here: Feedback Aide API JS Developer Documentation

Developer documentation for the Restful API is here: Feedback Aide Server-Side Documentation.