API Standard Document

API Standard Document

1. Document Information

• Document Name: SERVICEME System API Standard Document
• Version: v1.1
• Release Date: 2026-06-05
• Scope: Applicable to enterprise intelligent scenarios, supporting identity authentication, knowledge Q&A, process automation, data analysis, and content generation. The APIs follow a standard RESTful architecture for easy system integration and cross-platform usage, and are widely used in business modules such as customer service, marketing, finance, and human resources to improve collaboration efficiency and intelligent decision-making.

---

2. Revision History

Version	Revision Date	Revision Details
v1.0	2025-07-18	Initial draft
v1.1	2026-06-05	Added Cross-Origin Resource Sharing (CORS) guidelines

---

3. Overview

3.1 Purpose

This section explains the objective of the document, for example:

This document defines the API specifications of the SERVICEME system, including request formats, response formats, error codes, and more, for integrators and callers.

3.2 Terms and Abbreviations

• API: Application Programming Interface
• HTTP: Hypertext Transfer Protocol
• JSON: JavaScript Object Notation
• RESTful: An API design style

3.3 API Design Principles

• Follow RESTful conventions (where applicable).
• Use HTTPS to ensure security.
• Use JSON as the unified data format.
• Manage API versions (for example, /v1/xxx).

---

4. General Standards

4.1 Request Standards

• Request Methods: GET/POST/PUT/DELETE, etc.
• Request Headers:
  • Content-Type: application/json
  • Authorization: Bearer {token} (when authentication is required).
• Request Parameters:
  • Query parameters (GET), Body parameters (POST/PUT).
  • Required/optional field definitions.

4.2 Response Standards

• Response Format:

  {
    "code": 200,
    "message": "Success",
    "data": {}
  }

• HTTP Status Codes:

  • 200: Success
  • 400: Invalid request parameters
  • 401: Unauthorized
  • 500: Internal server error

4.3 Error Code Table

Error Code	Meaning	Recommended Action
200	Success	-
422	Invalid parameter	-
40001	Missing parameter	Check required fields
50001	Internal server error	Contact administrator

4.4 Cross-Origin Access Standards (CORS)

4.4.1 Background

Cross-Origin Resource Sharing (CORS) is a browser security mechanism used to control whether web pages are allowed to send requests to servers on different domains. When a front-end application and API service are deployed on different domains (or ports), browsers automatically perform CORS validation.

4.4.2 Default Policy in NEXT Version

By default, SERVICEME NEXT does not allow cross-origin access. In other words, if a browser page sends API requests directly and the request origin is not explicitly allowed by server-side configuration, the request will be rejected.

4.4.3 Differences from LTS Version

Item	LTS Version	NEXT Version
Cross-origin restriction	No restriction (no cross-origin interception)	Cross-origin access is denied by default
Migration impact	-	After migrating from LTS to NEXT, browser-based cross-origin API calls used previously may fail

Migration note: If your system is upgraded from LTS to NEXT and your front end relies on cross-origin API calls, those requests will fail after the upgrade unless cross-origin configuration is applied in advance.

4.4.4 Solution

If cross-origin access is required, contact your assigned delivery team for configuration. The delivery team will configure the allowed origin domains based on your business scenario.

4.4.5 Common Symptoms

When a cross-origin issue occurs, browser developer tools (Console) usually show errors like:

• Access to XMLHttpRequest at 'https://api.xxx.com/...' from origin 'https://your-app.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
• Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

If you see similar errors in the browser console, the request is being blocked by cross-origin policy. Please contact the delivery team.

---

5. API Details

5.1 API 1: Get User Information

• Path: GET /lite_api/v1/iam/user/{user_id}

• Request Parameters:

  Parameter	Type	Required	Description
  userId	Path	Yes	User ID

• Request Example:

  GET /v1/iam/user/293456 HTTP/1.1
  Authorization: Bearer abcdef123456

• Response Example:

  {
      "code": 200,
      "data": {
          "username": "string",
          "email": "string",
          "real_name": "",
          "nickname": "",
          "is_superuser": false,
          "avatar": "",
          "enable": true,
          "id": "string",
          "is_aad": false,
          "serial_number": "string",
          "created_at": "2019-08-24T14:15:22.123Z",
          "updated_at": "2019-08-24T14:15:22.123Z",
          "last_login": "2019-08-24T14:15:22.123Z",
          "roles": [],
          "user_roles": [],
          "organizations": [],
          "gender": 0,
          "birthday": "2019-08-24T14:15:22.123Z",
          "wechat": "string",
          "region": "string",
          "time_difference": 0,
          "join_time": "2019-08-24T14:15:22.123Z",
          "office_phone": "string",
          "mobile_phone": "string",
          "description": "string"
      },
      "message": "success"
  }

5.2 API 2: Create User

• Path: POST /lite_api/v1/iam/user/

• Request Parameters:

  Parameter	Type	Required	Description
  username	string	Yes	Username
  email	string	Yes	Email
  real_name	string	Yes	Real name

• Request Example:

  {
      "username": "string",
      "email": "",
      "real_name": ""
  }

• Response Example:

  {
      "username": "string",
      "email": "string",
      "real_name": ""
  }

5.3 API 3: Create Assistant

• Path: POST /lite_api/v1/robots/

• Request Parameters:

  Parameter	Type	Required	Description
  info	object	Yes	Assistant information and name
  masks	array	No	Assistant masks
  knowledge_bases	array	No	Knowledge bases
  skills	array	No	Skills
  mcps	array	No	Data models
  data_sources	array	No	Data sources
  keywords_filter	object	No	Keyword filter
  feedback_accounts	array	No	Feedback accounts

  Request Example:

  {
      "info": {
          "name": "string",
          "weight": 0,
          "avatar_url": "string",
          "description": "",
          "prompt": "string",
          "prologue": "string",
          "robot_type": "",
          "flow_id": "ef710584-0706-4b4b-b481-dd44a4541137",
          "cluster_group_id": "921cd751-fc17-4b9d-a7ec-91a434beaf0a",
          "product_position": "chat-x",
          "chat_rounds": 0,
          "user_id": "string",
          "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
          "split_type": "string",
          "load_type": "string",
          "spliter_json": "string",
          "embedding_id": "18e0b745-2b45-46cb-a826-bc9049d1152c",
          "user_skill_auths": [
              null
          ],
          "need_summary": true,
          "force_execute": true,
          "open_filter": true,
          "record_chat": true,
          "is_published": true,
          "category_ids": [
              "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          ],
          "recommend_question": false,
          "feedback": false,
          "knowledge_config": {
              "search_mode": "hybrid",
              "k": 5,
              "doc_score": 0.7,
              "qa_score": 0.8,
              "metadata": "none",
              "show_reference": false
          },
          "editable": true,
          "question_guide": false,
          "operator_execute": false,
          "bi_config": {
              "query_rewrite": false,
              "divide_think": false
          }
      },
      "masks": [
          {
              "mask_set_id": "d0bee2ed-0859-4bb6-8598-f64d47a5a28b"
          }
      ],
      "knowledge_bases": [
          {
              "classification_id": "string",
              "classification_name": "string",
              "classification_icon": "string",
              "workspaces": []
          }
      ],
      "skills": [
          {
              "skill_group_id": "85161907-67ae-4ae2-8fee-99b7d6fcc3f8"
          }
      ],
      "mcps": [],
      "data_sources": [
          {
              "skill_group_id": "85161907-67ae-4ae2-8fee-99b7d6fcc3f8"
          }
      ],
      "keywords_filter": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "robot_id": "8fe44936-b905-428b-ace5-566f232fcce8",
          "key_words": [
              "string"
          ],
          "review_input": true,
          "preset_reply_input": "string",
          "review_output": true,
          "preset_reply_output": "string"
      },
      "feedback_accounts": []
  }

  Response Example

  {
      "code": 200,
      "data": null,
      "message": "success"
  }

5.4 API 4: Get Assistant

• Path: POST /lite_api/v1/robots/{robot_id}

• Request Parameters:

Parameter	Type	Required	Description
robot_id	string	Yes	Assistant ID
internal_use	boolean	No	Internal use only

• Request Example:

  GET /lite_api/v1/robots/00001 HTTP/1.1
  Authorization: Bearer abcdef123456

• Response Example:

{
    "code": 200,
    "data": {
        "info": {
            "name": "string",
            "weight": 0,
            "avatar_url": "string",
            "description": "",
            "prompt": "string",
            "prologue": "string",
            "robot_type": "",
            "flow_id": "ef710584-0706-4b4b-b481-dd44a4541137",
            "cluster_group_id": "921cd751-fc17-4b9d-a7ec-91a434beaf0a",
            "product_position": "chat-x",
            "chat_rounds": 0,
            "user_id": "string",
            "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
            "split_type": "string",
            "load_type": "string",
            "spliter_json": "string",
            "embedding_id": "18e0b745-2b45-46cb-a826-bc9049d1152c",
            "user_skill_auths": [
                null
            ],
            "need_summary": true,
            "force_execute": true,
            "open_filter": true,
            "record_chat": true,
            "is_published": true,
            "category_ids": [
                "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            ],
            "recommend_question": false,
            "feedback": false,
            "knowledge_config": {
                "search_mode": "hybrid",
                "k": 5,
                "doc_score": 0.7,
                "qa_score": 0.8,
                "metadata": "none",
                "show_reference": false
            },
            "editable": true,
            "question_guide": false,
            "operator_execute": false,
            "bi_config": {
                "query_rewrite": false,
                "divide_think": false
            },
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "manageable": false
        },
        "masks": [],
        "knowledge_bases": [],
        "skills": [],
        "mcps": [],
        "data_sources": [],
        "keywords_filter": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "robot_id": "8fe44936-b905-428b-ace5-566f232fcce8",
            "key_words": [
                "string"
            ],
            "review_input": true,
            "preset_reply_input": "string",
            "review_output": true,
            "preset_reply_output": "string"
        },
        "feedback_accounts": []
    },
    "message": "success"
}

5.5 API 5: Upload File

• Path: POST /Api/Workspace/File/UploadFiles

• Request Parameters:

Parameter	Type	Required	Description
Files	array	No	Files uploaded in this request
WorkspaceId	string	No	Workspace ID
FullPath	string	No	Destination full path
IsCover	boolean	No	Whether this is a system upload
UserId	integer	No	User ID (for public API)
UserEmail	string	No	User email (for public API)
OCRMode	string	No	OCR mode

• Response Example:

{
    "success": true,
    "msg": "string",
    "data": [
        {
            "workspaceId": 0,
            "fullName": "string",
            "id": 0
        }
    ]
}

5.6 API 6: Get Knowledge Base List

• Path: GET /knowledge/v1/kb/me

• Request Parameters:

  Parameter	Type	Required	Description
  locale	Header	No	Locale, default en-US

• Request Example:

  GET /knowledge/v1/kb/me HTTP/1.1
  Authorization: Bearer abcdef123456
  locale: zh-CN

• Response Example:

  {
          "code": 200,
          "data": [
                  {
                          "id": "kb_001",
                          "name": "Product Knowledge Base",
                          "description": "Used to store product descriptions, FAQs, and operation manuals",
                          "mode": 1
                  }
          ],
          "message": "success"
  }

5.7 API 7: Create Knowledge Base

• Path: POST /knowledge/v1/kb/knowledge-base

• Request Parameters:

  Parameter	Type	Required	Description
  name	array	Yes	Knowledge base name, multilingual array
  description	array	Yes	Knowledge base description, multilingual array
  sort	integer	No	Sort order
  quota	object	No	Knowledge base quota configuration
  parent_id	string	No	Parent knowledge base ID
  mode	integer	No	Knowledge base mode, default 1

• Request Example:

  {
          "name": [
                  {
                          "locale": "zh-CN",
                          "content": "Customer Service Knowledge Base"
                  }
          ],
          "description": [
                  {
                          "locale": "zh-CN",
                          "content": "Used to maintain customer support Q&A and business documents"
                  }
          ],
          "sort": 0,
          "mode": 1
  }

• Response Example:

  {
          "code": 200,
          "data": {
                  "id": "kb_001",
                  "name": "Customer Service Knowledge Base"
          },
          "message": "success"
  }

5.8 API 8: Get Knowledge Base Details

• Path: GET /knowledge/v1/kb/knowledge-base/{kb_id}

• Request Parameters:

  Parameter	Type	Required	Description
  kb_id	Path	Yes	Knowledge base ID
  locale	Header	No	Locale, default en-US

• Request Example:

  GET /knowledge/v1/kb/knowledge-base/kb_001 HTTP/1.1
  Authorization: Bearer abcdef123456
  locale: zh-CN

• Response Example:

  {
          "code": 200,
          "data": {
                  "id": "kb_001",
                  "name": "Customer Service Knowledge Base",
                  "description": "Used to maintain customer support Q&A and business documents",
                  "mode": 1,
                  "sort": 0
          },
          "message": "success"
  }

5.9 API 9: Create Knowledge Base Folder

• Path: POST /knowledge/v1/file/ekb-folder

• Request Parameters:

  Parameter	Type	Required	Description
  workspaceId	Query	Yes	Associated knowledge base ID
  name	string	Yes	Folder name
  fullPath	string	Yes	Full folder path

• Request Example:

  POST /knowledge/v1/file/ekb-folder?workspaceId=1001 HTTP/1.1
  Authorization: Bearer abcdef123456
  Content-Type: application/json
  
  {
          "name": "Product Manuals",
          "fullPath": "/Customer Materials/Product Manuals"
  }

• Response Example:

  {
          "code": 200,
          "data": {
                  "id": 501,
                  "name": "Product Manuals",
                  "fullPath": "/Customer Materials/Product Manuals"
          },
          "message": "success"
  }

5.10 API 10: Get Knowledge Base Folder Tree

• Path: POST /knowledge/v1/file/ekb-folder-tree

• Request Parameters:

  Parameter	Type	Required	Description
  workspaceId	integer	Yes	Associated knowledge base ID
  ignore_folder_ids	array	No	Folder IDs to ignore

• Request Example:

  {
          "workspaceId": 1001,
          "ignore_folder_ids": [
                  999
          ]
  }

• Response Example:

  {
          "code": 200,
          "data": [
                  {
                          "id": 501,
                          "name": "Customer Materials",
                          "children": [
                                  {
                                          "id": 502,
                                          "name": "Product Manuals"
                                  }
                          ]
                  }
          ],
          "message": "success"
  }

5.11 API 11: Get Knowledge Base File List

• Path: POST /knowledge/v1/file/ekb-pagelist

• Request Parameters:

  Parameter	Type	Required	Description
  PageIndex	integer	No	Page number, default 1
  PageSize	integer	No	Page size, default 20
  OrderField	string	No	Sort field, default modified
  OrderType	string	No	Sort direction, default desc
  Conditions	array	No	Query condition list

• Request Example:

  {
          "PageIndex": 1,
          "PageSize": 20,
          "OrderField": "modified",
          "OrderType": "desc",
          "Conditions": [
                  {
                          "fieldName": "workspaceId",
                          "fieldValue": "1001"
                  }
          ]
  }

• Response Example:

  {
          "code": 200,
          "data": {
                  "items": [
                          {
                                  "id": 7001,
                                  "name": "Product_Overview.pdf",
                                  "objectType": 1,
                                  "modified": "2026-05-17T10:00:00Z"
                          }
                  ],
                  "total": 1
          },
          "message": "success"
  }

5.12 API 12: Preview Knowledge Base File

• Path: GET /knowledge/v1/file/ekb-preview

• Request Parameters:

  Parameter	Type	Required	Description
  c	Query	Yes	Container name
  n	Query	Yes	File name or Blob name
  u	Query	Yes	User ID
  s	Query	No	Source system, default ecm
  w	Query	No	Watermark user ID

• Request Example:

  GET /knowledge/v1/file/ekb-preview?c=docs&n=abc123%2Fproduct-overview.pdf&u=10001&s=ecm HTTP/1.1
  Authorization: Bearer abcdef123456

• Response Example:

  {
          "previewUrl": "https://example.com/preview/abc123",
          "expireAt": "2026-05-17T12:00:00Z"
  }

5.13 API 13: Download Knowledge Base File

• Path: POST /knowledge/v1/file/download

• Request Parameters:

  Parameter	Type	Required	Description
  fileId	integer	Yes	File ID
  objectType	integer	Yes	Object type

• Request Example:

  {
          "fileId": 7001,
          "objectType": 1
  }

• Response Example:

  {
          "downloadUrl": "https://example.com/download/7001",
          "fileName": "product-overview.pdf"
  }

5.14 API 14: Create Q&A

• Path: POST /knowledge/v1/qna

• Request Parameters:

  Parameter	Type	Required	Description
  answer	string	Yes	Standard answer
  enable	boolean	No	Whether enabled, default true
  workspaceId	integer	Yes	Associated knowledge base ID
  questions	array	Yes	Question list
  metadataExpansion	object	No	Extended metadata

• Request Example:

  {
          "answer": "Please log in and open 'My Applications' to check the approval progress.",
          "enable": true,
          "workspaceId": 1001,
          "questions": [
                  {
                          "content": "How can I check my application progress?",
                          "sort": 0
                  }
          ]
  }

• Response Example:

  {
          "code": 200,
          "data": {
                  "id": 9001,
                  "workspaceId": 1001,
                  "enable": true
          },
          "message": "success"
  }

5.15 API 15: Get Q&A List

• Path: POST /knowledge/v1/qna/pagelist

• Request Parameters:

  Parameter	Type	Required	Description
  PageIndex	integer	No	Page number, default 1
  PageSize	integer	No	Page size, default 20
  OrderField	string	No	Sort field, default modified
  OrderType	string	No	Sort direction, default desc
  Conditions	array	No	Query condition list

• Request Example:

  {
          "PageIndex": 1,
          "PageSize": 20,
          "OrderField": "modified",
          "OrderType": "desc",
          "Conditions": [
                  {
                          "fieldName": "workspaceId",
                          "fieldValue": "1001"
                  }
          ]
  }

• Response Example:

  {
          "code": 200,
          "data": {
                  "items": [
                          {
                                  "id": 9001,
                                  "question": "How can I check my application progress?",
                                  "answer": "Please log in and open 'My Applications' to check the approval progress.",
                                  "enable": true
                          }
                  ],
                  "total": 1
          },
          "message": "success"
  }

---

6. Security Standards

• Authentication: OAuth2.0/JWT/API Key.

• Data Encryption: Sensitive fields must be encrypted during transmission (for example, passwords).

• Rate Limiting: API frequency limits can follow the reference below.

  Scenario	Typical Limits	Notes
  Open APIs (for third-party access)	10-100 requests/min	For example, WeChat Pay and Alipay Open APIs typically allow 50-200 requests/min depending on API tier.
  Internal System APIs	100-1000 requests/min	Limits can be higher for internal service-to-service calls, but avoid over-consuming resources with a single service.
  User Behavior APIs	5-60 requests/min	Sensitive operations such as login or SMS sending should be strictly limited (for example, SMS verification endpoints are often limited to 1 request/60s).
  Data Query APIs	100-5000 requests/min	High-frequency query APIs may have higher limits, but should use caching to reduce database pressure.
  High-Concurrency Core APIs	Dynamic throttling (for example, token bucket)	For scenarios such as flash sales, combine throttling with circuit breaking and elastic scaling.