mentorAI - Using the API

1 Overview
2 Interacting with the API
- 2.1 VS Code
- 2.2 Postman
3 API Methods
4 Getting an API Key
5 API Documentation
6 Examples
- 6.1 Get Mentors
- 6.2 Get Mentor Datasets
- 6.3 Upload a document to a Mentor (Upload a dataset)
- 6.4 Create chat session with Mentor
- 6.5 Send a chat message to a mentor
  - 6.5.1 Getting a token and your FID

This document is still under construction, thank you for your patience.

Overview

This document is designed to provide starting point with interacting with mentorAI via it’s API and programmatically.

Interacting with the API

There are many ways to interact with an API and below are two examples, and how to set their environments up.

VS Code

Visual Studios Code is the “light” version of Visual Studios. It provides a powerful environment to program from and is the recommended IDE to use.

Setting up VS Code

Postman

Postman is a light-weight application that can be used to interact with an API through singular calls and is often helpful when testing.

Setting up Postman (WIP)

API Methods

In short, an API method is the basic idea of what you want an API to do. If all you wish to do is get information in regards to something you would use GET as the method. If you wish to create something new or request the API to make something, you would likely use a POST method.

For additional information on methods that are typically part of an API, see the page below.

API Methods

Getting an API Key

Despite an API key appearing as an option on a mentor, it is actually tied to your account, not a specific mentor. The API key has the same permissions your user account does.

At this time, request access to the API by emailing aihelp@syr.edu with your username (netid).

Afterwards, log back into mentorAI and navigate to a mentor you created or have been granted access to and select the API action in the drop down.

Screenshot of a mentor's drop down menu, including the API selection near the bottom.

Press the “Create New” button
1. Provide a name that is concise but descriptive of the key’s use-case
2. Pick an expiration date. Common intervals are 1 month, 3 months, 1 year.
3. Press “Submit”
Copy the string that is now provided to you. This string will NOT be shown to you again. This string is your API key/token. Do NOT share it with anyone. Store the string somewhere safe, like a password manager.

When programming, do NOT place your API key directly in your code. Instead, place it somewhere else and pull it into the code. Such as storing it in a .txt file and reading the file in the code.

If you use GitHub, be sure to not accidently upload your key into your repository!

API Documentation

IBL (the creators of mentorAI) have a documentation resource that you may find useful. See the links below:

ibl-data-manager (Public)

Examples

Currently the examples are in the PowerShell language.

In the future, our examples may be moved to GitHub or another method, and links will be provided. This will be to offer more programming language support for each example.

Get Mentors

$ErrorActionPreference = 'Stop'

#=== GET API KEY FROM FILE ===
[System.String]$apiKey = (Get-Content -Path "C:\path\to\your\apikey.txt" -Raw).Trim()

#=== BUILD REQUEST HEADERS ===
$headers = @{
    "Content-Type"  = "application/json"
    "Authorization" = "Api-Token $apiKey"
}

[System.String]$orgId = "syracuse"
[System.String]$userId = "{INSERT YOUR NETID HERE}" #can also use your FID

#=== API URL TO GET ALL MENTORS FOR A USER ===
# Below are multiple methods and examples of API endpoints to accomplish this goal

# Get the list of mentors you have access to.
#$urlPathway = "https://base.manager.ai.syr.edu/api/ai-mentor/orgs/$orgid/users/$userid/"

# Get the list of mentors you have access to, but pre-sort the response by name of the mentor
#$urlPathway = "https://base.manager.ai.syr.edu/api/ai-mentor/orgs/$orgid/users/$userid/?filter_by=name"

# Get the list of mentors created by a user (may require a user's FID as opposed to their netid)
#$urlPathway = "https://base.manager.ai.syr.edu/api/ai-search/mentors/?platform_key=$orgId&created_by=$userid"

# Similar to the first example, Get a list of mentors you have access to
$urlPathway = "https://base.manager.ai.syr.edu/api/ai-search/mentors/?platform_key=$orgId"

#=== CALL THE API ===
try {
    $response = Invoke-RestMethod -Uri $urlPathway -Method Get -Headers $headers
    $response.results | Format-List
}
catch {
    Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__
    Write-Host "StatusDescription:" $_.Exception.Response.StatusDescription
    Write-Host $_.Exception
    exit
}

Get Mentor Datasets

$ErrorActionPreference = 'Stop'

#=== GET API KEY FROM FILE ===
[System.String]$apiKey = (Get-Content -Path "C:\path\to\your\apikey.txt" -Raw).Trim()

#=== BUILD REQUEST HEADERS ===
$headers = @{
    "Content-Type"  = "application/json"
    "Authorization" = "Api-Token $apiKey"
}

[System.String]$orgId = "syracuse"
[System.String]$userId = "{INSERT YOUR NETID HERE}" #can also use your FID
[System.String]$pathway = "{INSERT MENTOR STRING HERE}" #You can find this at the end of the URL string when viewing a mentor in a browser. Will be formatted like: 12345678-1234-1234-1234-123456789012

#=== API URL TO GET ALL DATASETS FOR A PATHWAY ===
$urlPathway = "https://base.manager.ai.syr.edu/api/ai-index/orgs/$orgid/users/$userid/documents/pathways/$pathway/"

#=== CALL THE API ===
try {
    $response = Invoke-RestMethod -Uri $urlPathway -Method Get -Headers $headers
    $response.results | Format-List
}
catch {
    Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__
    Write-Host "StatusDescription:" $_.Exception.Response.StatusDescription
    Write-Host $_.Exception
    exit
}

Upload a document to a Mentor (Upload a dataset)

$ErrorActionPreference = 'Stop'

#=== GET API KEY FROM FILE ===
[System.String]$apiKey = (Get-Content -Path "C:\path\to\your\apikey.txt" -Raw).Trim()

#=== BUILD REQUEST HEADERS ===
$headers = @{
    "Content-Type"  = "application/json"
    "Authorization" = "Api-Token $apiKey"
}

[System.String]$orgId = "syracuse"
[System.String]$userId = "{INSERT YOUR NETID HERE}" #can also use your FID
[System.String]$url = "https://base.manager.ai.syr.edu/api/ai-index/orgs/$orgId/users/$userId/documents/train/"

[System.String]$pathway = "{INSERT MENTOR STRING HERE}" #You can find this at the end of the URL string when viewing a mentor in a browser. Will be formatted like: 12345678-1234-1234-1234-123456789012
[System.String]$ingestURL = "{ENTER URL OF PUBLIC WEBSITE YOU WISH TO UPLOAD HERE}"

$body = @{
    "pathway" = $pathway
    "url" = $ingestURL
    "type" = "url"
    "access" = "private"
} | ConvertTo-Json

#=== CALL THE API ===
try
{
    $response = Invoke-RestMethod -Uri $url -Method Post -Headers $headers -Body $body
}
catch 
{
    Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__
    Write-Host "StatusDescription:" $_.Exception.Response.StatusDescription
    Write-Host $_.Exception
    exit
}

Write-Host $response.message
Write-Host "Task ID:" + $response.task_id
Write-Host "Doc ID: " + $response.document_id

Create chat session with Mentor

Use this code below to get a sessionId. Then use the sessionId in the code to send a chat message. You can also get a sessionId from the developer tools in a browser. Steps are explained after the code for sending a message.

$ErrorActionPreference = 'Stop'

#=== GET API KEY FROM FILE ===
[System.String]$apiKey = (Get-Content -Path "C:\path\to\your\apikey.txt" -Raw).Trim()

#=== BUILD REQUEST HEADERS ===
$headers = @{
    "Content-Type"  = "application/json"
    "Authorization" = "Api-Token $apiKey"
}

[System.String]$orgId = "syracuse"
[System.String]$userId = "{INSERT YOUR NETID HERE}" #can also use your FID
[System.String]$mentorName = "{INSERT NAME OF THE MENTOR HERE}"
[System.String]$url = "https://base.manager.ai.syr.edu/api/ai-mentor/orgs/$orgId/users/$userId/sessions/"

$body = @{
  "mentor" = $mentorName
} | ConvertTo-Json

#=== CALL THE API ===
try
{
    $response = Invoke-RestMethod -Uri $url -Method Post -Headers $headers -Body $body
    $sessionId = $response[0].session_id
}
catch 
{
    Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__
    Write-Host "StatusDescription:" $_.Exception.Response.StatusDescription
    Write-Host $_.Exception
    exit
}

Send a chat message to a mentor

$ErrorActionPreference = 'Stop'

[System.String]$sessionId = "12345678-1234-1234-1234-1234567890"  # From the previous code
[System.String]$orgId = "syracuse"
[System.String]$userId = "{INSERT YOUR FID HERE}" # See information below this code snippet on how to obtain this
[System.String]$pathway = "{INSERT MENTOR STRING HERE}" #You can find this at the end of the URL string when viewing a mentor in a browser. Will be formatted like: 12345678-1234-1234-1234-123456789012
[System.String]$prompt = "Hello, what's your name?"

# Step 2: Create the JSON payload
$payload = @{
    flow = @{
        name = $pathway
        tenant = $orgId
        username = $userId
        pathway = $pathway
    }
    session_id = $sessionId
    token = "{INSERT TOKEN STRING HERE}" # See information below this code snippet on how to obtain this
    prompt = $prompt
} | ConvertTo-Json

# Step 3: Create and connect a webSocket
[System.Net.WebSockets.ClientWebSocket]$ws = New-Object System.Net.WebSockets.ClientWebSocket
$uri = [System.Uri]::new("wss://asgi.data.ai.syr.edu/ws/langflow/")
[System.Threading.CancellationTokenSource]$cts = New-Object System.Threading.CancellationTokenSource

try {
    # Connect to WebSocket
    #Write-Host "Connecting to WebSocket..." -ForegroundColor Yellow
    $connectTask = $ws.ConnectAsync($uri, $cts.Token)
    $connectTask.Wait()
    #Write-Host "Connected!" -ForegroundColor Green
    
    # Step 4: Send the message
    #Write-Host "Sending message..." -ForegroundColor Yellow
    $bytes = [System.Text.Encoding]::UTF8.GetBytes($payload)
    $buffer = New-Object System.ArraySegment[byte] -ArgumentList @(,$bytes)
    $sendTask = $ws.SendAsync($buffer, [System.Net.WebSockets.WebSocketMessageType]::Text, $true, $cts.Token)
    $sendTask.Wait()
    #Write-Host "Message sent!" -ForegroundColor Green
    
    # Step 5: Receive responses
    #Write-Host "`nReceiving responses:" -ForegroundColor Yellow
    $fullResponse = ""
    
    $receiveBuffer = New-Object byte[] 4096
    $segment = New-Object System.ArraySegment[byte] -ArgumentList @(,$receiveBuffer)
    
    do {
        $receiveTask = $ws.ReceiveAsync($segment, $cts.Token)
        $receiveTask.Wait()
        $result = $receiveTask.Result
        
        $message = [System.Text.Encoding]::UTF8.GetString($receiveBuffer, 0, $result.Count)
        $jsonResponse = $message | ConvertFrom-Json
        
        # Display the response
        #Write-Host $message
        
        # If it's a data chunk, accumulate it
        if ($jsonResponse.type -eq $null -and $jsonResponse.data) {
            $fullResponse += $jsonResponse.data
        }
        
        # Check if we've reached the end of responses
        if ($jsonResponse.eos -eq $true) {
            break
        }
        
    } while ($ws.State -eq [System.Net.WebSockets.WebSocketState]::Open)
    
    # Display the completed response
    #Write-Host "`n`nComplete Response:" -ForegroundColor Cyan
    Write-Host $prompt
    Write-Host $fullResponse
    
} catch {
    Write-Host "Error: $_" -ForegroundColor Red
} finally {
    # Step 6: Clean up
    if ($ws.State -eq [System.Net.WebSockets.WebSocketState]::Open) {
        $ws.CloseAsync([System.Net.WebSockets.WebSocketCloseStatus]::NormalClosure, "Done", $cts.Token).Wait()
    }
    $ws.Dispose()
    $cts.Dispose()
    #Write-Host "`nWebSocket closed." -ForegroundColor Yellow
}

Getting a token and your FID

We are working on a way to programmatically get a token, however, at this time, you can get one from your web browser. Follow the steps outlined below:

Navigate to mentorAI
Go to a mentor you are the creator or have permission to
Open the developer tools for the web browser you are using
1. Such as F12 or Ctrl + Shift + I on a Windows computer
2. Fn + F12 or Command + Option + I on a Mac computer
Send a chat message to the mentor, you can ask it anything.
Go to the Network tab > filter on Socket (might be called WS, WebSocket, etc) > select langflow/
1. Make sure you are on the Messages tab to the right of langflow/
Look at a message and grab the FID (username) and the Token that was used.