Introduction to the AI Assistant API
This page introduces the API for the AI AssistantOpens in a new tab in InterSystems Supply Chain Orchestrator™.
This API is contained in a separately installed package (rather than being part of the Supply Chain Framework). See Setting Up the AI Assistant.
Posting and Updating Credentials
When setting up the AI Assistant, you must post credentials for use in accessing Azure OpenAI, for use by the AI Assistant API.
Note that currently only AzureAI is supported, and the models used must be gpt-4.1 (for the LLM model) and text-embedding-3-large (for the embedding model).
To post credentials, use the following API call:
POST {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/credentials
With a request body like the following example:
{
"vendor": "azure",
"llmDeployment": {
"name": "gpt-4.1-deployment",
"apiKey": "<your_llm_api_key>",
"apiEndpoint": "<your_llm_endpoint>",
"apiVersion": "2024-12-01-preview"
},
"embeddingDeployment": {
"name": "text-embedding-3-large-deployment",
"apiKey": "<your_embedding_api_key>",
"apiEndpoint": "<your_embedding_endpoint>",
"apiVersion": "2024-12-01-preview"
},
"enabled": true
}
Required privilege: SC_AI_Assistant_Credentials_API:Write
To update credentials, use the following API call:
PUT {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/credentials
Use the same form of request body as with the POST call.
Required privilege: SC_AI_Assistant_Credentials_API:Write
Creating Memories
When setting up the AI Assistant, you can define memories for it to use when generating responses. You can define them system-wide and for individual users. The AI Assistant API uses all applicable memories.
Creating a User-Specific Memory
There are two ways to create a user-specific memory. First, the following API call creates a memory specific to the username under which the API call is made:
POST {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/usermemories
With a request body like the following example:
{
"document" : "This is a sample user memory",
"metadata" : {"key" : "value"}
}
The optional metadata object contains any additional information associated with this memory.
Required privilege: SC_AI_Assistant_Personal_Memory_API:Write
Second, an administrative user can use the following API call to create a memory for a specific user:
POST {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/memories
With a request body like the following example:
{
"document" : "This is a sample user memory",
"user" : "usernamehere",
"isSystem" : false,
"metadata" : {"key" : "value"}
}
Required privilege: SC_AI_Assistant_Admin_Memory_API:Write
In either case, the response object contains an id property which is the unique identifier of the memory.
Creating System-Wide Memories
To create a new system-wide memory, use the following API call:
POST {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/memories
With a request body like the following example:
{
"document" : "This is a sample system-wide memory",
"user" : "",
"isSystem" : true,
"metadata" : {"key" : "value"}
}
Required privilege: SC_AI_Assistant_Admin_Memory_API:Write
The response object contains an id property which is the unique identifier of the memory.
Retrieving Memories
To retrieve a user memory, given its unique ID:
GET {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/usermemories/:id
Required privilege: SC_AI_Assistant_Personal_Memory_API:Read
To get all personal memories of the request user as well as all system memories:
GET {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/usermemories
Required privilege: SC_AI_Assistant_Personal_Memory_API:Read
To retrieve a system memory, given its unique ID:
GET {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/memories/:id
Required privilege: SC_AI_Assistant_Admin_Memory_API:Read
Deleting Memories
To delete a user memory, given its unique ID:
DELETE {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/usermemories/:id
Required privilege: SC_AI_Assistant_Personal_Memory_API:Write
To delete a system memory, given its unique ID:
DELETE {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/memories/:id
Required privilege: SC_AI_Assistant_Admin_Memory_API:Write
Creating Sessions
To interact with the AI Assistant, you typically use sessions, which retain information between chat messages.
To create a session, use the following API call:
POST {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/sessions
Required privilege: SC_AI_Assistant_Sessions_API:Write
The response object contains an id property which is the unique identifier of the session.
Posting Messages to a Session
To post a message to a session, given its unique ID, use the following API call:
POST {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/sessions/:id/messages
With a request body like the following example:
[
{
"content": "Why was option C recommended?",
"type": "USER",
"metadata": ""
},
{
"content": "Option C was recommended because it had the lowest cost impact.",
"type": "ASSISTANT",
"metadata": ""
}
]
Required privilege: SC_AI_Assistant_Sessions_API:Write
Retrieving Messages from a Session
To retrieve the messages for a session, given its unique ID, use the following API call:
GET {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/sessions/:id
This returns an array of the message IDs.
Required privilege: SC_AI_Assistant_Sessions_API:Read
Deleting a Session
To delete a session, given its unique ID, use the following API call:
DELETE {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/sessions/:id
Required privilege: SC_AI_Assistant_Sessions_API:Write
Initiating a Chat Interaction
Within a session, to interact with the AI Assistant, you post chat messages, using the following API call:
POST {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scai/v1/chat
With a request body like the following example:
{
"question": "What is customer's location? Why was option A recommended?",
"sessionId": "sessionidhere",
"additionalContext": "This is ISSUE-1008."
}
Where sessionID is the unique ID of the session that you are using.
Required privilege: SC_AI_Assistant:Use
