Open API

Overview

The basic process for calling the SERVICEME Open API:

Step 1: Use the interface provided in the Authentication section to obtain an access token

Authentication is divided into two types: user authentication and client authentication.

User authentication: Authentication based on an individual 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 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. User account authentication is performed, and at the same time, client credentials (client id and secret) are 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, you can obtain the client id and secret.

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 colon then MD5 `client:{client}secret:{secret}account:{account}timestamp:{timestamp}nonce:{nonce}`; the resulting 32-character MD5 value in lowercase)

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 SERVICEME access token, format: openapi `{access_token}`

Request body:

Parameter Name	Required	Type	Description
expertCode	Yes	string	Agent code in 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, and the new session id will be returned in the response. From the second Q&A onwards, you need to carry the session id returned last time 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: not include)
language	No	object	Language for this chat
language.chatLanguage	No	string	The language you want AI to reply in. If empty, AI will decide automatically
language.systemLanguage	No	string	The base language of the session, affects plugin names, prompts, etc., but does not affect AI's reply. Defaults to en-US if empty. If chatLanguage is provided, it will override systemLanguage.

How to get 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,
    "language": { "chatLanguage" : null, "systemLanguage" :  "zh-CN"}
}'

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 answer
	medias			object	Array of media type answers (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 info
			model	float	Model elapsed time
			action	float	Action elapsed time
			total	float	Total elapsed time
		state		string	State (success: success)
	finish_reason			string	Whether the answer is finished. When value is stop, it means finished; during answering, value is null
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 publishes 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 the overtime hours in the time system, submit the overtime process in the system, and the remarks must clearly state the overtime task. Complete clock-in and clock-out records must be kept at the workplace. The team leader/supervisor approves the overtime application process after accepting the overtime results. HR confirms the clock-in records and calculates the compensatory leave quota.",
        "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 search for 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 search for 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 publishes 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 the overtime hours in the time system, submit the overtime process in the system, and the remarks must clearly state the overtime task. Complete clock-in and clock-out records must be kept at the workplace. The team leader/supervisor approves the overtime application process after accepting the overtime results. HR confirms the clock-in records and calculates the compensatory leave quota.","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 the Conversation

API Endpoint: /openapi/chat/record/{chatRecordId}/reference
Request Method: get
Request header:

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

Request URL Parameters:

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

Request Example:

shell
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 conversation record
	score	float	Relevance (0 to 1, the closer to 1 the more relevant)
	url	string	Link (currently only references of file type have links)
	type	string	Type enum: document, image, QnA, other
success		boolean	Whether the request was successful
msg		string	When success is false, this field contains error messages

Response example:

{
    "data": [
        {
            "title": "公司行政制度.pdf",
            "content": "片段一 ......",
            "score": 0.95,
            "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
            "type": "document"
        },
        {
            "title": "公司行政制度.pdf",
            "content": "片段二 ......",
            "score": 0.81,
            "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
            "type": "document"
        },
        {
            "title": "公司行政制度.pdf",
            "content": "片段三 ......",
            "score": 0.76,
            "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
            "type": "document"
        }
    ],
    "success": true,
    "msg": ""
}

Bot API

Create Bot API

Basic Information

Request Method: POST
Endpoint: /openapi

Request Parameters

Name	Type	Description
code	String	Bot code, unique, max length 50
cover	String	Cover image path (optional)
names	Array(TranslationInfo)	Name in multiple languages, required; each element contains: `languageCode`, `content`
welcomes	Array(TranslationInfo)	Welcome message in multiple languages; each element contains: `languageCode`, `content` (length limited by system)
descriptions	Array(TranslationInfo)	Description in multiple languages; same structure as above
historyRecordNumber	Number	Maximum number of historical messages
feedback	Boolean	Enable feedback or not
recoreChat	Boolean	Record conversations or not
useSuggestedQuestions	Boolean	Enable suggested questions or not
useKnowledgeBase	Boolean	Enable knowledge base or not
sort	Number	Sort order
chatModelId	Number(Int64)	Chat model ID
chatPrompt	String	Chat system prompt
temperature	Number	Temperature coefficient (0~2)
topP	Number	TopP (0~1)
tools	Array(BotPluginToolVO)	List of bot tools (each item must contain at least `id` = plugin ID)
knowledgeInfo	Object(BotKnowledgeVO)	Knowledge base configuration, e.g. `workspaces`: Array(Int64) list of workspace IDs
dataSources	Array(String)	Data source identifiers

Request parameter example (Body):

{
  "code": "qa-bot",
  "cover": "/images/bots/qa.png",
  "names": [
    { "languageCode": "zh-CN", "content": "问答机器人" },
    { "languageCode": "en-US", "content": "Q&A Bot" }
  ],
  "welcomes": [
    { "languageCode": "zh-CN", "content": "您好！我可以帮您解答问题。" },
    { "languageCode": "en-US", "content": "Hi! I can help answer your questions." }
  ],
  "descriptions": [
    { "languageCode": "zh-CN", "content": "用于通用问答的机器人" },
    { "languageCode": "en-US", "content": "A bot for general Q&A" }
  ],
  "historyRecordNumber": 10,
  "feedback": true,
  "recoreChat": true,
  "useSuggestedQuestions": false,
  "useKnowledgeBase": true,
  "sort": 1,
  "chatModelId": 4493000000000000001,
  "chatPrompt": "你是一个专业助手，请用简体中文回答用户问题。",
  "temperature": 0.7,
  "topP": 0.95,
  "tools": [
    { "id": 4488000000000001001 },
    { "id": 4488000000000001002 }
  ],
  "knowledgeInfo": {
    "workspaces": [4493061452348784640, 4493061452348784641]
  },
  "dataSources": ["kb", "faq"]
}

cURL example:

curl -X POST "https://<host>/openapi" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer <token>" ^
  -d "{ \"code\": \"qa-bot\", \"names\": [ { \"languageCode\": \"zh-CN\", \"content\": \"问答机器人\" } ], \"welcomes\": [ { \"languageCode\": \"zh-CN\", \"content\": \"您好！\" } ], \"descriptions\": [ { \"languageCode\": \"zh-CN\", \"content\": \"用于通用问答的机器人\" } ], \"historyRecordNumber\": 10, \"feedback\": true, \"recoreChat\": true, \"useSuggestedQuestions\": false, \"useKnowledgeBase\": true, \"sort\": 1, \"chatModelId\": 4493000000000000001, \"chatPrompt\": \"你是一个专业助手。\", \"temperature\": 0.7, \"topP\": 0.95, \"tools\": [ { \"id\": 4488000000000001001 } ], \"knowledgeInfo\": { \"workspaces\": [4493061452348784640] }, \"dataSources\": [\"kb\"] }"

Note:

code must be globally unique; duplicates will return an error.

Return Values

Name	Type	Description
data	String	Newly created bot ID
success	Boolean	API call result (true = success, false = failure)
msg	String	Message

Return example:

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

## File Space

### Single File Upload

- **Endpoint:** ```v1/openapi/workspace/file/upload```

- **Request Method:** ```post```

- **Request header:**

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

- **Content Type:** ```form-data```
- **Request body:**

| Parameter Name   | Required | Type   | Description                                         |
| ---------------- | -------- | ------ | --------------------------------------------------- |
| workspace        | Yes      | string | File space                                          |
| 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:**

```shell
curl --location 'http://localhost/v1/openapi/workspace/file/upload' \
--header 'Authorization: openapi {access_token}' \
--form '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 the request was successful
msg		string	When success is false, this field contains error messages

Response example:

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

File Space

Multiple File Upload

Submit Files

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

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

Content Type: form-data
Request body:

Parameter Name	Required	Type	Description
workspace	Yes	string	File space
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="测试空间"' \
--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, you can use this state id to poll for the latest upload result
success		boolean	Whether the request was successful
msg		string	When success is false, this field contains error messages

Response example:

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

Query Upload Result

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

Parameter Name	Required	Type	Description
Authorization	Yes	string	Fill in 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 multi-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, success, fail
	uploader	string	Uploader
	errorMsg	string	If state is fail, this field contains the reason for failure
	finishTime	string	Time when file processing was completed
success		boolean	Whether the request was successful
msg		string	When 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

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

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

Request body:

Parameter Name	Sub-Parameter	Required	Type	Description
workspace		Yes	string	File space
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": [
        "测试问题"
    ],
    "answer": "测试答案",
    "workspace": "测试空间",
    "metadatas": [
        {
            "typeCode": "Document type",
            "content": "测试元数据"
        }
    ]
}'

Response body:

Parameter Name	Type	Description
success	boolean	Whether the request was successful
msg	string	When success is false, this field contains error messages

Response example:

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

Query Files

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

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

Request body:

Parameter Name	Required	Type	Description
workspace	Yes	string	File space
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": "测试空间",
    "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 content
	chunkingState		string	File index state: waiting, success, fail, underway
	previewState		string	File preview state: waiting, success, fail, underway
	fileCanPreview		boolean	Whether the file can be previewed, true: yes; false: no
	previewUrl		string	File preview URL
	createdByRealName		string	File creator's name
	createdByAccount		string	File creator's account
	created		datetime	File creation time
	modifiedByRealName		string	File editor's name
	modifiedByAccount		string	File editor's account
	modified		datetime	File modification time
success			boolean	Whether the request was successful
msg			string	When success is false, this field contains error messages

Response example:

json
{
    "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 Chunks

Endpoint: v1/openapi/workspace/file/chunk
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	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 the first page
pageSize	No	number	Number to fetch, 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	Level 2	Type	Description
data		object array	Response data
	id	string	Chunk id
	content	string	Chunk content
success		boolean	Whether successful
msg		string	When success is false, this field has value and contains error messages

Response Example:

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

Download File as Markdown API

Basic Information

HTTP Method: POST
Endpoint: /v1/openapi/workspace/file/downloadDocument2MD

Request Parameters

Parameter Name	Type	Location	Required	Description
id	Number(Int64)	Body	Yes	File ID to be converted to Markdown

Request Body Example (JSON):

{
  "id": 4493061452348784640
}

cURL Example:

curl -X POST "https://<host>/v1/openapi/DownloadDocument2MD" ^
  -H "Authorization: <token>" ^
  -H "Content-Type: application/json" ^
  --data-raw "{\"id\":4493061452348784640}"

Return Value

Type: File stream (FileContentResult), downloaded as an attachment
File Name: Original file name with extension replaced by .md
Content-Type: application/octet-stream

Return Example (Key HTTP Response Headers):

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="SampleDocument.md"

RAG

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 search. Cannot both be `null` with Keywords.
`keywords`	`string`	No	None	Keywords, separated by `\|`. Cannot both be `null` with Query. If `null`, keywords will be extracted as needed; if not empty, the passed keywords are used directly.
`workspaces`	`array`	No	None	The workspace names or IDs to search in this RAG. If provided, only these workspaces will be searched.
`ragObject`	`RagObject`	Yes	`0`	RAG object type, enum value (see RagObject Enum). QNA search not supported yet.
`topk`	`number`	Yes	None	Number of results to return.
`minSimilarity`	`double`	No	`0.8`	Minimum similarity, range `[0, 1]`.
`metadataProvider`	`array`	No	None	Metadata to use. Currently only supports ["default"]
`metadataSearchType`	`number`	No	`0`	How to use metadata in search, only effective if metadataProvider is enabled. 0: filter mode, 1: weighted sort mode
`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` is not used.

Request Example:

curl --location 'http://localhost/v1/openapi/rag' \
--header 'Authorization: ••••••' \
--header 'Content-Type: application/json' \
--data '{  
    "query": "What is Artificial Intelligence?",  
    "keywords": "AI|Machine Learning",  
    "workspaces": ["workspace1", "workspace2"],  
    "ragObject": 0,  
    "topk": 3,  
    "minSimilarity": 0.8,  
    "metadataProvider": ["default"],  
    "metadataSearchType": 1,
    "ragMode": 1,  
    "weights": {  
        "Embedding": 0.9,  
        "FullText": 0.8  
    },  
    "reranker": "default"  
}  '

Response body:

Field Name	Type	Description
`data`	`object`	Response data object, contains search results and search ID, etc.
`data.results`	`array`	Search result list, 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": "file1.pdf",
                "content": "……",
                "metadata": {
                    "Url": "https://……",
                    "FileName": "file1.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": "file1.pdf",
                "content": "……",
                "metadata": {
                    "Url": "https://……",
                    "FileName": "file1.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": "file1.pdf",
                "content": "……",
                "metadata": {
                    "Url": "……",
                    "FileName": "file1.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 (QA not supported yet, even if selected, no results will be returned)

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

SearchMode Enum

Enum Value	Enum Number	Description
`Hybrid`	1	Hybrid search mode, combines 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 Example configuration for cohere-rerank-v3.5 model:

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 using Cohere official API, the value of the Token field is bearer token. If using Azure AI Foundry API, the value of the Token field should remove bearer.

Workspace List API

Basic Information

HTTP Method: GET
Endpoint: /v1/openapi/workspace/all

Request Parameters

None

Return Value

Parameter Name	Type	Description
data	Array	Category list; each item contains category info and its workspace list
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually empty string on success)

data Array Item Structure: Category (WorkspaceCategory)

Parameter Name	Type	Description
id	Number	Category Id
name	String	Category Name
icon	String	Icon
workspaces	Array	Workspace list under this category (see below)

data[n].workspaces Array Item Structure: Workspace (WorkspaceInfo)

Parameter Name	Type	Description
id	String	Workspace Id
name	String	Workspace Name
description	String	Workspace Description
operationKeys	Array(String)	Operation permission list
fileCount	Number	Number of files (statistic)

Return Value Example:

{
  "data": [
    {
      "id": 4493041505002323001,
      "name": "Video Materials",
      "icon": "icon-video",
      "workspaces": [
        {
          "id": "4493061452348784640",
          "name": "Promo Video Materials",
          "description": "Used to store promo video materials",
          "operationKeys": ["read", "write"],
          "fileCount": 128
        },
        {
          "id": "4493061452348784641",
          "name": "Meeting Recordings",
          "description": "Internal meeting recording files",
          "operationKeys": ["read"],
          "fileCount": 57
        }
      ]
    },
    {
      "id": 4493041505002323002,
      "name": "Document Materials",
      "icon": "icon-doc",
      "workspaces": [
        {
          "id": "4493061452348784700",
          "name": "Product Manual",
          "description": "Product documentation for external release",
          "operationKeys": [],
          "fileCount": 342
        }
      ]
    }
  ],
  "success": true,
  "msg": ""
}

Workspace Creation API

Basic Information

HTTP Method: POST
Endpoint: /v1/openapi/workspace/create

Request Parameters

Parameter Name	Type	Description	Required
name	String	Workspace name (example: "Test Workspace")	Yes
workspaceTypeId	String	Workspace type ID (example: "4493041505002323969")	Yes
classificationId	String	Category ID (example: "4035265396658405376")	Yes
description	String	Workspace description (example: "Test Workspace")	Yes
quota	Number	Quota (example: 1)
fileSize	Number	File size limit (example: 1)
fileTypes	Array	Supported file types list (example: [".mov", ".mp4", ".mpeg"] )
enable	Boolean	Whether enabled (true = enabled, false = disabled)
operationKeys	Array	Operation permission list (example: empty array)
notice	String	Workspace notice (example: "Test Workspace")
settings	String	Workspace settings (JSON string format, includes mode, file size, supported types, etc.)

Note:

For the settings field description, see [File Preprocessing and Configuration Parameter Description] below.
For the metadataTemplate field description, see [Metadata Parameter Description] below.

Request Parameter Example:

{
   "name": "Test Workspace",
   "workspaceTypeId": "4493041505002323969",
   "classificationId": "4035265396658405376",
   "description": "Test Workspace",
   "quota": 1,
   "fileSize": 1,
   "fileTypes": [".mov", ".mp4", ".mpeg"],
   "enable": true,
   "operationKeys": [],
   "notice": "Test Workspace",
   "settings": "{\"setting\":{\"mode\":\"default\",\"identifier\":\"\",\"maxLength\":1024,\"overlap\":0},\"status\":null,\"fileSize\":1,\"fileTypes\":[\".mov\",\".mp4\",\".mpeg\"]}"
}

Return Value

Parameter Name	Type	Description
data	String	ID of the newly added file workspace (example: "4493061452348784640")
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Value Example:

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

File Workspace Edit API

Basic Information

Request Method: POST
API Endpoint: /v1/openapi/workspace/update

Request Parameters

Parameter Name	Type	Description	Required
id	String	ID of the file workspace to edit (example: "4437336392049102848")	Yes
workspaceTypeId	String	File workspace type ID (example: "4437336252408139777")	Yes
workspaceTypeName	String	File workspace type name (example: "Test Workspace")	Yes
name	String	Workspace name (example: "Test Workspace")	Yes
enable	Boolean	Whether to enable (true = enabled, false = disabled)
notice	String	Workspace notice (example: "Final Test")
description	String	Workspace description (example: "Final Test")	Yes
classificationId	String	Classification ID (example: "4035265396658405376")	Yes
quota	Number/Null	Quota (can be null, means no change)
quotaUsage	Number	Used quota (example: 50815916)
settings	String	Workspace configuration (JSON string, includes mode, OCR, summary, etc.)
metadataTemplate	String	Metadata template

Note:

For details on the settings field, see [File Preprocessing and Configuration Parameter Description] below.
For details on the metadataTemplate field, see [Metadata Parameter Description] below.

Request Parameter Example:

{
   "id": "4437336392049102848",
   "workspaceTypeId": "4437336252408139777",
   "workspaceTypeName": "Test Workspace",
   "name": "Test Workspace",
   "enable": true,
   "notice": "Final Test",
   "description": "Final Test",
   "classificationId": "4035265396658405376",
   "quota": null,
   "quotaUsage": 50815916,
   "settings": "{\"setting\":{\"mode\":\"refine\",\"identifier\":\"\",\"maxLength\":1024,\"overlap\":0,\"previewEnable\":true,\"enable\":true,\"documentOCR\":false,\"summaryEnable\":true,\"imageRecognize\":false,\"ocrMode\":\"layout\",\"summaryPrompt\":\"### Summarize the following in the original language in no more than 200 words.\"},\"status\":null,\"fileSize\":null,\"fileTypes\":[\".md\"],\"useWorkspaceSetting\":true}",
   "metadataTemplate": "[{\"name\":\"Test\",\"type\":0}]"
}

Return Value

Parameter Name	Type	Description
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Value Example:

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

File Workspace Delete API

Basic Information

Request Method: DELETE
API Endpoint: /v1/openapi/workspace/delete

Request Parameters

Parameter Name	Type	Location	Description
ids	Array(Number)	Query or Body	List of file workspace IDs to delete, supports batch

Request Example:

[
  4493061452348784640,
  4493061452348784641
]

Return Value

Parameter Name	Type	Description
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Value Example:

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

File Preprocessing and Configuration Parameter Description

This JSON structure is used to define preprocessing rules, segmentation modes, and feature switches for files in the workspace. It is usually the core content of the settings field (corresponding to the settings parameter in the file workspace add/edit APIs). The following are detailed descriptions of each parameter:

1. Core Configuration Object: `setting`

Parameter Name	Type	Value Description	Remarks
`mode`	String	Optional values: - `default`: default segmentation mode - `refine`: refined segmentation mode	Controls file content segmentation strategy; refined mode splits content more finely
`maxLength`	Number	Numeric (example: 1024)	Effective only under custom segmentation model; defines max length per segment, default is 1024
`overlap`	Number	Numeric (example: 0)	Overlapping text length between segments to avoid content breakage; 0 means no overlap
`previewEnable`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether to enable file preview; when enabled, users can view part of the content without opening the file
`enable`	Boolean	`true` (enabled) / `false` (disabled)	Master switch, controls whether to enable file preprocessing (includes OCR, summary generation, etc.)
`documentOCR`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether to perform OCR on documents; suitable for image format docs or docs containing images; when enabled, text in images can be extracted
`ocrMode`	String	Optional values: - `read`: read mode (extracts text only) - `layout`: layout mode (retains text layout structure, such as paragraphs, table positions)	Effective only when `documentOCR` is `true`; defines OCR accuracy and output format
`summaryEnable`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether to auto-generate document summary; when enabled, summary is generated according to `summaryPrompt`
`imageRecognize`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether to recognize image elements in the document; when enabled, basic analysis of image content (such as image type, key info) is performed
`summaryPrompt`	String	Text string (example: `"### Summarize the following in the original language in no more than 200 words."`)	Custom rule for full-text summary generation; supports markdown format; guides AI to generate summary as required
`formulas`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether to recognize formulas in the document (e.g., math formulas, chemical equations); when enabled, original formula format is extracted and retained
`screenshots_by_page`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether to generate screenshots by document page; when enabled, a screenshot is generated for each page for quick preview of page layout

2. Global Configuration Switch: `useWorkspaceSetting`

Parameter Name	Type	Value Description	Remarks
`useWorkspaceSetting`	Boolean	`true` (follow) / `false` (custom)	Controls whether the current file's configuration follows the global configuration of the Workspace it belongs to: - `true`: file uses Workspace's default configuration, ignores custom rules in current `setting` - `false`: file uses custom configuration in current `setting`, overrides Workspace's default rules

Complete JSON Example

{
	"setting": {
		"mode": "refine", // Segmentation mode, default: default, refine: refined
		"maxLength": 1024, // For custom segmentation model, default 1024
		"overlap": 0, // Overlapping text length between segments
		"previewEnable": true, // Enable file preview
		"enable": true, // Enable preprocessing
		"documentOCR": true, // Enable OCR
		"ocrMode": "layout", // OCR mode, read: read, layout: layout
		"summaryEnable": true, // Enable document summary generation
		"imageRecognize": true, // Recognize images in document
		"summaryPrompt": "### Summarize the following in the original language in no more than 200 words.", // Custom full-text summary prompt
		"formulas": false, // Formula recognition
		"screenshots_by_page": false // Screenshot by page
	},
	"useWorkspaceSetting": true // Whether file settings follow Workspace settings
}

Metadata Parameter Description

Metadata accepts a JSON string as the parameter value.

1. Core Configuration Object: `setting`

Parameter Name	Type	Value Description
`name`	String	Metadata name
`type`	Number	0: text type; 1: option type
`limit`	String	Each option

Complete JSON Example

{
	"metadataTemplate": "[{\"name\":\"Test\",\"type\":0},{\"name\":\"Test2\",\"type\":1,\"limit\":\"[\\\"Option1\\\",\\\"Option2\\\"]\"}]"
}

Physical Delete File API

Basic Information

Request Method: DELETE
API Endpoint: /v1/openapi/workspace/file/deleteFilePhysically

Request Parameters

Parameter Name	Type	Location	Required	Description
id	Number(Int64)	Query	Yes	File ID to be physically deleted

Request Parameter Example (Query):

/v1/openapi/workspace/file/deleteFilePhysically?id=4493061452348784640

cURL Example:

curl -X DELETE "https://<host>/v1/openapi/workspace/file/deleteFilePhysically?id=4493061452348784640" ^
  -H "Authorization: Bearer <token>"

Return Value

Parameter Name	Type	Description
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Example:

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

Behavior Description

Physical deletion is irreversible. Please use with caution.
If the specified ID does not exist or you do not have permission, the call will fail.

Edit File Metadata API

Basic Information

Request Method: PUT
API Endpoint: /v1/openapi/workspace/file/metadataExpansionEdit

Request Parameters

Parameter Name	Type	Location	Required	Description
id	Number(Int64)	Body	Yes	File ID to edit
metadataTemplate	String	Body	No	Extended metadata JSON string; if empty or omitted, extended metadata will be cleared. Recommended structure example: `[{"name":"Document type","type":0,"value":"Contract"}]`

Request Body Example (JSON):

{
  "id": 4493061452348784640,
  "metadataTemplate": "[{\"name\":\"Document type\",\"type\":0,\"value\":\"Contract\"},{\"name\":\"Department\",\"type\":0,\"value\":\"Sales Department\"}]"
}

cURL Example:

curl -X PUT "https://<host>/v1/openapi/workspace/file/metadataExpansionEdit" ^
  -H "Authorization: Bearer <token>" ^
  -H "Content-Type: application/json" ^
  --data-raw "{\"id\":4493061452348784640,\"metadataTemplate\":\"[{\\\"name\\\":\\\"Document type\\\",\\\"type\\\":0,\\\"value\\\":\\\"Contract\\\"},{\\\"name\\\":\\\"Department\\\",\\\"type\\\":0,\\\"value\\\":\\\"Sales Department\\\"}]\"}"

Return Value

Parameter Name	Type	Description
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Example:

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

Behavior Description

Updates the file's extended metadata (MetadataExpansion) according to the input, and rebuilds the doc_metadata index to make the changes effective in retrieval.
If the specified ID does not exist or you do not have permission, the call will fail.

File List API

Basic Information

Request Method: POST
API Endpoint: /v1/openapi/workspace/file

Request Parameters

Parameter Name	Type	Location	Required	Description
workspace	String	Body	Yes	File workspace name
pageIndex	Number(Int32)	Body	No	Page number, default `1`
pageSize	Number(Int32)	Body	No	Items per page, default `10`

Request Body Example (JSON):

{
  "workspace": "Public Resource Library",
  "pageIndex": 1,
  "pageSize": 10
}

cURL Example:

curl -X POST "https://<host>/v1/openapi/workspace/file" ^
  -H "Authorization: Bearer <token>" ^
  -H "Content-Type: application/json" ^
  --data-raw "{\"workspace\":\"Public Resource Library\",\"pageIndex\":1,\"pageSize\":10}"

Return Value

Parameter Name	Type	Description
pageIndex	Number	Current page number
pageSize	Number	Items per page
totalCount	Number	Total count (may return 0 or -1 for unknown/incremental, client may handle)
data	Array<File>	List of file data, see below for "File Item Field Description"

File Item Field Description (example, actual fields may vary by system version):

Field Name	Type	Description
id	Number	File ID
fileName	String	File name
previewUrl	String	File preview URL (returned if system is configured with preview URL template)
fileCanPreview	Boolean	Whether file can be previewed (calculated by backend preview status)
previewState	String	Preview state: `waiting` / `underway` / `success` / `fail`
chunkingState	String	Chunking state: `waiting` / `underway` / `success` / `fail`
modified	String	Last modified time (ISO format, e.g. `2024-01-01T12:00:00Z`)

Return Example:

{
  "pageIndex": 1,
  "pageSize": 10,
  "totalCount": 125,
  "data": [
    {
      "id": 4493061452348784640,
      "fileName": "Sample Document.docx",
      "previewUrl": "https://<host>/preview/file/4493061452348784640",
      "fileCanPreview": true,
      "previewState": "success",
      "chunkingState": "underway",
      "modified": "2024-07-01T09:30:15Z"
    }
  ]
}

Behavior Description

Only returns "files" (not folders).
Default sorting is by Modified field in descending order, supports paginated queries.
Only queries files within the specified workspace; the caller must have access to the workspace; non-admins also need appropriate authorization.
If the system is configured with a file preview URL template, previewUrl will be returned; otherwise, this field is empty or omitted.
The enum values for previewState and chunkingState are waiting / underway / success / fail.
If pageIndex / pageSize are not provided, default values 1 / 10 will be used.

File Workspace Types

Add File Workspace Type API

Basic Information

Request Method: POST
API Endpoint: /v1/openapi/workspaceType

Request Parameters

Parameter Name	Type	Description	Required
code	String	File workspace type code	Yes
title	Array	Multilingual title list, each element contains: - `languageCode`: language code (e.g. ja-JP, zh-CN, en-US) - `content`: title content in the corresponding language	Yes
icon	String	Icon path (example: `/icons/01842830fc1348edacf68edd2695614a.png`)	Yes
sort	Number	Sort order (example: 1)	Yes
description	String	Type description	Yes

Request Parameter Example (Body):

{
  "code": "File Workspace Type Code",
  "title": [
    { "languageCode": "zh-CN", "content": "Multilingual" },
    { "languageCode": "en-US", "content": "Test Add" }
  ],
  "icon": "/icons/01842830fc1348edacf68edd2695614a.png",
  "sort": 1,
  "description": "Description"
}

cURL Example:

curl -X POST "https://<host>/v1/openapi/workspaceType" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer <token>" ^
  -d "{ \"code\": \"File Workspace Type Code\", \"title\": [ { \"languageCode\": \"zh-CN\", \"content\": \"Multilingual\" } ], \"icon\": \"/icons/018...png\", \"sort\": 1, \"description\": \"Description\" }"

Return Value

Parameter Name	Type	Description
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Example:

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

Edit File Space Type API

Basic Information

Request Method: PUT
Endpoint: /v1/openapi/workspaceType

Request Parameters

Parameter Name	Type	Description	Required
id	String	ID of the type to edit	Yes
code	String	File space type code	Yes
title	Array	Multilingual title list (same as above)	Yes
icon	String	Icon path	Yes
sort	Number	Sort order	Yes
description	String	Type description	Yes

Request Parameter Example (Body):

{
  "id": "4493041505002323969",
  "code": "workspace-type-code",
  "title": [
    { "languageCode": "zh-CN", "content": "中文名称" },
    { "languageCode": "en-US", "content": "English Name" }
  ],
  "icon": "/icons/xxx.png",
  "sort": 2,
  "description": "更新说明"
}

cURL Example:

curl -X PUT "https://<host>/v1/openapi/workspaceType" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer <token>" ^
  -d "{ \"id\": \"4493041505002323969\", \"code\": \"workspace-type-code\", \"title\": [ { \"languageCode\": \"zh-CN\", \"content\": \"中文名称\" } ], \"icon\": \"/icons/xxx.png\", \"sort\": 2, \"description\": \"更新说明\" }"

Return Value

Parameter Name	Type	Description
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Example:

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

Delete File Space Type API

Basic Information

Request Method: DELETE
Endpoint: /v1/openapi/workspaceType

Request Parameters

Parameter Name	Type	Location	Description	Required
ids	Array(Number)	Query or Body	List of type IDs to delete, supports batch	Yes

Request Parameter Example (Body):

[4493061452348784640, 4493061452348784641]

cURL Example:

curl -X DELETE "https://<host>/v1/openapi/workspaceType" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer <token>" ^
  -d "[4493061452348784640,4493061452348784641]"

Return Value

Parameter Name	Type	Description
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Example:

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

Get File Space Type Form Information API

Basic Information

Request Method: GET
Endpoint: /v1/openapi/workspaceType

Request Parameters

Parameter Name	Type	Location	Required	Description
id	String	Query	Yes	Type ID

Request Parameter Example (Query):

/v1/openapi/workspaceType?id=4493061452348784640

cURL Example:

curl -X GET "https://<host>/v1/openapi/workspaceType?id=4493061452348784640" ^
  -H "Authorization: Bearer <token>"

Return Value

Parameter Name	Type	Description
data	Object(MasterDataVO)	Type details (includes code, title, icon, sort, description, etc.)
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Example:

{
  "data": {
    "id": "4493061452348784640",
    "code": "workspace-type-code",
    "title": [
      { "languageCode": "zh-CN", "content": "中文名称" }
    ],
    "icon": "/icons/xxx.png",
    "sort": 1,
    "description": "说明"
  },
  "success": true,
  "msg": ""
}

Enable/Disable File Space Type API

Basic Information

Request Method: PUT
Endpoint: /v1/openapi/workspaceType/Enable

Request Parameters

Parameter Name	Type	Description
ids	Array	Array of type IDs
enable	Boolean	Enable or disable (true = enable, false = disable)

Request Parameter Example (Body):

{ "ids": ["4511528107064164355"], "enable": true }

cURL Example:

curl -X PUT "https://<host>/v1/openapi/workspaceType/Enable" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer <token>" ^
  -d "{ \"ids\": [4493061452348784640], \"enable\": true }"

Return Value

Parameter Name	Type	Description
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Example:

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

Basic Information

Request Method: GET
Endpoint: /v1/openapi/workspaceType/Dropdown

Request Parameters

None

cURL Example:

curl -X GET "https://<host>/v1/openapi/workspaceType/Dropdown" ^
  -H "Authorization: Bearer <token>"

Return Value

Parameter Name	Type	Description
data	Array(DropdownVO)	Dropdown data list
success	Boolean	API call result (true = success, false = failure)
msg	String	Message (usually an empty string on success)

Return Example:

{
  "data": [
    { "label": "个人空间", "value": "4493061452348784640" },
    { "label": "团队空间", "value": "4493061452348784641" }
  ],
  "success": true,
  "msg": ""
}

User

Add User (Batch Supported)

Endpoint: v1/openapi/user
Request 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
`userName`	Yes	`string`	None	Account/Username
`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 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, true: external
`userInfo.officePhoneNumber`	No	`string`	None	Office phone number
`userInfo.isAad`	No	`boolean`	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`	Username
`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

Endpoint: v1/openapi/user
Request 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
`userName`	No	`string`	None	Account/Username, only used to find the user, will not be modified, cannot be empty together with id
`id`	No	`string`	''	id, cannot be empty together with userName
`active`	Yes	`boolean`	true	Active status
`realName`	Yes	`string`	Value of userName	Real name
`spell`	Yes	`string`	None	Pinyin of real name
`serialNumber`	Yes	`string`	None	Employee number
`nickName`	Yes	`string`	None	Nickname
`gender`	Yes	`number`	0	Gender 0:FEMALE, 1:MALE
`birthday`	Yes	`string`	None	Birthday
`mobilePhone`	Yes	`string`	None	Mobile number
`email`	Yes	`string`	None	Email
`weChat`	Yes	`string`	None	WeChat ID
`avatar`	Yes	`string`	None	Avatar
`region`	Yes	`string`	None	Region
`joinTime`	Yes	`string`	None	Date of joining
`sort`	Yes	`number`	0	Sort number
`enable`	Yes	`boolean`	false	Enable/Disable
`description`	Yes	`string`	None	Description
`external`	Yes	`boolean`	false	Internal/External user flag false: internal, true: external
`officePhoneNumber`	Yes	`string`	None	Office phone number
`isAad`	Yes	`Boolean`	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 '{  
    "id": "123456",
    "userName": "user1",   
    "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
`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
Request 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
Request 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 Parameter:

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

Request Example:

shell
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 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. 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 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/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, true: external
`data.isAad`	`boolean`	Whether the account is 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, true: external
`data.IsAad`	`boolean`	Whether the 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 Information

Endpoint: v1/openapi/user/me
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 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 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, true: external
`data.IsAad`	`boolean`	Whether the 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:

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

Get Roles of Current Logged-in User

Description: Does not include roles from the user's organization, nor roles without granted data permissions (generally only super admins may have this situation).
API Endpoint: v1/openapi/user/me/roles
Request 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 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": "Knowledge Base Visitor",
			"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, 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/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": "Knowledge Base Visitor",
			"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, 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 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}' \
{
  ["1","3","5"]
}

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": "Knowledge Base Visitor",
			"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, 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	Parent organization Id, at least one of parentId or parentCode must be filled
`parentCode`	No	`string`	None	Parent organization code, at least one of parentId or parentCode 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	Is 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": "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`	Parent organization name
`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"
		}
	]
}

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, 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	Parent organization Id, at least one of parentId or parentCode must be filled
`parentCode`	No	`string`	None	Parent organization code, at least one of parentId or parentCode 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	Is 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": "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:

json
{
	"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 the 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 Codes. The array must be all Ids or all Codes.

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 Organization Tree Structure

Endpoint: v1/openapi/organization/tree
HTTP Method: get
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 Query:

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

Request Example:

curl --location 'http://localhost/v1/openapi/organization/tree?external=false' \
--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 -- node ids separated by '/'
`data.external`	`boolean`	Internal/External organization flag
`data.childNodeList`	`array`	Sub-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 the 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, can use id for creation time sort.
`orderType`	Yes	`string`	None	Sort type, asc: ascending, desc: descending
`conditions`	No	`array`	None	Query conditions, multiple are ANDed together
`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
`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, true: external
`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 the 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 the 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 the 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, can use id for creation time sort.
`orderType`	Yes	`string`	None	Sort type, asc: ascending, desc: descending
`conditions`	No	`array`	None	Query conditions, multiple are ANDed together
`conditions.fieldName`	No	`string`	None	Name of the query condition, must pass OrganizationId or OrganizationCode as filter condition
`conditions.fieldValue`	No	`string`	None	Value of the query condition
`conditions.conditionalType`	No	`number`	0
`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": "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:

json
{
    "data": [
        {
			"accountId": "123456",
			"userId": "123456",
			"userName": "user1",
			"realName": "Zhang San"
		}
    ],
    "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 the Conversation​

Bot API​

Create Bot API​

Basic Information​

Request Parameters​

Return Values​

File Space​

Multiple File Upload​

Submit Files​

Query Upload Result​

QnA Creation​

Query Files​

Query File Chunks​

Download File as Markdown API​

Basic Information​

Request Parameters​

Return Value​

RAG​

Workspace List API​

Basic Information​

Request Parameters​

Return Value​

data Array Item Structure: Category (WorkspaceCategory)​

data[n].workspaces Array Item Structure: Workspace (WorkspaceInfo)​

Workspace Creation API​

Basic Information​

Request Parameters​

Return Value​

File Workspace Edit API​

Basic Information​

Request Parameters​

Return Value​

File Workspace Delete API​

Basic Information​

Request Parameters​

Return Value​

File Preprocessing and Configuration Parameter Description​

1. Core Configuration Object: setting​

2. Global Configuration Switch: useWorkspaceSetting​

Complete JSON Example​

Metadata Parameter Description​

1. Core Configuration Object: setting​

Complete JSON Example​

Physical Delete File API​

Basic Information​

Request Parameters​

Return Value​

Behavior Description​

Edit File Metadata API​

Basic Information​

Request Parameters​

Return Value​

Behavior Description​

File List API​

Basic Information​

Request Parameters​

Return Value​

Behavior Description​

File Workspace Types​

Add File Workspace Type API​

Basic Information​

Request Parameters​

Return Value​

Edit File Space Type API​

Basic Information​

Request Parameters​

Return Value​

Delete File Space Type API​

Basic Information​

Request Parameters​

Return Value​

Get File Space Type Form Information API​

Basic Information​

Request Parameters​

Overview

Authentication Methods

User AAD Authentication

Client and User Account Authentication

Chat

Send Message to Agent

Get References for the Conversation

Bot API

Create Bot API

Basic Information

Request Parameters

Return Values

File Space

Multiple File Upload

Submit Files

Query Upload Result

QnA Creation

Query Files

Query File Chunks

Download File as Markdown API

Basic Information

Request Parameters

Return Value

RAG

Workspace List API

Basic Information

Request Parameters

Return Value

data Array Item Structure: Category (WorkspaceCategory)

data[n].workspaces Array Item Structure: Workspace (WorkspaceInfo)

Workspace Creation API

Basic Information

Request Parameters

Return Value

File Workspace Edit API

Basic Information

Request Parameters

Return Value

File Workspace Delete API

Basic Information

Request Parameters

Return Value

File Preprocessing and Configuration Parameter Description

1. Core Configuration Object: `setting`

2. Global Configuration Switch: `useWorkspaceSetting`

Complete JSON Example

Metadata Parameter Description

1. Core Configuration Object: `setting`

Complete JSON Example

Physical Delete File API

Basic Information

Request Parameters

Return Value

Behavior Description

Edit File Metadata API

Basic Information

Request Parameters

Return Value

Behavior Description

File List API

Basic Information

Request Parameters

Return Value

Behavior Description

File Workspace Types

Add File Workspace Type API

Basic Information

Request Parameters

Return Value

Edit File Space Type API

Basic Information

Request Parameters

Return Value

Delete File Space Type API

Basic Information

Request Parameters

Return Value

Get File Space Type Form Information API

Basic Information

Request Parameters