tftsr-devops_investigation/GenAI API User Guide.md

A User Guide to GenAI API

Revision: 3.4

Change History

Date	Version	Author	Changes
08-22-2023	1.0	Dipjyoti Bisharad	Initial Draft
08-24-2023	1.1	Jahnavi Alike	Updated sessionId usage process.
12-12-2023	1.2	Sunil Vurandur	Updated details on different model types
03-28-2024	1.3	Jahnavi Alike	Text rearrangement
04-23-2024	1.4	Dipjyoti Bisharad	Introduced additional args field in response
05-08-2024	2.0	Dipjyoti Bisharad	Updated to v2 of chat API
05-17-2024	2.1	Dipjyoti Bisharad	Added Gemini 1.5 Pro
06-25-2024	2.2	Dipjyoti Bisharad	Added disclaimer on omitting the userId from payload
06-27-2024	2.3	Dipjyoti Bisharad	Added the datastoreId to the request payload. Introduced GPT 4 Omni, Claude Sonnet. Replaced Gemini 1.5 Pro with Gemini 1.5 Flash. Deprecation of legacy /chat.
07-10-2024	2.4	Dipjyoti Bisharad	Added modelConfig in the chat payload. Added application identifier x-msi-genai-client in header. Upload files to a chat session
08-09-2024	2.5	Dipjyoti Bisharad	Added note regarding impersonation with API keys
08-12-2024	2.6	Dipjyoti Bisharad	Added userId usage for the /upload endpoint
09-16-2024	2.7	Dipjyoti Bisharad	Added endpoints for delete message and retrieve session messages
11-15-2024	2.8	Dipjyoti Bisharad	Updated contacts
11-18-2024	2.9	Girish Manivel	Added API error codes
01-09-2025	3.0	Anjali Kamath	Added Init Datastore API details
01-15-2025	3.1	Vibin Jacob	Added default Model config values
01-30-2025	3.2	Vibin Jacob	Added Nova Lite
03-04-2025	3.3	Anjali Kamath	Updated Model details
03-27-2025	3.4	Vibin Jacob	Updated Model details
05-12-2025	3.5	Vibin Jacob	Google Search Agent

People

Name	Role	Email
Manminder Kaur Sardarni	Dev Manager	manminderkaur.sardarni@motorolasolutions.com
Suma Rebbapragada	Product Manager	lakshmisuma.rebbapragada@motorolasolutions.com
Anjali Kamath	Lead Engineer	anjali.kamath@motorolasolutions.com
Sri Chand Jasti	Sr Mgr, IT AIML	srichand.jasti@motorolasolutions.com

Table of Contents

People 3

1. Abstract 5

2. The API Key 5

3. Properties of the API Key 7

4. API Reference 7

4.1. Chat Endpoint 7

4.2. File upload Endpoint 10

4.3. Get Session Messages Endpoint 11

4.4. Delete Message Endpoint 12

4.5. Initialise Datastore Endpoint 13

1. Abstract

This document is a user guide to interact with the API provided by MSI GenAI, which can be used to programmatically send a prompt and receive a response from AI Models. The endpoint can do session management, so the user needs to pass only the current prompt and session ID (more details below), and the past contexts will be automatically retained.

The API is exposed at the following link: https://genai-service.stage.commandcentral.com/app-gateway/api/v2/chat

To interact with the API, an API key is required, which can be obtained from the steps listed below.

Note: In this v2 release, the endpoint has been changed to /api/v2/chat, which will support a long-lived API key. The former endpoint /chat stands deprecated.

2. The API Key

Follow these steps to get an API key for the endpoint.

1. Log in to the MSI GenAI Portal
2. After logging in, click on the name in the top right corner of the screen and click on the Generate API Key.
   
3. Click on the Copy & Close button. This automatically copies the token to the clipboard. This token will be visible only once and is not saved or logged anywhere in the backend
   
4. The token for the legacy /chat endpoint can be obtained by clicking the Auth Token (Legacy) button.

NOTE: API usage cost is limited to $50 per user/month. The user’s keys will be disabled once they cross the limit in a normal scenario.

3. Properties of the API Key

1. Visible only once.
2. Valid for 3 months.
3. The API key CANNOT be used to request content on behalf of other users, however, the owner of the key shall always be logged for audit purposes.
   API keys will ordinarily not be able to request content on behalf of other users. Reach out to any of the contacts listed if a key has to be revoked.
4. Upcoming feature to allow customizing the token validity as well as self-service token revocation.

4. API Reference

   1. Chat Endpoint

• Host: https://genai-service.stage.commandcentral.com/app-gateway

• Endpoint: /api/v2/chat

• HTTP Type: POSTHeaders:
  x-msi-genai-api-key: <INSERT API KEY HERE>
  Content-Type: application/json
  X-msi-genai-client (optional): <some-unique-app-identifier>

• Request Body:
  {
  "userId": "core-id@motorolasolutions.com",
  "model": "VertexGemini",
  "prompt": "Who plays the best piano?",
  "system": "",
  "sessionId": "c2e07ae5-4d6b-48e6-b035-6a8aefb57321",
  "datastoreId": "a1c0e7f2-a01a-4ee4-b5fb-e3362bd1f302",
  "modelConfig": {
  "temperature": 0.5,
  "max_tokens": 800,
  "top_p": 1,
  "frequency_penalty": 0,
  "presence_penalty": 0
  }
  }

The different fields of the request body have the following usage.

• userId (optional): The email address of the user in the CORE ID format.
  Note: In case this field is not provided with the payload, all the usages and subsequent costs will be mapped to the user who created the token.
• model (mandatory): The model to be used for the AI. The following options are available:

• Use model: ChatGPT4o to access GPT4 Omni

• Use model: ChatGPT4o-mini to access GPT4o Omni Mini

• Use model: ChatGPT-o3-mini to access GPT o3 Omni

• Use model: Gemini-2_0-Flash-001 to access Gemini 2.0 Flash

• Use model: Gemini-2_5-Flash to access Gemini 2.5 Flash

• Use model: Claude-Sonnet-3_7 to access Claude-Sonnet 3.7.

• Use model: Openai-gpt-4_1-mini to access OpenAI GPT 4.1 Mini.

• Use model: Openai-o4-mini to access OpenAI o4 Mini.

• Use model: Claude-Sonnet-4 to access Claude Sonnet 4.

• Use model: ChatGPT-o3-pro to access ChatGPT o3 Pro.

• Use model: OpenAI-ChatGPT-4_1 to access OpenAI ChatGPT 4.1.

• Use model: OpenAI-GPT-4_1-Nano to access OpenAI ChatGPT 4.1 Nano.

• Use model: ChatGPT-5 to access OpenAI ChatGPT5

• Use model: VertexGemini to access Gemini 2.0 Flash 001

• Use model: ChatGPT-5_1 to access ChatGPT 5.1

• Use model: ChatGPT-5_1-chat to access ChatGPT 5.1 Chat

• Use model: ChatGPT-5_2-Chat to access ChatGPT 5.2 Chat

• Use model: Gemini-3_Pro-Preview to access Gemini 3.1 Pro

• Use model: Gemini-3_1-flash-lite-preview to access Gemini 3.1 Flash Lite

  File uploads are currently supported for models VertexGemini, ChatGPT4o, and Claude-Sonnet (Claude-Sonnet supports image files only)

• Supported Files
  1.

Model	Supported Files Extensions
Gemini-3_Pro-Preview	Image: JPEG, JPG, PNG or WEBP format.Video: MP4, WEBM, MKV or MOV format.Document: PDF or TXT format.Audio: MP3, MPGA, WAV, WEBM, M4A, OPUS, AAC, FLAC or PCM format.
ChatGPT 4o	Text, image
ChatGPT 4.1 Mini	text and vision
ChatGPT 5.2 Chat
ChatGPT o4 Mini	Text, image
Claude Sonnet 4

2. Check model Access and privacy for model accessibility

• prompt (mandatory): The plain text query.

• sessionId (optional): All the messages linked to a sessionId are treated as part of the same conversation. The sessionId should not be passed for the first message. The AI engine generates a session ID after the first successful prompt, and that value should be used in subsequent API calls.

• system (optional): Optional system message that can be configured for the model. It will only work with the models that support it. Ignored for non-supported models.

• datastoreId (optional): Optional DatastoreId that can be passed to refer to the files of a datastore within your chat session.

• modelConfig (optional): Expert settings to tune the model parameters.
  If model parameters are not mentioned in the request payload, they will set by default as below:

  temperature: 0.7
  max_tokens:(800 Azure OpenAI),(4000 Gemini),(1024 AWS)
  top_p: 1.0
  Top_k: (NA Azure OpenAI), (32 Gemini), (250 AWS)
  frequency_penalty: 0
  presence_penalty:0

• Response Body:
  {
  "status": true,
  "success": true,
  "sessionId": String,
  "sessionTitle": String,
  "msg": Text,
  "valid_response": Boolean,
  "initialPrompt": Boolean,
  "args": JSON
  }

The different fields of the response body have the following usage.

• status: states whether the API call is successful or not

• success: always true (internal reference key).

• sessionId: UUID for a session. One can use the same sessionId to maintain a conversation in the same session

• sessionTitle: Title created for the session

• msg: Actual response from AI models for users prompt

• valid_response: always true (internal reference key).

• initialPrompt: states whether the user is starting a new session or an old one. If the user sends a message for the first time in a new session, then this will be true; else false.

• args: Contains metadata about the response

• Error Response Body:

{
status: false,
msg: String (Error Msg)
}

The curl command for the request looks like this:

curl -X POST -H "x-msi-genai-api-key: <key-value>" -H "Content-Type: application/json" https://genai-service.stage.commandcentral.com/app-gateway/api/v2/chat -d '{"userId": "String", "model": "String", "prompt": "Text", "sessionId": "String", "datastoreId": "String"}'

Here,

• -X refers to the HTTP Method we want to use

• -H refers to a header, you can use multiple headers by using multiple ‘-H’

• -d refers to the data or body of the request

  2. File upload Endpoint

• Host: -5
• Endpoint: /api/v2/upload/<SESSION-ID>?userId=<CORE-ID>@motorolasolutions.com
• HTTP Type: POST
• Headers:
  x-msi-genai-api-key: <INSERT API KEY HERE>
  Content-Type: multipart/form-data
  X-msi-genai-client (optional): <some-unique-app-identifier>

Note:

• The SESSION-ID is mandatory, and hence a file CANNOT be the first message in chat history. Obtain a session id by initiating a chat session specified in 4.1
• The userId is optional and by default is set to the user who created the token.
• The owner of the SESSION-ID should match the userId

The curl command for the request looks like this:

curl -X POST --location 'https://genai-service.stage.commandcentral.com/app-gateway/api/v2/upload/<SESSION-ID>' \
--header 'x-msi-genai-api-key: <key-value>' \
--form 'file=@"/var/pdf/myfile.pdf"'

3. Get Session Messages/Datastore Files Endpoint {#get-session-messages/datastore-files-endpoint}

• Host: https://genai-service.stage.commandcentral.com/app-gateway
• Endpoint: /api/v2/getSessionMessages/<SESSION-ID>?userId=<CORE-ID>@motorolasolutions.com&page=1&limit=10
• HTTP Type: GET
• Headers:
  x-msi-genai-api-key: <INSERT API KEY HERE>
  X-msi-genai-client (optional): <some-unique-app-identifier>

Note:

• The SESSION-ID is mandatory. For Datastores, pass the datastore id as SESSION-ID.
• The userId is optional and by default is set to the user who created the token.
• The owner of the SESSION-ID should match the userId.
• The page & limit are optional and meant for pagination for large message sessions. By default, all messages are returned.

The curl command for the request looks like this:

curl -X GET --location 'https://genai-service.stage.commandcentral.com/app-gateway/api/v2/getSessionMessages/<SESSION-ID>?page=1&limit=2' \
--header 'x-msi-genai-api-key: <key-value>'

The response structure is

{
    "status": true,
    "TotalSessionLength": "134",
    "data": [
,
        {
            "id": 1,
            "msg": "hi",
            "role": "user",
            "type": "text"
        },
        {
            "id": 2,
            "msg": "Hi! 😊  How can I assist you today? \n",
            "role": "assistant",
            "type": "text"
        }
    ]
}

Note:

• The status will be true if the data is successfully retrieved; false otherwise

• The TotalSessionLength gives the total number of messages in the specified session.

• The data has the list of messages (as per page and limit specified, if any) ordered by increasing order of chronology (most recent message is at the last of the array).

• Each msg has a unique id which can be used to delete the message from the session.

  4. Delete Message Endpoint

• Host: https://genai-service.stage.commandcentral.com/app-gateway

• Endpoint: /api/v2/entry/<MSG-ID>?userId=<CORE-ID>@motorolasolutions.com

• HTTP Type: DELETE

• Headers:
  x-msi-genai-api-key: <INSERT API KEY HERE>
  X-msi-genai-client (optional): <some-unique-app-identifier>

Note:

• The MSG-ID is mandatory
• The userId is optional and by default is set to the user who created the token.
• The owner of the MSG-ID should match the userId

The curl command for the request looks like this:

curl -X DELETE --location 'https://genai-service.stage.commandcentral.com/app-gateway/api/v2/entry/<MSG-ID>' \
--header 'x-msi-genai-api-key: <key-value>'

5. Initialise Datastore Endpoint

   Host: https://genai-service.stage.commandcentral.com/app-gateway

   Endpoint: /api/v2/initDataStore/datastore/<DATASTORE-NAME>

   HTTP Type: POST

   Headers:

   x-msi-genai-api-key: <INSERT API KEY HERE>

   X-msi-genai-client (optional): <some-unique-app-identifier>

Note:

• The DATASTORE-NAME is mandatory
• Datastore ID can be retrieved from the response payload
• You can upload files to the datastore using the file upload endpoint.

The curl command for the request looks like this:

curl -X POST --location 'genai-service.stage.commandcentral.com/app-gateway/api/v2/initDataStore/datastore/<DATASTORE-NAME>' \
--header 'x-msi-genai-api-key: <key-value>'

6. Get Chat Sessions Endpoint

• Host: https://genai-service.stage.commandcentral.com/app-gateway
• Endpoint: /api/v2/getChatSessions/<MODEL>
• HTTP Type: GET
• Headers:
  x-msi-genai-api-key: <INSERT API KEY HERE>
  X-msi-genai-client (optional): <some-unique-app-identifier>

Note:

• The MODEL is mandatory PARAMETER.

The curl command for the request looks like this:

curl -X GET --location 'https://genai-service.stage.commandcentral.com/app-gateway/api/v2/getChatSessions/<MODEL>' \
--header 'x-msi-genai-api-key: <key-value>'

The response structure is

{
    "status": true,
    "msg": "Session fetched successfully",
    "data": [
,
        {
            "sessionId": "7cads-a9123-1a1ddd",
            "sessionTittle": "hi",
            "sessionchatinstruction": "",
            "total_tokens": 0
        },
        {
            "sessionId": "8bads-a9123-1a1ddd",
            "sessionTittle": "why is sky blue",
            "sessionchatinstruction": "",
            "total_tokens": 0
        },
    ],	
     "user_cost": "0"
}

Note:

• The status will be true if the data is successfully retrieved; false otherwise
• The user_cost will return the monthly usage cost value of the portal.
• The data has the list of messages (as per page and limit specified, if any) ordered by increasing order of chronology (most recent message is at the last of the array).
• Each sessionTitle has a unique sessionId

5. API Error Codes

General Error Codes
400 Bad Request	The request was malformed or contained invalid parameters.
401 Unauthorized	The user is not authenticated or lacks permission to perform the requested action.
403 Forbidden	The user is authenticated but lacks the necessary permissions for the requested action.
404 Not Found	The requested resource (model, user, API key, session, etc.) was not found.
405 Method Not Allowed	The requested method (GET, POST, PUT, DELETE) is not allowed for the resource.
409 Conflict	The requested action cannot be completed due to a conflict, such as attempting to create a duplicate resource.
500 Internal Server Error	An unexpected error occurred on the server.
502 Bad Gateway	The server received an invalid response from a downstream server.
503 Service Unavailable	The server is currently unavailable.

Error Codes Breakdown

fileHandlerService:

uploadFile
400	Invalid Datastore ID.
500	Error while uploading the file.
deleteMessage
400	Invalid request, missing msgId.
401	Unauthorized.
404	Message not found.
500	Internal error while deleting the message.

usersHandler:

getSessionMessages
400	Invalid request body, missing sessionId.
401	Unauthorized access to the session.
500	Internal error while fetching session messages.
chat
400	Invalid request, missing model or prompt, or model not found.
500	Internal error while processing the chat request.

Error Response Format:

All error responses follow a consistent format:
json
{
"status": false,
"msg": "Error message. Correlation ID: <transactionId>"
}

Note:

• <transactionId> is a unique identifier for the request.
• The error field might be present in certain error responses, providing additional details about the error.

6. Model Access & Privacy

Model Name (ID)	Friendly Name	Privacy Status
ChatGPT4o	GPT4 Omni	Public
ChatGPT4o-mini	GPT4o Omni Mini	Private
ChatGPT-o3-mini	GPT o3 Omni	Private
Gemini-2_0-Flash-001	Gemini 2.0 Flash	Private
Gemini-2_5-Flash	Gemini 2.5 Flash	Private
Claude-Sonnet-3_7	Claude-Sonnet 3.7	Private
Openai-gpt-4_1-mini	OpenAI GPT 4.1 Mini	Private
Openai-o4-mini	OpenAI o4 Mini	Public
Claude-Sonnet-4	Claude Sonnet 4	Public
ChatGPT-o3-pro	ChatGPT o3 Pro	Private
OpenAI-ChatGPT-4_1	OpenAI ChatGPT 4.1	Private
OpenAI-GPT-4_1-Nano	OpenAI ChatGPT 4.1 Nano	Private
ChatGPT-5	OpenAI ChatGPT5	Private
VertexGemini	Gemini 2.0 Flash 001	Private
ChatGPT-5_1	ChatGPT 5.1	Private
ChatGPT-5_1-chat	ChatGPT 5.1 Chat	Private
ChatGPT-5_2-Chat	ChatGPT 5.2 Chat	Public
Gemini-3_Pro-Preview	Gemini 3 Pro	Private