AI

Permissions based plugin end-points for AI Engines to integrate with MOTAR.

Authentication

Since the APIs are designed to be used by an AI agent rather than a specific user, you must use your plugin's client ID and client secret for authentication, rather than a standard MOTAR auth token generated by the SSO.

See Plugins page for more information.

Steps for generating a basic auth token:

1. Concatenate your app's client ID and client secret with a ":" character between them: <client_id>:<client_secret>

2. Base 64 encode the result.

3. Attach the resulting string as a header to your API request: Authorization: Basic <base64_encoded_string>

Each set of AI Plugin APIs are permission controlled by MOTAR Admin. To begin, you need to create your AI plugin and ask a MOTAR Admin to enable the correct permissions for it.

User Record

This API allows your AI Engine to access the user learning record, also known as the Airman Learning Record (ALR) or Airman Guardian Learning Record (AGLR)

Returns student record data for the supplied functional orgs, or all the orgs your plugin has access to.

GET https://api.motar.io/plugin/v2/ai/record-data

Query Parameters

Name	Type	Description
orgIds	String	Comma-separated list of functional orgs, e.g. orgIds=abc,def,ghi. Must be from the list your plugin has access to. If not provided, returns all orgs your plugin has access to.

Headers

Name	Type	Description
Authorization*	String	Basic auth header generated from your plugin's client ID and client secret.

200: OK

[{
    userId: String,
    dutyTitle: String,
    afsc: String,
    education: String
}]

Badge Data API Methods

This API set allows you to assert badges for a user's record or return a set of badges held by a user.

Asserts a badge for a user.

POST https://api.motar.io/plugin/v2/ai/badge/assertion

Headers

Name	Type	Description
Authorization*	String	Basic auth header generated from your plugin's client ID and client secret

Request Body

Name	Type	Description
userId*
badgeId*	String
name*	String
type*	String
image*	String
issuedOn*	ISO Date String
issuerName*	String
lessonId	String	required IF badge is from MOTAR
classId	String	required IF badge is from MOTAR
versionId	String	required IF badge is from MOTAR

200: OK

{
    userId: String,
    badgeId: String
    name: String,
    type: String,
    image: String,
    issuedOn: ISO Date String,
    issuerName: String,
    lessonId: String, only IF badge is from MOTAR,
    classId: String, only IF badge is from MOTAR,
    versionId: String, only IF badge is from MOTAR
}

Returns badge assertions for a user.

GET https://api.motar.io/plugin/v2/ai/badge/assertion

Query Parameters

Name	Type	Description
userId	String	User ID of badge assertion recipient from My Record Data API.
userIds	String	Comma-separated list of user IDs.

Headers

Name	Type	Description
Authorization*	String	Basic auth header generated from your plugin's client ID and client secret.

200: OK

[{
    userId: String,
    badgeId: String
    name: String,
    type: String,
    image: String,
    issuedOn: ISO Date String,
    issuerName: String,
    lessonId: String, only IF badge is from MOTAR,
    classId: String, only IF badge is from MOTAR,
    versionId: String, only IF badge is from MOTAR
}]

Creates a badge.

POST /plugin/v2/ai/badge

Headers

Name	Type	Description
Authorization*	String	Basic auth header generated from your plugin's client ID and client secret.

Request Body

Name	Type	Description
name*	String
type*	String
image*	String
description	String
alignments	String
tags	String
proficiency*	Number

200: OK

 [{
 badgeId: String
 name: String,
 type: String,
 image: String,
 proficiency: Number,
 description: String, optional,
 criteria: {
    module: [],
    objective: []
  },
  alignments: String, optional,
 tags: String, optional
}]

Returns course badges from all courses selected functional org(s) member(s) are enrolled in.

GET https://api.motar.io/plugin/v2/ai/badge/course

Query Parameters

Name	Type	Description
orgIds	String	Comma separated list of functional orgs, e.g. orgIds=abc,def,ghi. Must be from the list your plugin has access to.

Headers

Name	Type	Description
Authorization	String	Basic auth header generated from your plugin's client ID and client secret.

200: OK

[{
    badgeId: String
    name: String,
    type: String,
    image: String,
    description: String, optional,
    criteria: {
        module: [],
        objective: [{
            objectiveId: String,
            objectiveName: String,
            objectiveDescription: String
        }]
    },
    alignments: String, optional,
    tags: String, optional,
    courseId: String, optional,
    courseVersion: String, optional
}]

Returns objective badges from all courses selected functional org(s) member(s) are enrolled in.

GET https://api.motar.io/plugin/v2/ai/badge/objective

Query Parameters

Name	Type	Description
orgIds	String	Comma separated list of functional orgs, e.g. orgIds=abc,def,ghi. Must be from the list your plugin has access to.

Headers

Name	Type	Description
Authorization*	String	Basic auth header generated from your plugin's client ID and client secret.

200: OK

[{
    badgeId: String
    name: String,
    type: String,
    image: String,
    description: String, optional,
    criteria: {
        module: [{
            moduleId: String,
            moduleName: String,
            moduleDescription: String
        }],
        objective: []
    },
    alignments: String, optional,
    tags: String, optional,
    courseId: String, optional,
    courseVersion: String, optional
}]

Hobbies and Other Skills API

This API allows the AI to read a user's hobbies and skills from their record.

Returns a user's hobbies and other skills.

GET https://api.motar.io/plugin/v2/ai/other-skills

Query Parameters

Name	Type	Description
userId	String	User ID from My Record Data API.
userIds	String	Comma-separated list of user IDs.

Headers

Name	Type	Description
Authorization*	String	Basic auth header generated from your plugin's client ID and client secret.

200: OK

{[{
    selfClaimedExpertise: String,
    level: String
}]

Additional Info API

POST https://api.motar.io/plugin/v2/ai/additional-info

Headers

Name	Type	Description
Authorization	String	Basic auth header generated from your plugin's client ID and client secret.

Request Body

Name	Type	Description
Body	String	{ userId: String, additionalInfo: [{ title: String, description: String }] }

200: OK

[{
    title: String,
    description: String
}] 

Mission Planner Search API

For your plugin to support Mission Planner Search, you must implement a capabilities search request endpoint, and a candidate search request endpoint. When a user uses the MOTAR Mission Planner and your plugin has been configured properly, they will have the option to select your plugin for their search.

All requests to your API from MOTAR will include a basic auth header, as detailed in "Authentication" above. You should decode this header and verify the client ID and client secret match before returning a response.

Capabilities Search Request

Be sure to configure your AI plugin in MOTAR Studio with your Capabilities Search endpoint. If you have not set your endpoint, your plugin will not appear as an option for Mission Planner search.

Search is limited to specific data sets. Contact MOTAR Help Desk to verify your AI's data access permissions.

Request body (from MOTAR):

Request Body

{
    "positions": [{
        "title": String,
        "knowledgeLevel": KnowledgeLevel,
        "afsc": String,
        "count": Number,
        "exactMatch": Boolean
    }]
}

Expected response (from plugin API):

Response Body

{
    "positions": [{
        "title": String,
        "competencies": [{
            "competencyId": String,
            "title": "String,
            "preferredCompetencyLevel": CompetencyLevel
        }]
    }],
    "additionalCompetencies": [{
        "competencyId": String,
        "title": String
    }]
}

Candidate Search Request

Be sure to configure your AI plugin in MOTAR Studio with your Candidate Search endpoint. If you have not set your endpoint, your plugin will not appear as an option for Mission Planner search.

Request body (from MOTAR):

Request Body

{
    "positions": [{
        "title": String,
        "count": Number,
        "competencies": [{
            "competencyId": String,
            "title": String,
            "minimumRequirement": CompetencyLeveL,
            "preferredRequirement": CompetencyLevel
        }]
    }]
}

Expected response (from plugin API):

Response Body

{
    "positions": [{
        "title": String,
        "readyCandidates": [{
            "candidateId": String,
            "trainingGap": [{
                "competencyId": String,
                "recommendedAction": [{
                    "type": ActionType,
                    "objectIds": [String]
                }]
            }]
        }],
        "recommendedCandidates": [{
            "candidateId": String,
            "trainingGap": [{
                "competencyId": String,
                "recommendedAction": [{
                    "type": ActionType,
                    "objectIds": [String]
                }]
            }]
        }]
    }]
}

Data Types

KnowledgeLevel

[
    "apprentice",
    "journeyman",
    "craftsman",
    "superintendent"
]

ActionType

[
    "course",
    "objective"
]

CompetencyLevel

[
    "basic",
    "intermediate",
    "advanced",
    "expert"
]