Open API

Overview

The basic process for calling the SERVICEME Open API:

Step 1: Use the interface provided in the authentication section to perform identity authentication and obtain an access token

There are two types of authentication: user authentication and client authentication.

User authentication: Authentication based on a personal account identity.
Client authentication: Authentication using the client code and secret issued by SERVICEME.

Step 2: Use the access token to call the corresponding API

Authentication Methods

User AAD Authentication

This method is a type of user authentication and requires the use of an AAD access token as the basis for identity authentication.

How to obtain an AAD access token:

AAD and React integration documentation: Go to->

AAD and .Net integration documentation: Go to->

AAD and Java integration documentation: Go to->
API endpoint: /openapi/auth/user/aad
Request method: post
Request body:

Parameter Name	Required	Type	Description
token	Yes	string	User AAD access token (provided by integrator)

API request example:

curl --location 'https://localhost/openapi/auth/user/aad' \
--header 'Content-Type: application/json' \
--data '{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlhSdmtvOFA3QTNVYVdTblU3Yk05blQwTWpoQSJ9.eyJhdWQiOiIzZTEwNjVhYS1jZWYxLTRiYTgtOWRiOS1kMWQ1Y2UzMGYyZDgiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNDRjMjRmNDItZDQ5Yi00MT......"
}'

Response body:

Parameter Name	Sub-parameter	Type	Description
data		object	Response data
	access_token	string	SERVICEME system access token
	expires_in	number	Expiration time, in minutes
success		boolean	Whether the request was successful
msg		string	If success is false, this field contains error messages

Response example:

{
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc0V4dGVybmFsIjpmYWxzZSwidXNlcklkIjoiNDAzMDUwMjEwMTEyODgzOTE2OCIsImFjY291bnQiOiJlY210cmlhbEBzZXJ2aWNlbWUub25taWNyb3NvZ......",
        "expires_in": 1440
    },
    "success": true,
    "msg": ""
}

Client and User Account Authentication

This authentication method combines client authentication and user account authentication. Identity authentication is performed through the user account, and client credentials (client id and secret) are also required to ensure the security of API calls. Signature verification is required when calling this interface.

How to obtain client and secret?

The system administrator creates credentials through the client management interface {domain}#/super-admin/client-management. After creation, the client id and secret can be obtained.

API endpoint: /openapi/auth/client_with_account
Request method: post
Request body:

Parameter Name	Required	Type	Description
client	Yes	string	Client Id
account	Yes	string	User account (corresponds to UserName in user management)
timestamp	Yes	number	Timestamp (13-digit number, accurate to milliseconds, e.g. 1711537596897)
nonce	Yes	string	6-digit random string (can be a combination of numbers or letters)
signature	Yes	string	Signature, valid within five minutes (Signature format: concatenate with colons and then MD5 `client:{client}secret:{secret}account:{account}timestamp:{timestamp}nonce:{nonce}`; the resulting 32-character lowercase MD5 value)

JavaScript signature example:

Please create a new HTML file, paste the following content, and open it in your browser

<html>
  <head>
    <style>
      .box {
         width: 100%;
         height: 100%;
         padding: 50px 50px;
       }
       .row {
            display: flex;
            height: 50px;
            width: 100%;
          }
          .col1 {
            flex: 1;
       }
       .col2 {
         flex: 3;
       }
     </style>
   </head>
   <body>
      <div class="box">
      <div class="row">
           <div class="col1">client:</div>
           <div class="col2" id="client"></div>
         </div>
         <div class="row">
           <div class="col1">secret:</div>
           <div class="col2" id="secret"></div>
         </div>
        <div class="row">
        <div class="col1">account:</div>
        <div class="col2" id="account"></div>
      </div>
      <div class="row">
         <div class="col1">timestamp:</div>
         <div class="col2" id="timestamp"></div>
       </div>
       <div class="row">
         <div class="col1">nonce:</div>
         <div class="col2" id="nonce"></div>
       </div>
       <div class="row">
         <div class="col1">signature:</div>
         <div class="col2" id="signature"></div>
       </div>
     </div>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.0.0/crypto-js.min.js"></script>
     <script>
       const client = "openapi"
       const secret = "DzYwyICrKbUCEseYthCK0PfSfX7NPEuV"
       const account = "test@serviceme.com"
       const timestamp = +new Date()
       const nonce = "123abc"
       const message = `client:${client}secret:${secret}account:${account}timestamp:${timestamp}nonce:${nonce}` // Signature plaintext
       const md5Hash = CryptoJS.MD5(message).toString().toLowerCase(); // MD5 32-bit lowercase
   
       console.log(`Signature plaintext: ${message}`)
       console.log(`Signature result: ${md5Hash}`)
  
       document.getElementById('client').innerText = client;
       document.getElementById('secret').innerText = secret;
       document.getElementById('account').innerText = account;
       document.getElementById('timestamp').innerText = timestamp;
       document.getElementById('nonce').innerText = nonce;
       document.getElementById('signature').innerText = md5Hash;
     </script>
   </body>
   </html>

API request example:

curl --location 'https://localhost/openapi/auth/client_with_account' \
--header 'Content-Type: application/json' \
--data '{
    "client": "openapi",
    "account": "test@serviceme.com",
    "timestamp": 1711537596456,
    "nonce": "123abc",
    "signature": "182be0c5cdcd5072bb1864cdee4d3d6e"
}'

Response body

Parameter Name	Sub-parameter	Type	Description
data		object	Response data
	access_token	string	SERVICEME system access token
	expires_in	number	Expiration time, in minutes
success		boolean	Whether the request was successful
msg		string	If success is false, this field contains error messages

API response example:

{
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc0V4dGVybmFsIjpmYWxzZSwidXNlcklkIjoiNDAzMDUwMjEwMTEyODgzOTE2OCIsImFjY291bnQiOiJlY210cmlhbEBzZXJ2ub25ta......",
        "expires_in": 1440
    },
    "success": true,
    "msg": ""
}

Chat

Send Message to Agent

API endpoint: /openapi/chat/expert
Request method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Request body:

Parameter Name	Required	Type	Description
expertCode	Yes	string	Agent code in the SERVICEME system (see SERVICEME system)
content	Yes	string	Question content
sessionId	No	string	Session id, represents a chat context; passing null starts a new session, the new session id will be returned in the response. From the second Q&A onwards, you need to carry the session id returned from the previous response to continue.
stream	No	boolean	Whether to enable streaming (true: on; false: off), default is off
includeThought	No	boolean	Whether to include thoughts in the response content (true: include; false: do not include)

How to obtain the Q&A code? See the image below:

Request example:

curl --location 'https://localhost/vee/openapi/chat/expert' \
--header 'Authorization: openapi {access_token}' \
--header 'Content-Type: application/json' \
--data '{
    "expertCode": "CHATES",
    "content": "加班申请",
    "sessionId": null,
    "stream": false,
    "includeThought": true
}'

Response body:

Parameter	Sub-parameter	Sub-sub-parameter	Sub-sub-sub-parameter	Type	Description
data				object	Response data
	chatRecordId			string	Chat record id
	sessionId			string	Session id
	content			string	Text-type answer information
	medias			object	Array of media-type answer information (images, files, etc.)
		type		string	image: image; file: file
		name		string	Name
	suggestionQuestions			array string	Suggested questions
	thoughts			array	Thoughts
		thought		string	Thought content
		pluginName		string	Plugin name
		elapsedTime		object	Plugin elapsed time information
			model	float	Model elapsed time
			action	float	Action elapsed time
			total	float	Total elapsed time
		state		string	State (success: successful)
	finish_reason			string	Whether the answer is finished; value "stop" means finished, null during answering
success				boolean	Whether the request was successful
msg				string	If success is false, this field contains error messages

Non-streaming response example:

{
    "data": {
        "chatRecordId": "4299234148041625600",
        "sessionId": "4292755814873047040",
        "content": "The team leader issues work tasks, clarifies completion milestones and acceptance criteria, and employees can only work overtime after reaching an agreement with their supervisor. After working overtime, employees fill in overtime hours in the time system, submit the overtime process in the system, and clearly state the overtime tasks in the remarks. Complete clock-in and clock-out records must be kept at the workplace. After the team leader/supervisor accepts the overtime results, the overtime application process is approved. HR confirms the clock-in records and calculates compensatory leave.",
        "medias": [
			{
        		"type": "image",
                "name": null,
                "url":"http://localhost:3978/openapi/chat/media/image/FE680A9CCFB1B56E80737FB28562DC33F4A37DEF52A65F046464788B83E0BE77"
            },
            {
        		"type": "file",
                "name": "答案参考文件.pdf",
                "url":"https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login"
            },
        ],
        "suggestionQuestions": [],
        "thoughts": [
            {
                "thought": "To answer this question, I need to query relevant information in the knowledge base.",
                "pluginName": "Search Knowledgebase",
                "elapsedTime": {
                    "model": 3612.4722,
                    "action": 689.5891,
                    "total": 4302.0613
                },
                "state": "success"
            }
        ],
        "finish_reason": "stop"
    },
    "success": true,
    "msg": ""
}

Streaming response example:

data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"","medias":[],"suggestionQuestions":[],"thoughts":[{"thought":"To answer this question, I need to query relevant information in the knowledge base.","pluginName":"Search Knowledgebase","elapsedTime":{"model": 3612.4722,"action": 689.5891,"total": 4302.0613},"state": "success"}],"finish_reason":null},"success":true,"msg":""}

data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"The team leader issues work tasks, clarifies completion milestones and acceptance criteria, and employees can only work overtime after reaching an agreement with their supervisor. After working overtime, employees fill in overtime hours in the time system, submit the overtime process in the system, and clearly state the overtime tasks in the remarks. Complete clock-in and clock-out records must be kept at the workplace. After the team leader/supervisor accepts the overtime results, the overtime application process is approved. HR confirms the clock-in records and calculates compensatory leave.","medias":[],"suggestionQuestions":[],"thoughts":[],"finish_reason":null},"success":true,"msg":""}

data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"","medias":[{"type":"image","name":null,"url":"http://localhost:3978/openapi/chat/media/image/FE680A9CCFB1B56E80737FB28562DC33F4A37DEF52A65F046464788B83E0BE77"}],"suggestionQuestions":[],"thoughts":[],"finish_reason":null},"success":true,"msg":""}

data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"","medias":[{"type":"file","name":"答案参考文件.pdf","url":"https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login"}],"suggestionQuestions":[],"thoughts":[],"finish_reason":"stop"},"success":true,"msg":""}

Get References for a Conversation

API endpoint: /openapi/chat/record/{chatRecordId}/reference
Request method: get
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Request URL parameters:

Parameter Name	Required	Type	Description
chatRecordId	Yes	string	Value taken from the chatRecordId field returned by the Q&A interface

Request example:

curl --location 'http://localhost/openapi/chat/record/4299234148041625600/reference' \
--header 'Authorization: openapi {access_token}'

Response body:

Parameter Name	Sub-parameter	Type	Description
data		object array	Response data
	title	string	Title
	content	string	Content of the referenced fragment in this chat record
	score	float	Relevance (0 to 1, the closer to 1, the more relevant)
	url	string	Link (currently only file-type references have links)
	type	string	Type enum: document, image, QnA, other
success		boolean	Whether the request was successful
msg		string	If success is false, this field contains error messages

Response example:

json
{
    "data": [
        {
            "title": "Company Administrative Policy.pdf",
            "content": "Fragment One ......",
            "score": 0.95,
            "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
            "type": "document"
        },
        {
            "title": "Company Administrative Policy.pdf",
            "content": "Fragment Two ......",
            "score": 0.81,
            "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
            "type": "document"
        },
        {
            "title": "Company Administrative Policy.pdf",
            "content": "Fragment Three ......",
            "score": 0.76,
            "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
            "type": "document"
        }
    ],
    "success": true,
    "msg": ""
}

File Workspace

Single File Upload

API Endpoint: v1/openapi/workspace/file/upload
Request Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Content Type: form-data
Request body:

Parameter Name	Required	Type	Description
workspace	Yes	string	File workspace
file	Yes	file	File (single)
eponymousCover	No	bool	Whether to overwrite if a file with the same name exists (default: do not overwrite)

Request Example:

curl --location 'http://localhost/v1/openapi/workspace/file/upload' \
--header 'Authorization: openapi {access_token}' \
--form 'workspace="Test Workspace"' \
--form 'file=@"/C:/test.doc"' \
--form 'eponymousCover="false"'

Response body:

Parameter Name	Sub-parameter	Type	Description
data		object	Response data
	fileId	string	File id
	fileName	string	File name
	uploader	string	Uploader
success		boolean	Whether successful
msg		string	If success is false, this field contains error messages

Response Example:

{
    "data": {
        "fileId": "4345229404125790208",
        "fileName": "test.doc",
        "uploader": "test@serviceme.com"
    },
    "success": true,
    "msg": ""
}

Batch File Upload

Submit Files

API Endpoint: v1/openapi/workspace/file/upload/batchSubmit
Request Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Content Type: form-data
Request body:

Parameter Name	Required	Type	Description
workspace	Yes	string	File workspace
files	Yes	file	Files (multiple)
eponymousCover	No	bool	Whether to overwrite if a file with the same name exists (default: do not overwrite)

Request Example:

curl --location 'http://localhost/v1/openapi/workspace/file/upload/batchSubmit' \
--header 'Authorization: openapi {access_token}' \
--form 'workspace="Test Workspace"' \
--form 'files=@"/C:/test1.doc"' \
--form 'files=@"/C:/test2.docx"' \
--form 'eponymousCover="false"'

Response body:

Parameter Name	Sub-parameter	Type	Description
data		object	Response data
	stateId	string	Upload state id, use this id to poll for the latest upload result
success		boolean	Whether successful
msg		string	If success is false, this field contains error messages

Response Example:

{
    "data": {
        "stateId": "4345229404125790208"
    },
    "success": true,
    "msg": ""
}

Query Upload Result

API Endpoint: v1/openapi/workspace/file/upload/batchSubmit/{stateId}
Request Method: get
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Request URL Parameters:

Parameter Name	Required	Type	Description
stateId	Yes	string	The stateId field value returned by the batch file upload API

Request Example:

curl --location 'http://localhost/v1/openapi/workspace/file/upload/batchSubmit/4345227891722682368' \
--header 'Authorization: openapi {access_token}'

Response body:

Parameter Name	Sub-parameter	Type	Description
data		object array	Response data
	fileId	string	File Id
	fileName	string	File name
	state	string	State enum: underway (in queue), success, fail
	uploader	string	Uploader
	errorMsg	string	If state is fail, the reason for failure
	finishTime	string	File processing completion time
success		boolean	Whether successful
msg		string	If success is false, this field contains error messages

Response Example:

{
    "data": [
        {
            "fileId": "4345227925730099200",
            "fileName": "test1.doc",
            "state": "success",
            "uploader": "test@serviceme.com",
            "errorMsg": "",
            "finishTime": "2024-08-17T05:04:30.0128596Z"
        },
        {
            "fileId": "4345227924266287104",
            "fileName": "test2.docx",
            "state": "success",
            "uploader": "test@serviceme.com",
            "errorMsg": "",
            "finishTime": "2024-08-17T05:04:29.7952274Z"
        }
    ],
    "success": true,
    "msg": ""
}

QnA Creation

API Endpoint: v1/openapi/workspace/qna/create
Request Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Request body:

Parameter Name	Sub-parameter	Required	Type	Description
workspace		Yes	string	File workspace
questions		Yes	string array	Array of questions, multiple allowed
answer		Yes	string	Answer
metadatas		No	object array	Metadata
	typeCode	Yes	string	Metadata type
	content	Yes	string	Content

Request Example:

curl --location 'http://localhost/v1/openapi/workspace/qna/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: openapi {access_token}' \
--data '{
    "questions": [
        "Test question"
    ],
    "answer": "Test answer",
    "workspace": "Test Workspace",
    "metadatas": [
        {
            "typeCode": "Document type",
            "content": "Test metadata"
        }
    ]
}'

Response body:

Parameter Name	Type	Description
success	boolean	Whether successful
msg	string	If success is false, this field contains error messages

Response Example:

{
    "success": true,
    "msg": ""
}

Query Files

API Endpoint: v1/openapi/workspace/file
Request Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Request body:

Parameter Name	Required	Type	Description
workspace	Yes	string	File workspace
pageIndex	No	number	Page number, default is first page
pageSize	No	number	Number of items to retrieve, default is 10

Request Example:

curl --location 'http://localhost/v1/openapi/workspace/file' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "workspace": "Test Workspace",
    "pageIndex": 1,
    "pageSize": 10
}'

Response body:

Parameter Name	Sub-parameter	Sub-sub-parameter	Type	Description
data			object array	Response data
	id		string	File id
	name		string	File name
	size		number	File size, in bytes
	description		string	Description
	fullPath		string	File path
	tags		object array	File tag information
		id	string	Tag id
		value	string	Tag value
	chunkingState		string	File index state: waiting, success, fail, underway
	previewState		string	File preview state: waiting, success, fail, underway
	fileCanPreview		boolean	Whether file can be previewed, true: yes; false: no
	previewUrl		string	File preview URL
	createdByRealName		string	File creator name
	createdByAccount		string	File creator account
	created		datetime	File creation time
	modifiedByRealName		string	File editor name
	modifiedByAccount		string	File editor account
	modified		datetime	File modification time
success			boolean	Whether successful
msg			string	If success is false, this field contains error messages

Response Example:

{
    "data": [
        {
            "id": "4339013367831199744",
            "name": "test.docx",
            "size": 15113,
            "description": null,
            "fullPath": "/",
            "tags": [],
            "chunkingState": "success",
            "previewState": "success",
            "fileCanPreview": true,
            "previewUrl": "http://localhost.com/#/share/preview?fileId=4339013367831199744&objectType=2&previewType=file&mode=login",
            "createdByRealName": "test",
            "createdByAccount": "test",
            "created": "2024-07-31T01:30:02.88",
            "modifiedByRealName": "test",
            "modifiedByAccount": "test",
            "modified": "2024-07-31T01:30:02.88"
        }
    ],
    "pageSize": 10,
    "pageIndex": 1,
    "totalCount": 1,
    "success": true,
    "msg": ""
}

Query File Fragments

API Endpoint: v1/openapi/workspace/file/chunk
Request Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Request body:

Parameter Name	Required	Type	Description
fileId	Yes	string	File id
imageFormat	No	string	Image format, markdown or html, default is markdown output
pageIndex	No	number	Page number, default is first page
pageSize	No	number	Number of items to retrieve, default is 10

Request Example:

curl --location 'http://localhost/v1/openapi/workspace/file/chunk' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "fileId": "4344174161665458176",
    "imageFormat": "html",
    "pageIndex": 1,
    "pageSize": 10
}'

Response body:

Parameter Name	Sub-parameter	Type	Description
data		object array	Response data
	id	string	Fragment id
	content	string	Fragment content
success		boolean	Whether successful
msg		string	If success is false, this field contains error messages

Response Example:

json
{
    "data": [
        {
            "id": "4339013367831199744",
            "content": "test"
        }
    ],
    "pageSize": 10,
    "pageIndex": 1,
    "totalCount": 1,
    "success": true,
    "msg": ""
}

RAG

API Endpoint: /v1/openapi/rag
HTTP Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Request body:

Parameter Name	Type	Required	Default	Description
`query`	`string`	No	None	The question or content to be retrieved. Cannot be `null` at the same time as the Keywords parameter.
`keywords`	`string`	No	None	Keywords, multiple keywords separated by `\|`. Cannot be `null` at the same time as the Query parameter. If `null`, keywords will be extracted as needed; if not empty, the provided keywords will be used directly.
`workspaces`	`array`	No	None	Names or IDs of the file spaces to be searched in this RAG. If this value is provided, only these spaces will be searched.
`ragObject`	`RagObject`	Yes	`0`	RAG object type, enum value (see RagObject Enum).
`topk`	`number`	Yes	None	Number of results to return.
`minSimilarity`	`double`	No	`0.8`	Minimum similarity, range `[0, 1]`.
`metadataFilter`	`array`	No	None	Types of metadata filters to use. Currently only the default filter is supported.
`ragMode`	`SearchMode`	Yes	`0`	RAG mode, enum value (see SearchMode Enum).
`weights`	`object`	No	None	RRF weights for each index, only effective when `RagMode` is `Hybrid`. If `null`, default weights are used.
`reranker`	`string`	No	None	If `null`, `reranker` will not be used.

Request Example:

curl --location 'http://localhost/v1/openapi/rag' \
--header 'Authorization: ••••••' \
--header 'Content-Type: application/json' \
--data '{  
    "query": "什么是人工智能？",  
    "keywords": "AI|机器学习",  
    "workspaces": ["workspace1", "workspace2"],  
    "ragObject": 0,  
    "topk": 3,  
    "minSimilarity": 0.8,  
    "metadataFilter": ["default"],  
    "ragMode": 1,  
    "weights": {  
        "Embedding": 0.9,  
        "FullText": 0.8  
    },  
    "reranker": "default"  
}  '

Response body:

Field Name	Type	Description
`data`	`object`	Response data object, containing search results and search ID, etc.
`data.results`	`array`	List of search results, each element is an object containing chunk information.
`data.results[].chunkId`	`string`	Chunk ID
`data.results[].fileId`	`string`	File ID to which the chunk belongs
`data.results[].fileName`	`string`	File name to which the chunk belongs
`data.results[].content`	`string`	Chunk content
`data.results[].metadata`	`json`	Chunk metadata
`data.results[].url`	`string`	URL address of the chunk (if any)
`data.results[].searchScore`	`double`	Similarity score
`data.results[].rrfScore`	`double`	RRF score
`data.results[].rerankScore`	`double`	Rerank score
`data.results[].workspaceId`	`string`	Workspace ID to which the file belongs
`data.results[].workspaceName`	`string`	Workspace name to which the file belongs
`data.searchId`	`string`	Unique identifier for this search operation
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
    "data": {
        "results": [
            {
                "chunkId": "4422442085118906369",
                "fileId": "4417076017114382336",
                "fileName": "文件1.pdf",
                "content": "……",
                "metadata": {
                    "Url": "https://……",
                    "FileName": "文件1.pdf",
                    "WorkspaceName": "workspace1",
                    "FileId": "4417076017114382336",
                    "FilePath": "/",
                    "Created": "2025-03-03T11:23:08.803",
                    "Size": "1160594"
                },
                "url": "https://……",
                "searchScore": 0.153852914388501,
                "rrfScore": 0.8768274796195331,
                "rerankScore": 0.0,
                "workspaceId": "4417069258022846464",
                "workspaceName": ""
            },
            {
                "chunkId": "4422442085114712073",
                "fileId": "4417076017114382336",
                "fileName": "文件1.pdf",
                "content": "……",
                "metadata": {
                    "Url": "https://……",
                    "FileName": "文件1.pdf",
                    "WorkspaceName": "workspace1",
                    "FileId": "4417076017114382336",
                    "FilePath": "/",
                    "Created": "2025-03-03T11:23:08.803",
                    "Size": "1160594"
                },
                "url": "https://……",
                "searchScore": 0.152822583517241,
                "rrfScore": 0.8670604574184315,
                "rerankScore": 0.0,
                "workspaceId": "4417069258022846464",
                "workspaceName": ""
            },
            {
                "chunkId": "4422442085114712071",
                "fileId": "4417076017114382336",
                "fileName": "文件1.pdf",
                "content": "……",
                "metadata": {
                    "Url": "……",
                    "FileName": "文件1.pdf",
                    "WorkspaceName": "workspace1",
                    "FileId": "4417076017114382336",
                    "FilePath": "/",
                    "Created": "2025-03-03T11:23:08.803",
                    "Size": "1160594"
                },
                "url": "……",
                "searchScore": 0.153708375384407,
                "rrfScore": 0.8661891817471927,
                "rerankScore": 0.0,
                "workspaceId": "4417069258022846464",
                "workspaceName": ""
            }
        ],
        "searchId": "4423568945336811520"
    },
    "success": true,
    "msg": ""
}

Enum Types

RagObject Enum

Enum Value	Enum Number	Description
`Both`	0	Retrieve both Q&A and document content.
`Qna`	1	Retrieve only Q&A content.
`Doc`	2	Retrieve only document content.

SearchMode Enum

Enum Value	Enum Number	Description
`Hybrid`	1	Hybrid search mode, combining embedding and full-text search.
`Embedding`	2	Search mode based only on embeddings.
`FullText`	3	Search mode based only on full-text search.

Rerank Model Configuration Taking the configuration of the cohere-rerank-v3.5 model as an example:

INSERT INTO dbo.AI_LLM (Id,ModelName,TokenCount,Config,Enable,[Default],Display,DisplayName) VALUES
(4183721090264072898,N'rerank-v3.5',255454,N'{"RerankerName":"cohere","Uri":"https://domain/v2/rerank","Token":"bearer token"}',1,0,0,N'cohere-rerank-v3.5');

Note: If you are using the Cohere official API, the value of the Token field should be bearer token. If you are using the Azure AI Foundry API, the value of the Token field should remove bearer.

User

Add User (Batch Supported)

API Endpoint: v1/openapi/user
HTTP Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
`userName`	Yes	`string`	None	Account/User name
`password`	No	`string`	''	Password
`active`	No	`boolean`	true	Active status
`userInfo`	No	`object`	None	User information
`userInfo.realName`	No	`string`	Value of userName	Real name
`userInfo.spell`	No	`string`	None	Pinyin of real name
`userInfo.serialNumber`	No	`string`	None	Employee number
`userInfo.nickName`	No	`string`	None	Nickname
`userInfo.gender`	No	`number`	0	Gender 0:FEMALE, 1:MALE
`userInfo.birthday`	No	`string`	None	Birthday
`userInfo.mobilePhone`	No	`string`	None	Mobile phone number
`userInfo.email`	No	`string`	None	Email
`userInfo.weChat`	No	`string`	None	WeChat ID
`userInfo.avatar`	No	`string`	None	Avatar
`userInfo.region`	No	`string`	None	Region
`userInfo.joinTime`	No	`string`	None	Date of joining
`userInfo.sort`	No	`number`	0	Sort number
`userInfo.enable`	No	`boolean`	false	Enable/Disable
`userInfo.description`	No	`string`	None	Description
`userInfo.external`	No	`boolean`	false	Internal/External user flag false: internal user, true: external user
`userInfo.officePhoneNumber`	No	`string`	None	Office phone number
`userInfo.isAad`	No	`string`	None	Whether the account is from AAD (Microsoft Entra ID)

Request Example:

curl --location 'http://localhost/v1/openapi/user' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "userName": "user1",  
    "password": "abc123",  
    "active": true,  
    "userInfo": {  
        "realName": "张三",  
        "spell": "zhangsan",
        "serialNumber": "123456",
        "nickName": "张三",
        "gender": 0,
        "birthday": "1990-01-01",
        "mobilePhone": "13800138000",
        "email": "zhangsan@email.com",
        "weChat": "zhangsan",
        "avatar": "/icons/e5392a9c9efb423cab69ce040dcb04e7.png",
        "region": "中国",
        "joinTime": "2023-01-01",
        "sort": 101,
        "enable": true,
        "description": "张三的描述",
        "external": false,
        "officePhoneNumber": "010-12345678",
        "isAad": false
    },  
}  '

Response body:

Field Name	Type	Description
`data`	`object`	Response data object
`data.accountId`	`string`	Account ID
`data.userId`	`string`	User ID
`data.userName`	`string`	User name
`data.realName`	`string`	User real name
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": "",
	"data": [
		{
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "张三"
		}
	]
}

Update User

API Endpoint: v1/openapi/user
HTTP Method: put
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in the SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
`userName`	No	`string`	None	Account/User name, only used to find the user and will not be modified, cannot both be empty with id
`id`	No	`string`	''	id, cannot both be empty with userName
`active`	No	`boolean`	true	Active status
`realName`	No	`string`	Value of userName	Real name
`spell`	No	`string`	None	Pinyin of real name
`serialNumber`	No	`string`	None	Employee number
`nickName`	No	`string`	None	Nickname
`gender`	No	`number`	0	Gender 0:FEMALE, 1:MALE
`birthday`	No	`string`	None	Birthday
`mobilePhone`	No	`string`	None	Mobile phone number
`email`	No	`string`	None	Email
`weChat`	No	`string`	None	WeChat ID
`avatar`	No	`string`	None	Avatar
`region`	No	`string`	None	Region
`joinTime`	No	`string`	None	Date of joining
`sort`	No	`number`	0	Sort number
`enable`	No	`boolean`	false	Enable/Disable
`description`	No	`string`	None	Description
`external`	No	`boolean`	false	Internal/External user flag false: internal user, true: external user
`officePhoneNumber`	No	`string`	None	Office phone number
`isAad`	No	`string`	None	Whether the account is from AAD (Microsoft Entra ID)

Request Example:

shell
curl --location 'http://localhost/v1/openapi/user' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "id": "123456",
    "userName": "user1",   
    "realName": "Zhang San",  
    "spell": "zhangsan",
    "serialNumber": "123456",
    "nickName": "Zhang San",
    "gender": 0,
    "birthday": "1990-01-01",
    "mobilePhone": "13800138000",
    "email": "zhangsan@email.com",
    "weChat": "zhangsan",
    "avatar": "/icons/e5392a9c9efb423cab69ce040dcb04e7.png",
    "region": "China",
    "joinTime": "2023-01-01",
    "sort": 101,
    "enable": true,
    "description": "Description of Zhang San",
    "external": false,
    "officePhoneNumber": "010-12345678",
    "isAad": false
}  '

Response body:

Field Name	Type	Description
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": ""
}

Delete User

Endpoint: v1/openapi/user
HTTP Method: delete
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
	Yes	`array`	None	Array of user IDs or usernames. The array must contain only IDs or only usernames.

Request Example:

curl --location 'http://localhost/v1/openapi/user' \
--header 'Authorization: openapi {access_token}' \
--data '['user1','user2']'

Response body:

Field Name	Type	Description
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": ""
}

Enable User

Endpoint: v1/openapi/user/{userCode}/enable
HTTP Method: put
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Route parameters:

Parameter Name	Required	Type	Default	Description
userCode	Yes	`string`	None	User ID or username

Request Example:

curl --location 'http://localhost/v1/openapi/user/123456/enable' \
--header 'Authorization: openapi {access_token}' \

Response body:

Field Name	Type	Description
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": ""
}

Disable User

Endpoint: v1/openapi/user/{userCode}/disable
HTTP Method: put
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Route parameters:

Parameter Name	Required	Type	Default	Description
userCode	Yes	`string`	None	User ID or username

Request Example:

curl --location 'http://localhost/v1/openapi/user/123456/disable' \
--header 'Authorization: openapi {access_token}' \

Response body:

Field Name	Type	Description
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": ""
}

Enable/Disable Users (Batch Supported)

Endpoint: v1/openapi/user/enable
HTTP Method: put
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
codes	Yes	`array`	None	Array of user IDs or usernames. The array must contain only IDs or only usernames.
operation	Yes	`boolean`	true	true: enable, false: disable

Request Example:

curl --location 'http://localhost/v1/openapi/user/enable' \
--header 'Authorization: openapi {access_token}' \
--data '{
  "codes": ['user1', 'user2'],
  "operation": true
}'

Response body:

Field Name	Type	Description
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": ""
}

Get User List (Paginated)

Endpoint: v1/openapi/user/pageList
HTTP Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
`orderField`	Yes	`string`	None	Field for sorting. The ID contains time information, so sorting by id can be used as sorting by creation time.
`orderType`	Yes	`string`	None	Sort type, asc: ascending, desc: descending
`conditions`	No	`array`	None	Query conditions. When multiple are passed, the relationship is AND.
`conditions.fieldName`	No	`string`	None	Name of the query condition, e.g., realName
`conditions.fieldValue`	No	`string`	None	Value of the query condition
`conditions.conditionalType`	No	`number`	0	Comparison type: 0: exact match, 1: fuzzy match, 2: greater than, 3: greater than or equal, 4: less than, 5: less than or equal, 6: in, 7: not in, 8: left fuzzy match, 9: right fuzzy match, 10: not equal, 11: nullOrEmpty, 12: not empty, 13: notLike
`pageIndex`	Yes	`number`	None	Page number
`pageSize`	Yes	`number`	None	Number per page

Request Example:

curl --location 'http://localhost/v1/openapi/user/pageList' \
--header 'Authorization: openapi {access_token}' \
{
  "orderField": "id",
  "orderType": "desc",
  "conditions": [
    {
      "fieldName": "realName",
      "fieldValue": "张三",
      "conditionalType": 0
    }
  ],
  "pageIndex": 1,
  "pageSize": 15
}

Response body:

Field Name	Type	Description
`data`	`array`	Paginated data
`data.id`	`string`	Account ID
`data.userId`	`string`	User ID
`data.userName`	`string`	Username
`data.active`	`boolean`	Whether activated
`data.avatar`	`string`	Avatar
`data.birthday`	`string`	Birthday
`data.created`	`string`	User data creation date
`data.modified`	`string`	User data last modified date
`data.description`	`string`	Description
`data.gender`	`number`	Gender 0:FEMALE, 1:MALE
`data.mobilePhone`	`string`	Mobile phone number
`data.nickName`	`string`	Nickname
`data.email`	`string`	Email
`data.joinTime`	`string`	Date of joining
`data.region`	`string`	Region
`data.weChat`	`string`	WeChat ID
`data.spell`	`string`	Pinyin of real name
`data.serialNumber`	`string`	Employee number
`data.accountId`	`string`	Account ID to which the user belongs
`data.sort`	`number`	Sort number
`data.officePhoneNumber`	`string`	Office phone number
`data.external`	`boolean`	Internal/external user flag false: internal user, true: external user
`data.isAad`	`boolean`	Whether the account comes from AAD (Microsoft Entra ID)
`data.enable`	`boolean`	Enable/Disable
`pageIndex`	`number`	Current page number
`pageSize`	`number`	Page size
`totalCount`	`number`	Total count
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
    "data": [
        {
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "张三"
		}
    ],
    "pageSize": 15,
    "pageIndex": 1,
    "totalCount": 1,
    "success": true,
    "msg": null
}

Get User Information

Endpoint: v1/openapi/user/{userCode}
HTTP Method: get
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Route parameters:

Parameter Name	Required	Type	Default	Description
userCode	Yes	`string`	None	User ID or username

Request Example:

curl --location 'http://localhost/v1/openapi/user/123456' \
--header 'Authorization: openapi {access_token}' \

Response body:

Field Name	Type	Description
`data`	`object`	Response data object
`data.id`	`string`	Account ID
`data.userId`	`string`	User ID
`data.userName`	`string`	Username
`data.Active`	`boolean`	Whether activated
`data.Avatar`	`string`	Avatar
`data.Birthday`	`string`	Birthday
`data.Created`	`string`	User data creation date
`data.Modified`	`string`	User data last modified date
`data.Description`	`string`	Description
`data.Gender`	`number`	Gender 0:FEMALE, 1:MALE
`data.MobilePhone`	`string`	Mobile phone number
`data.NickName`	`string`	Nickname
`data.Email`	`string`	Email
`data.JoinTime`	`string`	Date of joining
`data.Region`	`string`	Region
`data.WeChat`	`string`	WeChat ID
`data.Spell`	`string`	Pinyin of real name
`data.SerialNumber`	`string`	Employee number
`data.AccountId`	`string`	Account ID to which the user belongs
`data.Sort`	`number`	Sort number
`data.OfficePhoneNumber`	`string`	Office phone number
`data.External`	`boolean`	Internal/external user flag false: internal user, true: external user
`data.IsAad`	`boolean`	Whether the account comes from AAD (Microsoft Entra ID)
`data.Enable`	`boolean`	Enable/Disable
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

json
{
	"success": true,
	"msg": "",
	"data": [
		{
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "张三"
		}
	]
}

Get Current Logged-in User Information

API Endpoint: v1/openapi/user/me
Request Method: get
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, value format: openapi `{access_token}`

Content Type: application/json
Request Example:

curl --location 'http://localhost/v1/openapi/user/me' \
--header 'Authorization: openapi {access_token}' \

Response body:

Field Name	Type	Description
`data`	`object`	Response data object
`data.id`	`string`	Account ID
`data.userId`	`string`	User ID
`data.userName`	`string`	Username
`data.Active`	`boolean`	Whether activated
`data.Avatar`	`string`	Avatar
`data.Birthday`	`string`	Birthday
`data.Created`	`string`	User data creation date
`data.Modified`	`string`	User data last modified date
`data.Description`	`string`	Description
`data.Gender`	`number`	Gender 0:FEMALE, 1:MALE
`data.MobilePhone`	`string`	Mobile phone number
`data.NickName`	`string`	Nickname
`data.Email`	`string`	Email
`data.JoinTime`	`string`	Date of joining
`data.Region`	`string`	Region
`data.WeChat`	`string`	WeChat ID
`data.Spell`	`string`	Pinyin of real name
`data.SerialNumber`	`string`	Employee number
`data.AccountId`	`string`	Account ID the user belongs to
`data.Sort`	`number`	Sort number
`data.OfficePhoneNumber`	`string`	Office phone number
`data.External`	`boolean`	Internal/external user flag false: internal user, true: external user
`data.IsAad`	`boolean`	Whether account is from AAD (Microsoft Entra ID)
`data.Enable`	`boolean`	Enable/Disable
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": "",
	"data": [
		{
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "张三"
		}
	]
}

Get Current Logged-in User Roles

API Endpoint: v1/openapi/user/roles
Request Method: get
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, value format: openapi `{access_token}`

Content Type: application/json
Request Example:

curl --location 'http://localhost/v1/openapi/user/me/roles' \
--header 'Authorization: openapi {access_token}' \

Response body:

Field Name	Type	Description
`data`	`array`	Response data object
`data.roleId`	`string`	Role ID
`data.roleName`	`string`	Role name
`data.dataPermissionList`	`array`	Data permissions for the user under this role
`data.dataPermissionList.BusinessTreeType`	`number`	Application type
`data.dataPermissionList.DataPermissionObjectId`	`string`	Data permission object ID, e.g., if it's knowledge base permission, it's the knowledge base ID
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": "",
	"data": [
		{
			"roleId": "123456",
			"roleName": "知识库访客",
			"dataPermissionList": [
                {
                    "BusinessTreeType": 1,
                    "DataPermissionObjectId": "123456"
                }
            ]
		}
	]
}

Get Roles Associated with a User

API Endpoint: v1/openapi/user/{userCode}/roles
Request Method: get
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, value format: openapi `{access_token}`

Content Type: application/json
Route Parameters:

Parameter Name	Required	Type	Default	Description
userCode	Yes	`string`	None	User ID array or username

Request Example:

curl --location 'http://localhost/v1/openapi/user/123456/roles' \
--header 'Authorization: openapi {access_token}' \

Response body:

Field Name	Type	Description
`data`	`array`	Response data object
`data.roleId`	`string`	Role ID
`data.roleName`	`string`	Role name
`data.dataPermissionList`	`array`	Data permissions for the user under this role
`data.dataPermissionList.BusinessTreeType`	`number`	Application type
`data.dataPermissionList.DataPermissionObjectId`	`string`	Data permission object ID, e.g., if it's knowledge base permission, it's the knowledge base ID
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": "",
	"data": [
		{
			"roleId": "123456",
			"roleName": "知识库访客",
			"dataPermissionList": [
                {
                    "BusinessTreeType": 1,
                    "DataPermissionObjectId": "123456"
                }
            ]
		}
	]
}

Modify User-Role Relationship

API Endpoint: v1/openapi/user/{userCode}/roles
Request Method: put
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, value format: openapi `{access_token}`

Content Type: application/json
Route Parameters:

Parameter Name	Required	Type	Default	Description
userCode	Yes	`string`	None	User ID array or username

Request body:

Parameter Name	Required	Type	Default	Description
	Yes	`array`	None	Array of role IDs or role names. The array must contain either all IDs or all names.

Request Example:

curl --location 'http://localhost/v1/openapi/user/123456/roles' \
--header 'Authorization: openapi {access_token}' \

Response body:

Field Name	Type	Description
`data`	`array`	Response data object
`data.roleId`	`string`	Role ID
`data.roleName`	`string`	Role name
`data.dataPermissionList`	`array`	Data permissions for the user under this role
`data.dataPermissionList.BusinessTreeType`	`number`	Application type
`data.dataPermissionList.DataPermissionObjectId`	`string`	Data permission object ID, e.g., if it's knowledge base permission, it's the knowledge base ID
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": "",
	"data": [
		{
			"roleId": "123456",
			"roleName": "知识库访客",
			"dataPermissionList": [
                {
                    "BusinessTreeType": 1,
                    "DataPermissionObjectId": "123456"
                }
            ]
		}
	]
}

Organization

Add Organization

API Endpoint: v1/openapi/organization
Request Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, value format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
`code`	Yes	`string`	None	Organization code, unique in the system, cannot be duplicated
`parentId`	No	`string`	None	At least one of parent organization ID or parent organization name must be filled
`parentName`	No	`string`	None	Parent organization name, at least one of parent organization ID or name must be filled
`name`	Yes	`string`	None	Name
`location`	No	`string`	None	Address
`remarks`	No	`string`	None	Remarks
`contact`	No	`string`	None	Contact information
`Info`	No	`string`	None	Organization information
`Extension`	No	`string`	None	Extension information
`IsSubsidiary`	No	`boolean`	false	Whether it is a subsidiary
`sort`	No	`number`	0	Sort number
`isEnable`	No	`boolean`	false	Enable/Disable
`external`	No	`boolean`	false	Internal/external organization flag false: internal, true: external

Request Example:

curl --location 'http://localhost/v1/openapi/organization' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "code": "123456",
    "parentId": "12345",
    "name": "组织名称",
    "location": "地址"
}  '

Response body:

Field Name	Type	Description
`data`	`object`	Response data object
`data.id`	`string`	Organization ID
`data.code`	`string`	Organization code
`data.parentId`	`string`	Parent organization ID
`data.parentName`	`string`	Whether activated
`data.name`	`string`	Name
`data.location`	`string`	Address
`data.remarks`	`string`	Remarks
`data.contact`	`string`	Contact information
`data.Info`	`string`	Organization information
`data.Extension`	`number`	Extension information
`data.IsSubsidiary`	`boolean`	Whether it is a subsidiary
`data.sort`	`number`	Sort number
`data.isEnable`	`boolean`	Enable/Disable
`data.external`	`boolean`	Internal/external organization flag
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

{
	"success": true,
	"msg": "",
	"data": [
		{
			"id": "123456",
            "code": "123456",
            "parentId": "12345",
            "name": "组织名称",
            "location": "地址"
		}
	]
}

Update Organization

API Endpoint: v1/openapi/organization
Request Method: put
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, value format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
`id`	No	`string`	None	Organization ID, at least one of id or code must be filled
`code`	No	`string`	None	Organization code, at least one of id or code must be filled
`parentId`	No	`string`	None	At least one of parent organization ID or parent organization name must be filled
`parentName`	No	`string`	None	Parent organization name, at least one of parent organization ID or name must be filled
`name`	Yes	`string`	None	Name
`location`	No	`string`	None	Address
`remarks`	No	`string`	None	Remarks
`contact`	No	`string`	None	Contact information
`Info`	No	`string`	None	Organization information
`Extension`	No	`string`	None	Extension information
`IsSubsidiary`	No	`boolean`	false	Whether it is a subsidiary
`sort`	No	`number`	0	Sort number
`isEnable`	No	`boolean`	false	Enable/Disable
`external`	No	`boolean`	false	Internal/external organization flag false: internal, true: external

Request Example:

shell
curl --location 'http://localhost/v1/openapi/organization' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "code": "123456",
    "parentId": "12345",
    "name": "Organization Name",
    "location": "Address"
}  '

Response body:

Field Name	Type	Description
`data`	`object`	Response data object
`data.id`	`string`	Organization ID
`data.code`	`string`	Organization code
`data.parentId`	`string`	Parent organization ID
`data.parentName`	`string`	Is activated
`data.name`	`string`	Name
`data.location`	`string`	Address
`data.remarks`	`string`	Remarks
`data.contact`	`string`	Contact information
`data.Info`	`string`	Organization information
`data.Extension`	`number`	Extension information
`data.IsSubsidiary`	`boolean`	Is subsidiary
`data.sort`	`number`	Sort number
`data.isEnable`	`boolean`	Enable/Disable
`data.external`	`boolean`	Internal/External organization flag
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response example:

{
	"success": true,
	"msg": "",
	"data": [
		{
			"id": "123456",
            "code": "123456",
            "parentId": "12345",
            "name": "Organization Name",
            "location": "Address"
		}
	]
}

Delete Organization

Endpoint: v1/openapi/organization
HTTP Method: delete
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
	Yes	`array`	None	Array of organization IDs or organization names. The array must contain either all IDs or all names.

Request example:

curl --location 'http://localhost/v1/openapi/organization' \
--header 'Authorization: openapi {access_token}' \
--data '['org1','org2']'

Response body:

Field Name	Type	Description
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response example:

{
	"success": true,
	"msg": ""
}

Get Tree Organization Structure

Endpoint: v1/openapi/organization/tree
HTTP Method: get
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request query:

Parameter Name	Required	Type	Default	Description
`external`	No	`boolean`	false	Whether external organization

Request example:

curl --location 'http://localhost/v1/openapi/organization/tree' \
--header 'Authorization: openapi {access_token}' \

Response body:

Field Name	Type	Description
`data`	`array`	Response data object
`data.nodeId`	`string`	Organization ID
`data.nodeName`	`string`	Organization name
`data.parentNodeId`	`string`	Parent organization ID
`data.code`	`string`	Organization code
`data.path`	`string`	Path from root node to current node -- IDs separated by '/'
`data.external`	`boolean`	Internal/External organization flag
`data.childNodeList`	`array`	Child organizations
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response example:

{
	"success": true,
	"msg": "",
	"data": [
        {
            "isExternal": false,
            "sort": 1,
            "nodeId": "4034994050380595200",
            "nodeName": "Internal Organization",
            "path": "4034994050380595200/4419926899526991872",
            "parentNodeId": "-1",
            "childNodeList": [
                {
                    "isExternal": false,
                    "sort": 1,
                    "nodeId": "4419926899526991872",
                    "nodeName": "IT",
                    "path": "4034994050380595200/4419926899526991872",
                    "parentNodeId": "4034994050380595200",
                }
            ]
        }
    ]
}

Get Users by Organization Relationship (Paginated)

Endpoint: v1/openapi/organization/getAllOrgUserPageList
HTTP Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
`orderField`	Yes	`string`	None	Field for sorting. ID contains time info, so sorting by ID can be used as creation time sorting
`orderType`	Yes	`string`	None	Sort type, asc: ascending, desc: descending
`conditions`	No	`array`	None	Query conditions, multiple conditions are combined with AND
`conditions.fieldName`	No	`string`	None	Name of the query condition, e.g. organizationId
`conditions.fieldValue`	No	`string`	None	Value of the query condition
`conditions.conditionalType`	No	`number`	0	Comparison type: 0: exact match, 1: fuzzy match, 2: greater than, 3: greater or equal, 4: less than, 5: less or equal, 6: in, 7: not in, 8: left fuzzy match, 9: right fuzzy match, 10: not equal, 11: nullOrEmpty, 12: not empty, 13: notLike
`pageIndex`	Yes	`number`	None	Page number
`pageSize`	Yes	`number`	None	Number per page

Request example:

curl --location 'http://localhost/v1/openapi/organization/getAllOrgUserPageList' \
--header 'Authorization: openapi {access_token}' \
{
  "orderField": "id",
  "orderType": "desc",
  "conditions": [
    {
      "fieldName": "organizationName",
      "fieldValue": "123456",
      "conditionalType": 0
    }
  ],
  "pageIndex": 1,
  "pageSize": 15
}

Response body:

Field Name	Type	Description
`data`	`array`	Paginated data
`data.userId`	`string`	User ID
`data.account`	`string`	Username
`data.accountId`	`boolean`	Account ID
`data.realName`	`string`	Real name
`data.organizationName`	`string`	Organization name
`data.organizationId`	`string`	Organization ID
`data.organizationParentId`	`string`	Parent organization ID
`data.Email`	`string`	Email
`data.Sort`	`number`	Sort number
`data.External`	`boolean`	Internal/External user flag false: internal user, true: external user
`pageIndex`	`number`	Current page number
`pageSize`	`number`	Page size
`totalCount`	`number`	Total count
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response example:

{
    "data": [
        {
            "account": "user1",
            "accountId": "123456",
            "userId": "123456",
            "realName": "user1",
            "organizationName": "org1",
            "organizationId": "123456",
            "external": false,
            "organizationParentId": "12345",
            "sort": 1,
            "email": ""
        }
    ],
    "pageSize": 15,
    "pageIndex": 1,
    "totalCount": 1,
    "success": true,
    "msg": null
}

Add User-Organization Relationship

Endpoint: v1/openapi/organization/relationship
HTTP Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
`organizationId`	Yes	`string`	None	Organization ID
`userId`	Yes	`string`	None	User ID
`sort`	No	`number`	0	Sort number

Request example:

curl --location 'http://localhost/v1/openapi/organization/relationship' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "organizationId": "123456",
    "userId": "12345"
}  '

Response body:

Field Name	Type	Description
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response example:

{
	"success": true,
	"msg": ""
}

Delete User-Organization Relationship

Endpoint: v1/openapi/organization/relationship
HTTP Method: delete
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
`organizationIds`	Yes	`array`	None	Organization IDs
`userIds`	Yes	`array`	None	User IDs

Request example:

curl --location 'http://localhost/v1/openapi/organization/relationship' \
--header 'Authorization: openapi {access_token}' \
--data '{  
    "organizationIds": ["123456"],
    "userIds": ["12345"]
}  '

Response body:

Field Name	Type	Description
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response example:

{
	"success": true,
	"msg": ""
}

Query Users under Organization (Paginated)

Endpoint: v1/openapi/organization/getUserPages
HTTP Method: post
Request header:

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in SERVICEME access token, format: openapi `{access_token}`

Content Type: application/json
Request body:

Parameter Name	Required	Type	Default	Description
`orderField`	Yes	`string`	None	Field for sorting. ID contains time info, so sorting by ID can be used as creation time sorting
`orderType`	Yes	`string`	None	Sort type, asc: ascending, desc: descending
`conditions`	No	`array`	None	Query conditions, multiple conditions are combined with AND
`conditions.fieldName`	No	`string`	None	Name of the query condition, must provide at least OrganizationId or OrganizationCode as filter condition
`conditions.fieldValue`	No	`string`	None	Value of the query condition
`conditions.conditionalType`	No	`number`	0	Comparison type: 0: exact match, 1: fuzzy match, 2: greater than, 3: greater or equal, 4: less than, 5: less or equal, 6: in, 7: not in, 8: left fuzzy match, 9: right fuzzy match, 10: not equal, 11: nullOrEmpty, 12: not empty, 13: notLike
`pageIndex`	Yes	`number`	None	Page number
`pageSize`	Yes	`number`	None	Number per page

Request example:

shell
curl --location 'http://localhost/v1/openapi/user/pageList' \
--header 'Authorization: openapi {access_token}' \
{
  "orderField": "id",
  "orderType": "desc",
  "conditions": [
    {
      "fieldName": "OrganizationCode",
      "fieldValue": "org1",
      "conditionalType": 0
    }
  ],
  "pageIndex": 1,
  "pageSize": 15
}

Response body:

Field Name	Type	Description
`data`	`array`	Paginated data
`data.id`	`string`	User ID
`data.account`	`string`	Username
`data.name`	`string`	Real name
`data.ownerMainDepartment`	`string`	User's main department
`data.sort`	`number`	Sort number
`data.status`	`boolean`	User enabled status
`data.create`	`datetime`	User creation time
`pageIndex`	`number`	Current page number
`pageSize`	`number`	Page size
`totalCount`	`number`	Total count
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response example:

{
    "data": [
        {
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "张三"
		}
    ],
    "pageSize": 15,
    "pageIndex": 1,
    "totalCount": 1,
    "success": true,
    "msg": null
}

Overview​

Authentication Methods​

User AAD Authentication​

Client and User Account Authentication​

Chat​

Send Message to Agent​

Get References for a Conversation​

File Workspace​

Single File Upload​

Batch File Upload​

Submit Files​

Query Upload Result​

QnA Creation​

Query Files​

Query File Fragments​

RAG​

User​

Add User (Batch Supported)​

Update User​

Delete User​

Enable User​

Disable User​

Enable/Disable Users (Batch Supported)​

Get User List (Paginated)​

Get User Information​

Get Current Logged-in User Information​

Get Current Logged-in User Roles​

Get Roles Associated with a User​

Modify User-Role Relationship​

Organization​

Add Organization​

Update Organization​

Delete Organization​

Get Tree Organization Structure​

Get Users by Organization Relationship (Paginated)​

Add User-Organization Relationship​

Delete User-Organization Relationship​

Query Users under Organization (Paginated)​