Open API

Overview

The basic process for calling the SERVICEME Open API:

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

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

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

Step 2: Call the corresponding API with the access token

Authentication Methods

User AAD Authentication

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

How to obtain 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 the integrator)

Example request:

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	Contains error messages if success is false

Example response:

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

Client and User Account Authentication

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

How to obtain client and secret?

System administrators create credentials through the client management interface {domain}#/super-admin/client-management. After creation, the client id and secret can be obtained.

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

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

JavaScript signature example:

Please create a new HTML file, paste the following content, and open it in a 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>

Example request:

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	Contains error messages if success is false

Example response:

{
    "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 headers:

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 the SERVICEME system (see SERVICEME system)
content	Yes	string	Question content
sessionId	No	string	Session id representing a chat context; pass null to start a new session. The new session id will be returned in the response. From the second Q&A onward, include the previous session id 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 (true: include; false: exclude)
language	No	object	Language settings for this chat
language.chatLanguage	No	string	Desired language for AI response; if empty, AI decides
language.systemLanguage	No	string	Base language of the session, affects plugin names, prompts, etc., but does not affect AI response. Defaults to en-US if empty. If chatLanguage is provided, it overrides this.

How to obtain the expert code? Please see the image below:

Example request:

curl --location 'https://localhost/vee/openapi/chat/expert' \
--header 'Authorization: openapi {access_token}' \
--header 'Content-Type: application/json' \
--data '{
    "expertCode": "CHATES",
    "content": "Overtime application",
    "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	Textual answer content
	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	Status (success: successful)
	finish_reason			string	Whether the answer is finished; "stop" means finished, null means ongoing
success				boolean	Whether the request was successful
msg				string	Contains error messages if success is false

Non-streaming response example:

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

Streaming response example:

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

data: {"data":{"chatRecordId":"4299228743576059904","sessionId":"4292755079242457089","content":"The team leader issues work tasks, clarifies completion milestones and acceptance criteria, and employees can only work overtime after reaching consensus with their supervisors. After overtime, employees fill in overtime hours in the time system and submit the overtime process in the system. The remarks must clearly list the overtime tasks, and complete clock-in and clock-out records at the workplace must be recorded. The team leader/supervisor reviews the overtime results and approves the overtime application process. HR confirms the clock-in records and calculates compensatory leave quotas.","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":"Answer Reference Document.pdf","url":"https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login"}],"suggestionQuestions":[],"thoughts":[],"finish_reason":"stop"},"success":true,"msg":""}

Get Reference Materials for a Conversation

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

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 taken from the chatRecordId field returned by the Q&A API

Example request:

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	Quoted fragment content from the conversation record
	score	float	Relevance (0 to 1, closer to 1 means more relevant)
	url	string	Link (currently only file-type references have links)
	type	string	Type enum: document, image, QnA, other
success		boolean	Whether the request was successful
msg		string	Contains error messages if success is false

Example response:

{
  "data": [
    {
      "title": "company-policy.pdf",
      "content": "Excerpt one ......",
      "score": 0.95,
      "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
      "type": "document"
    },
    {
      "title": "company-policy.pdf",
      "content": "Excerpt two ......",
      "score": 0.81,
      "url": "https://localhost/#/share/preview?fileId=4268457334348447744&objectType=2&previewType=file&mode=login",
      "type": "document"
    },
    {
      "title": "company-policy.pdf",
      "content": "Excerpt three ......",
      "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

Parameter	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 elements as above
historyRecordNumber	Number	Maximum number of historical messages
feedback	Boolean	Whether to enable feedback
recoreChat	Boolean	Whether to record conversations
useSuggestedQuestions	Boolean	Whether to enable suggested questions
useKnowledgeBase	Boolean	Whether to enable knowledge base
sort	Number	Sort order number
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)	Set of 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

Parameter	Type	Description
data	String	New 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 no)

Request Example:

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 successful
msg		string	When success is false, contains partial 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 no)

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 status ID, can be used to poll for latest upload results
success		boolean	Whether successful
msg		string	When success is false, contains partial error messages

Response Example:

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

Query Upload Results

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` value returned by the multiple file submit 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	Status enum: underway (queued), success, fail
	uploader	string	Uploader
	errorMsg	string	When state is fail, contains failure reason
	finishTime	string	File processing completion time
success		boolean	Whether successful
msg		string	When success is false, contains partial 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 successful
msg	string	When success is false, contains partial 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 first page
pageSize	No	number	Number of items to retrieve, default 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 indexing status: waiting, success, fail, underway
	previewState		string	File preview status: waiting, success, fail, underway
	fileCanPreview		boolean	Whether file can be previewed, true: yes; false: no
	previewUrl		string	File preview URL
	createdByRealName		string	File creator name
	createdByAccount		string	File creator account
	created		datetime	File creation time
	modifiedByRealName		string	File editor name
	modifiedByAccount		string	File editor account
	modified		datetime	File edit time
success			boolean	Whether successful
msg			string	When success is false, contains partial 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 Chunk

API Endpoint:v1/openapi/workspace/file/chunk
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
fileId	Yes	string	File ID
imageFormat	No	string	Image format, markdown or html, default is markdown output
pageIndex	No	number	Page number, default is first page
pageSize	No	number	Number of items to retrieve, default is 10

Request Example:

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

Response Body:

Parameter Name	Secondary Parameter	Type	Description
data		object array	Response data
	id	string	Chunk ID
	content	string	Chunk content
success		boolean	Whether the request was successful
msg		string	Contains error message if success is false

Response Example:

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

RAG

API Endpoint:/v1/openapi/rag
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	Type	Required	Default	Description
`query`	`string`	No	None	The question or content to search for. Cannot be `null` together with `keywords`.
`keywords`	`string`	No	None	Keywords separated by `\|`. Cannot be `null` together with `query`. If `null`, keywords will be extracted as needed; if not empty, the provided keywords are used directly.
`workspaces`	`array`	No	None	Names or IDs of file workspaces to search in this RAG operation. If provided, search will be limited to these workspaces.
`ragObject`	`RagObject`	Yes	`0`	RAG object type, enum values (see RagObject Enum). QNA queries are currently not supported.
`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`	Metadata search mode, effective only if metadataProvider is enabled. 0: filter mode, 1: weighted ranking mode.
`ragMode`	`SearchMode`	Yes	`0`	RAG mode, enum values (see SearchMode Enum).
`weights`	`object`	No	None	RRF weights for each index, effective only 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 containing search results and search ID information.
`data.results`	`array`	List of search results, each element is an object containing chunk information.
`data.results[].chunkId`	`string`	Chunk ID
`data.results[].fileId`	`string`	File ID to which the chunk belongs
`data.results[].fileName`	`string`	File name to which the chunk belongs
`data.results[].content`	`string`	Chunk content
`data.results[].metadata`	`json`	Chunk metadata
`data.results[].url`	`string`	URL 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 (QNA is currently not supported, 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 Q&A content only.
`Doc`	2	Search document content only.

SearchMode Enum

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

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

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

Note: If using Cohere's official API, the Token field value is bearer token; if using Azure AI Foundry's API, the Token field value should omit the bearer prefix.

Workspace List API

Basic Information

Request Method: GET
API Endpoint: /v1/openapi/workspace/all

Request Parameters

None

Response

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	List of workspaces under this category (see table 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)	List of operation permissions
fileCount	Number	Number of files (statistical value)

Response Example:

{
  "data": [
    {
      "id": 4493041505002323001,
      "name": "Video Materials",
      "icon": "icon-video",
      "workspaces": [
        {
          "id": "4493061452348784640",
          "name": "Promotional Video Assets",
          "description": "Used to store promotional 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 Manuals",
          "description": "Externally released product documentation",
          "operationKeys": [],
          "fileCount": 342
        }
      ]
    }
  ],
  "success": true,
  "msg": ""
}

Workspace Creation API

Basic Information

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

Request Parameters

Parameter Name	Type	Description
name	String	Workspace name (example: "Test Workspace")
workspaceTypeId	String	Workspace type ID (example: "4493041505002323969")
classificationId	String	Category ID (example: "4035265396658405376")
description	String	Workspace description (example: "Test Workspace")
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 permissions list (example: empty array)
notice	String	Workspace notice (example: "Test Workspace")
settings	String	Workspace configuration (JSON string format, including mode, file size, supported types, etc.)

Note:

For the explanation of the settings field, please refer to 【File Preprocessing and Configuration Parameters Description】 below.
For the explanation of the metadataTemplate field, please refer to 【Metadata Parameters 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 Values

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

Return example:

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

File Workspace Edit API

Basic Information

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

Request Parameters

Parameter	Type	Description
id	String	ID of the file workspace to edit (e.g., "4437336392049102848")
workspaceTypeId	String	File workspace type ID (e.g., "4437336252408139777")
workspaceTypeName	String	File workspace type name (e.g., "Test Workspace")
name	String	Workspace name (e.g., "Test Workspace")
enable	Boolean	Whether enabled (true = enabled, false = disabled)
notice	String	Workspace notice (e.g., "Final Test")
description	String	Workspace description (e.g., "Final Test")
classificationId	String	Classification ID (e.g., "4035265396658405376")
quota	Number/Null	Quota (can be null to indicate no modification)
quotaUsage	Number	Quota used (e.g., 50815916)
settings	String	Workspace settings (JSON string format, including mode, OCR, summary, and other advanced configurations)
metadataTemplate	String	Metadata template (JSON array string, e.g., `"[{"name":"Test","type":0}]"`)

Note:

For the settings field, please refer to the section 【File Preprocessing and Configuration Parameters Description】 below.
For the metadataTemplate field, please refer to the section 【Metadata Parameters Description】 below.

Request 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 Values

Parameter	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": ""
}

File Workspace Delete API

Basic Information

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

Request Parameters

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

Request example:

[
  4493061452348784640,
  4493061452348784641
]

Return Values

Parameter	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": ""
}

File Preprocessing and Configuration Parameters Description

This JSON structure defines the preprocessing rules, segmentation modes, and feature toggle configurations for files within a workspace. It is typically the core content of the settings field (corresponding to the settings parameter in the file workspace add/edit APIs). Below are detailed descriptions of each parameter:

1. Core Configuration Object: `setting`

Parameter	Type	Description	Remarks
`mode`	String	Options: - `default`: Default segmentation mode - `refine`: Refined segmentation mode	Controls the file content segmentation strategy; refined mode splits content more finely
`maxLength`	Number	Numeric (e.g., 1024)	Effective only under custom segmentation model, defines max length per segment, default is 1024
`overlap`	Number	Numeric (e.g., 0)	Length of overlapping text between segments to avoid content breaks; 0 means no overlap
`previewEnable`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether file preview is enabled; when enabled, users can view part of the content without opening the file
`enable`	Boolean	`true` (enabled) / `false` (disabled)	Master switch controlling whether file preprocessing is enabled (including OCR, summary generation, and all subsequent sub-functions)
`documentOCR`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether OCR recognition is performed on documents, suitable for image format documents or documents containing images; when enabled, text in images can be extracted
`ocrMode`	String	Options: - `read`: Read mode (extract text only) - `layout`: Layout mode (preserves text layout such as paragraphs, table positions)	Effective only when `documentOCR` is `true`, defines OCR recognition accuracy and output format
`summaryEnable`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether automatic document summary generation is enabled; when enabled, summaries are generated according to `summaryPrompt` rules
`imageRecognize`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether images within the document are recognized; when enabled, basic analysis of image content (e.g., image type, key information) is performed
`summaryPrompt`	String	Text string (e.g., `"### Summarize the following in the original language in no more than 200 words."`)	Custom rule for generating full-text summaries, supports markdown format, guides AI to generate summaries that meet requirements
`formulas`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether formulas in the document (e.g., mathematical formulas, chemical equations) are recognized; when enabled, formulas are extracted and original format preserved
`screenshots_by_page`	Boolean	`true` (enabled) / `false` (disabled)	Controls whether screenshots are generated by document page; when enabled, an image screenshot is generated for each page to facilitate quick preview of page layout

2. Global Configuration Switch: `useWorkspaceSetting`

Parameter	Type	Description	Remarks
`useWorkspaceSetting`	Boolean	`true` (follow) / `false` (custom)	Controls whether the current file's configuration follows the global configuration of the file workspace (Workspace): - `true`: file uses Workspace's default configuration, ignoring custom rules in current `setting` - `false`: file uses custom configuration in current `setting`, overriding Workspace's default rules

Complete JSON Example

{
	"setting": {
		"mode": "refine", // segmentation mode, default: default, refine: refined
		"maxLength": 1024, // fill in under custom segmentation model, default 1024
		"overlap": 0, // length of overlapping text 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 inside 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 // screenshots by page
	},
	"useWorkspaceSetting": true // whether file settings follow Workspace settings
}

Metadata Parameters Description

Metadata accepts a JSON string as the parameter value.

1. Core Configuration Object: `setting`

Parameter	Type	Description
`name`	String	Metadata name
`type`	Number	0: Text type; 1: Option type
`limit`	String	Each option item

Complete JSON Example

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

Physical File Deletion API

Basic Information

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

Request Parameters

Parameter	Type	Location	Required	Description
id	Number(Int64)	Query	Yes	ID of the file to be physically deleted

Request 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 Values

Parameter	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 permission is denied, the call will fail.

Edit File Metadata API

Basic Information

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

Request Parameters

Parameter	Type	Location	Required	Description
id	Number(Int64)	Body	Yes	ID of the file 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\"}]"
}

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\\\"}]\"}"

Return Values

Parameter	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) based on input parameters and rebuilds the doc_metadata index to make changes effective in search.
If the specified ID does not exist or permission is denied, the call will fail.

File List API

Basic Information

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

Request Parameters

Parameter	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	Number of items per page, default `10`

Request body example (JSON):

{
  "workspace": "Public Repository",
  "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 Repository\",\"pageIndex\":1,\"pageSize\":10}"

Return Values

Parameter	Type	Description
pageIndex	Number	Current page number
pageSize	Number	Number of items per page
totalCount	Number	Total count (may return 0 or -1 indicating unknown/incremental, client can handle accordingly)
data	Array<File>	List of file data, fields described below

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 the file can be previewed (calculated by backend preview status)
previewState	String	Preview status: `waiting` / `underway` / `success` / `fail`
chunkingState	String	Chunking processing status: `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": "ExampleDocument.docx",
      "previewUrl": "https://<host>/preview/file/4493061452348784640",
      "fileCanPreview": true,
      "previewState": "success",
      "chunkingState": "underway",
      "modified": "2024-07-01T09:30:15Z"
    }
  ]
}

Behavior Description

Returns only "files" (excluding folders).
Default sorting is descending by Modified field, supports pagination.
Only files within the specified workspace are queried; caller must have access permission to the workspace; non-admins require corresponding 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 are used.

File Workspace Types

Add File Workspace Type API

Basic Information

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

Request Parameters

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

Request example (Body):

{
  "code": "FileWorkspaceTypeCode",
  "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\": \"FileWorkspaceTypeCode\", \"title\": [ { \"languageCode\": \"zh-CN\", \"content\": \"Multilingual\" } ], \"icon\": \"/icons/018...png\", \"sort\": 1, \"description\": \"Description\" }"

Return Values

Parameter	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 Workspace Type Interface

Basic Information

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

Request Parameters

Parameter	Type	Description
id	String	ID of the type to be edited
code	String	Workspace type code
title	Array	Multilingual title list (same as above)
icon	String	Icon path
sort	Number	Sort order
description	String	Type description

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": "Update 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\": \"Update description\" }"

Response

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

Response Example:

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

Delete Workspace Type Interface

Basic Information

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

Request Parameters

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

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]"

Response

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

Response Example:

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

Get Workspace Type Form Information Interface

Basic Information

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

Request Parameters

Parameter	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>"

Response

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

Response Example:

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

Enable/Disable Workspace Type Interface

Basic Information

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

Request Parameters

Parameter	Type	Description
id	Number(Int64)	Type ID
enable	Boolean	Enable status (true = enable, false = disable)

Request Parameter Example (Body):

{ "id": 4493061452348784640, "enable": true }

cURL Example:

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

Response

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

Response 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>"

Response

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

Response Example:

{
  "data": [
    { "label": "Personal Space", "value": "4493061452348784640" },
    { "label": "Team Space", "value": "4493061452348784641" }
  ],
  "success": true,
  "msg": ""
}

User

Add User (Supports Batch)

Endpoint:v1/openapi/user
Request Method:post
Request Headers:

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	Activation status
`userInfo`	No	`object`	None	User information
`userInfo.realName`	No	`string`	Value of userName	Real name
`userInfo.spell`	No	`string`	None	Pinyin of real name
`userInfo.serialNumber`	No	`string`	None	Employee number
`userInfo.nickName`	No	`string`	None	Nickname
`userInfo.gender`	No	`number`	0	Gender 0:FEMALE, 1:MALE
`userInfo.birthday`	No	`string`	None	Birthday
`userInfo.mobilePhone`	No	`string`	None	Mobile phone number
`userInfo.email`	No	`string`	None	Email
`userInfo.weChat`	No	`string`	None	WeChat ID
`userInfo.avatar`	No	`string`	None	Avatar
`userInfo.region`	No	`string`	None	Region
`userInfo.joinTime`	No	`string`	None	Date of joining
`userInfo.sort`	No	`number`	0	Sort order
`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 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": "China",
        "joinTime": "2023-01-01",
        "sort": 101,
        "enable": true,
        "description": "Description of Zhang San",
        "external": false,
        "officePhoneNumber": "010-12345678",
        "isAad": false
    },  
}]  '

Response Body:

Field Name	Type	Description
`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": "张三"
		}
	]
}

Modify User

Endpoint:v1/openapi/user
Request Method:put
Request Headers:

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, used only to find 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	Activation 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 phone 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 order
`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 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": "China",
    "joinTime": "2023-01-01",
    "sort": 101,
    "enable": true,
    "description": "Description of Zhang San",
    "external": false,
    "officePhoneNumber": "010-12345678",
    "isAad": false
}  '

Response Body:

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

Response Example:

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

Delete User

Endpoint:v1/openapi/user
Request Method:delete
Request Headers:

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 either all IDs or all 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 Headers:

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

Content Type:application/json
Route Parameters:

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

Request Example:

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

Response Body:

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

Response Example:

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

Disable User

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

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 User (Batch Supported)

Endpoint:v1/openapi/user/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
Request body:

Parameter Name	Required	Type	Default	Description
codes	Yes	`array`	None	Array of user IDs or usernames. The array must contain either all IDs or all 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
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
`orderField`	Yes	`string`	None	Field used for sorting. Id contains time information, 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 of the query condition: 0: exact match, 1: fuzzy match, 2: greater than, 3: greater or equal, 4: less than, 5: less or equal, 6: contains (in), 7: does not contain (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 of items 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 active
`data.avatar`	`string`	Avatar
`data.birthday`	`string`	Birthday
`data.created`	`string`	User data creation date
`data.modified`	`string`	User data last modified date
`data.description`	`string`	Description
`data.gender`	`number`	Gender 0:FEMALE, 1:MALE
`data.mobilePhone`	`string`	Mobile phone number
`data.nickName`	`string`	Nickname
`data.email`	`string`	Email
`data.joinTime`	`string`	Date of joining
`data.region`	`string`	Region
`data.weChat`	`string`	WeChat ID
`data.spell`	`string`	Pinyin of real name
`data.serialNumber`	`string`	Employee number
`data.accountId`	`string`	Account ID the user belongs to
`data.sort`	`number`	Sort number
`data.officePhoneNumber`	`string`	Office phone number
`data.external`	`boolean`	Internal/external user flag false: internal user, true: external user
`data.isAad`	`boolean`	Whether the account is from AAD (Microsoft Entra ID)
`data.enable`	`boolean`	Enabled/disabled
`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}
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' \
--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 active
`data.Avatar`	`string`	Avatar
`data.Birthday`	`string`	Birthday
`data.Created`	`string`	User data creation date
`data.Modified`	`string`	User data last modified date
`data.Description`	`string`	Description
`data.Gender`	`number`	Gender 0:FEMALE, 1:MALE
`data.MobilePhone`	`string`	Mobile phone number
`data.NickName`	`string`	Nickname
`data.Email`	`string`	Email
`data.JoinTime`	`string`	Date of joining
`data.Region`	`string`	Region
`data.WeChat`	`string`	WeChat ID
`data.Spell`	`string`	Pinyin of real name
`data.SerialNumber`	`string`	Employee number
`data.AccountId`	`string`	Account ID the user belongs to
`data.Sort`	`number`	Sort number
`data.OfficePhoneNumber`	`string`	Office phone number
`data.External`	`boolean`	Internal/external user flag false: internal user, true: external user
`data.IsAad`	`boolean`	Whether the account is from AAD (Microsoft Entra ID)
`data.Enable`	`boolean`	Enabled/disabled
`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
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' \
--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 active
`data.Avatar`	`string`	Avatar
`data.Birthday`	`string`	Birthday
`data.Created`	`string`	User data creation date
`data.Modified`	`string`	User data last modified date
`data.Description`	`string`	Description
`data.Gender`	`number`	Gender 0:FEMALE, 1:MALE
`data.MobilePhone`	`string`	Mobile phone number
`data.NickName`	`string`	Nickname
`data.Email`	`string`	Email
`data.JoinTime`	`string`	Date of joining
`data.Region`	`string`	Region
`data.WeChat`	`string`	WeChat ID
`data.Spell`	`string`	Pinyin of real name
`data.SerialNumber`	`string`	Employee number
`data.AccountId`	`string`	Account ID the user belongs to
`data.Sort`	`number`	Sort number
`data.OfficePhoneNumber`	`string`	Office phone number
`data.External`	`boolean`	Internal/external user flag false: internal user, true: external user
`data.IsAad`	`boolean`	Whether the account is from AAD (Microsoft Entra ID)
`data.Enable`	`boolean`	Enabled/disabled
`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 Current Logged-in User's Roles

Description: Does not include roles from the user's affiliated organizations, nor roles without granted data permissions (usually only super admins do not have this).
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 objects
`data.roleId`	`string`	Role ID
`data.roleName`	`string`	Role name
`data.dataPermissionList`	`array`	Data permissions of the user under this role
`data.dataPermissionList.BusinessTreeType`	`number`	Application type
`data.dataPermissionList.DataPermissionObjectId`	`string`	Data permission object ID, e.g., if knowledge base permission, it is the knowledge base ID
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Response message (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 objects
`data.roleId`	`string`	Role ID
`data.roleName`	`string`	Role name
`data.dataPermissionList`	`array`	Data permissions of the user under this role
`data.dataPermissionList.BusinessTreeType`	`number`	Application type
`data.dataPermissionList.DataPermissionObjectId`	`string`	Data permission object ID, e.g., if knowledge base permission, it is the knowledge base ID
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Response message (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 objects
`data.roleId`	`string`	Role ID
`data.roleName`	`string`	Role name
`data.dataPermissionList`	`array`	Data permissions of the user under this role
`data.dataPermissionList.BusinessTreeType`	`number`	Application type
`data.dataPermissionList.DataPermissionObjectId`	`string`	Data permission object ID, e.g., if knowledge base permission, it is the knowledge base ID
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Response message (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 and non-repetitive in the system
`parentId`	No	`string`	None	Parent organization ID or parent organization code, at least one must be provided
`parentCode`	No	`string`	None	Parent organization code or parent organization ID, at least one must be provided
`name`	Yes	`string`	None	Name
`location`	No	`string`	None	Address
`remarks`	No	`string`	None	Remarks
`contact`	No	`string`	None	Contact information
`Info`	No	`string`	None	Organization information
`Extension`	No	`string`	None	Extension information
`IsSubsidiary`	No	`boolean`	false	Whether it is a subsidiary company
`sort`	No	`number`	0	Sort order
`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`	Whether it is a subsidiary company
`data.sort`	`number`	Sort order
`data.isEnable`	`boolean`	Enable/disable
`data.external`	`boolean`	Internal/external organization flag
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Response message (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 provided
`code`	No	`string`	None	Organization code, at least one of code or id must be provided
`parentId`	No	`string`	None	Parent organization ID or parent organization code, at least one must be provided
`parentCode`	No	`string`	None	Parent organization code or parent organization ID, at least one must be provided
`name`	Yes	`string`	None	Name
`location`	No	`string`	None	Address
`remarks`	No	`string`	None	Remarks
`contact`	No	`string`	None	Contact information
`Info`	No	`string`	None	Organization information
`Extension`	No	`string`	None	Extension information
`IsSubsidiary`	No	`boolean`	false	Whether it is a subsidiary company
`sort`	No	`number`	0	Sort order
`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`	Whether enabled
`data.name`	`string`	Name
`data.location`	`string`	Address
`data.remarks`	`string`	Remarks
`data.contact`	`string`	Contact information
`data.Info`	`string`	Organization information
`data.Extension`	`number`	Extension information
`data.IsSubsidiary`	`boolean`	Whether it is a subsidiary company
`data.sort`	`number`	Sort order
`data.isEnable`	`boolean`	Enable/disable
`data.external`	`boolean`	Internal/external organization flag
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Response message (if any)

Response Example:

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

Delete Organization

Endpoint:v1/openapi/organization
Method:delete
Request Header:

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

Content Type:application/json
Request Body:

Parameter Name	Required	Type	Default	Description
	Yes	`array`	None	Array of organization Ids or organization Codes. The array must contain either all Ids or all organization 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 Tree-Structured Organization

Endpoint:v1/openapi/organization/tree
Method:get
Request Header:

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

Content Type:application/json
Request Query:

Parameter Name	Required	Type	Default	Description
`external`	No	`boolean`	false	Whether 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`	Child organizations
`success`	`boolean`	Whether the request was successful
`msg`	`string`	Message returned by the request (if any)

Response Example:

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

Get Users Based on User-Organization Relationship (Paginated)

Endpoint:v1/openapi/organization/getAllOrgUserPageList
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 used for sorting. Id contains time info, so sorting by id can be used as creation time sorting
`orderType`	Yes	`string`	None	Sort type, asc: ascending, desc: descending
`conditions`	No	`array`	None	Query conditions, multiple conditions are combined with AND
`conditions.fieldName`	No	`string`	None	Name of the query condition, e.g. organizationId
`conditions.fieldValue`	No	`string`	None	Value of the query condition
`conditions.conditionalType`	No	`number`	0	Comparison type: 0: exact match, 1: fuzzy match, 2: greater than, 3: greater or equal, 4: less than, 5: less or equal, 6: contains (in), 7: not contains (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 of items per page

Request Example:

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

Response Body:

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

Response Example:

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

Add User-Organization Relationship

Endpoint:v1/openapi/organization/relationship
Method:post
Request Header:

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

Content Type:application/json
Request Body:

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

Request Example:

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

Response Body:

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

Response Example:

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

Delete User-Organization Relationship

Endpoint:v1/openapi/organization/relationship
Method:delete
Request Header:

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

Content Type:application/json
Request Body:

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

Request Example:

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

Response Body:

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

Response Example:

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

Query Users Under Organization (Paginated)

Endpoint:v1/openapi/organization/getUserPages
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 used for sorting. Id contains time info, so sorting by id can be used as creation time sorting
`orderType`	Yes	`string`	None	Sort type, asc: ascending, desc: descending
`conditions`	No	`array`	None	Query conditions, multiple conditions are combined with AND
`conditions.fieldName`	No	`string`	None	Name of the query condition, must include at least OrganizationId or OrganizationCode as filter condition
`conditions.fieldValue`	No	`string`	None	Value of the query condition
`conditions.conditionalType`	No	`number`	0	Comparison type: 0: exact match, 1: fuzzy match, 2: greater than, 3: greater or equal, 4: less than, 5: less or equal, 6: contains (in), 7: not contains (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 of items 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 position
`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 Reference Materials for a Conversation​

Bot API​

Create Bot API​

Basic Information​

Request Parameters​

Return Values​

File Space​

Single File Upload​

File Space​

Multiple File Upload​

Submit Files​

Query Upload Results​

QnA Creation​

Query Files​

Query File Chunk​

RAG​

Workspace List API​

Basic Information​

Request Parameters​

Response​

data Array Item Structure: Category (WorkspaceCategory)​

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

Workspace Creation API​

Basic Information​

Request Parameters​

Return Values​

File Workspace Edit API​

Basic Information​

Request Parameters​

Return Values​

File Workspace Delete API​

Basic Information​

Request Parameters​

Return Values​

File Preprocessing and Configuration Parameters Description​

1. Core Configuration Object: setting​

2. Global Configuration Switch: useWorkspaceSetting​

Complete JSON Example​

Metadata Parameters Description​

1. Core Configuration Object: setting​

Complete JSON Example​

Physical File Deletion API​

Basic Information​

Request Parameters​

Return Values​

Behavior Description​

Edit File Metadata API​

Basic Information​

Request Parameters​

Return Values​

Behavior Description​

File List API​

Basic Information​

Request Parameters​

Return Values​

Behavior Description​

File Workspace Types​

Add File Workspace Type API​

Basic Information​

Request Parameters​

Return Values​

Edit Workspace Type Interface​

Basic Information​

Request Parameters​

Response​

Delete Workspace Type Interface​

Basic Information​

Request Parameters​

Response​

Get Workspace Type Form Information Interface​

Basic Information​

Request Parameters​

Response​

Enable/Disable Workspace Type Interface​

Overview

Authentication Methods

User AAD Authentication

Client and User Account Authentication

Chat

Send Message to Agent

Get Reference Materials for a Conversation

Bot API

Create Bot API

Basic Information

Request Parameters

Return Values

File Space

Single File Upload

File Space

Multiple File Upload

Submit Files

Query Upload Results

QnA Creation

Query Files

Query File Chunk

RAG

Workspace List API

Basic Information

Request Parameters

Response

data Array Item Structure: Category (WorkspaceCategory)

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

Workspace Creation API

Basic Information

Request Parameters

Return Values

File Workspace Edit API

Basic Information

Request Parameters

Return Values

File Workspace Delete API

Basic Information

Request Parameters

Return Values

File Preprocessing and Configuration Parameters Description

1. Core Configuration Object: `setting`

2. Global Configuration Switch: `useWorkspaceSetting`

Complete JSON Example

Metadata Parameters Description

1. Core Configuration Object: `setting`

Complete JSON Example

Physical File Deletion API

Basic Information

Request Parameters

Return Values

Behavior Description

Edit File Metadata API

Basic Information

Request Parameters

Return Values

Behavior Description

File List API

Basic Information

Request Parameters

Return Values

Behavior Description

File Workspace Types

Add File Workspace Type API

Basic Information

Request Parameters

Return Values

Edit Workspace Type Interface

Basic Information

Request Parameters

Response

Delete Workspace Type Interface

Basic Information

Request Parameters

Response

Get Workspace Type Form Information Interface

Basic Information

Request Parameters

Response

Enable/Disable Workspace Type Interface