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/jsonAuthorization: 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 /webapi/lite_api/v1/iam/user/
{user_id} -
Request Parameters:
Parameter Type Required Description userId Path Yes User ID -
Request Example:
GET /webapi/lite_api/v1/iam/user/234567 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 /webapi/lite_api/v1/iam/user/
-
Request Parameters:
Parameter Type Required Description username string Yes Username real_name string Yes Real name is_aad boolean Yes Whether it is an AAD domain account is_superuser boolean Yes Whether it is a super administrator account avatar string Yes User avatar -
Request Example:
{
"username": "string",
"real_name": "string",
"is_aad": false,
"is_superuser": false,
"avatar": ""
} -
Response Example:
{
"code": 200,
"data": {
"username": "string",
"email": "",
"real_name": "string",
"nickname": "",
"is_superuser": false,
"avatar": "",
"enable": true,
"id": "0000046446975123456",
"is_aad": false,
"serial_number": "",
"created_at": "2026-07-21T09:02:18.709790",
"updated_at": "2026-07-21T09:02:18.709607",
"last_login": null,
"roles": [],
"user_roles": [],
"organizations": [],
"gender": 0,
"birthday": null,
"wechat": "",
"region": "",
"time_difference": 8,
"join_time": null,
"office_phone": "",
"mobile_phone": "",
"description": ""
},
"message": "success"
}
5.3 API 3: Create Assistant
-
Path: POST /webapi/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 Information
-
Path: GET /webapi/lite_api/v2/api/robot/
{robot_id} -
Authentication: HTTP Bearer authentication.
- Header:
Authorization: Bearer {token}(required)
- Header:
-
Path Parameters:
Parameter Type Required Description robot_id UUID Yes Unique robot identifier -
Request Example:
GET /webapi/lite_api/v2/api/robot/a1b2c3d4-5678-90ef-ghij-klmnopqrstuv HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN_HERE -
Response Example (200):
{
"code": 200,
"data": {
"info": {
"name": "Example Robot",
"id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
"avatar_url": "https://example.com/avatar.png",
"description": "This is an example robot",
"prompt": "You are an intelligent assistant",
"prologue": "Welcome to the example robot",
"robot_type": "chat",
"product_position": "assistant"
},
"masks": [],
"knowledge_bases": [],
"skills": [],
"mcps": [],
"data_sources": [],
"keywords_filter": null,
"feedback_accounts": []
},
"message": "success"
}
5.5 API 5: Upload File
- Path: POST /webapi/knowledge/v1/file/ekb-knowledge-upload
- Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| Files | array | Yes | Files uploaded in this request |
| WorkspaceId | string | Yes | string |
| fullPath | string | No | Full path where the file will be uploaded |
- Response Example:
{
"code": 200,
"data": [
{
"id": "000060269455675392",
"fullName": "String",
"scan_status": {}
}
],
"message": "File uploaded successfully"
}
5.6 API 6: Get Knowledge Base List
-
Path: GET /webapi/knowledge/v1/kb/me
-
Request Parameters:
Parameter Type Required Description locale Header No Locale, default en-US -
Request Example:
GET /webapi/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 /webapi/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 /webapi/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 /webapi/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 /webapi/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 /webapi/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 File List
-
Path: POST /webapi/knowledge/v1/file/ekb-pagelist
-
Request Parameters:
Parameter Type Required Description PageIndex integer No Page number, default 1PageSize integer No Page size, default 20OrderField string No Sort field, default modifiedOrderType string No Sort order, default descConditions 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.11 API 11: Preview Knowledge Base File
-
Path: GET /webapi/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 ecmw Query No Watermark user ID -
Request Example:
GET /webapi/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.12 API 12: Download Knowledge Base File
-
Path: POST /webapi/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.13 API 13: Create Q&A
-
Path: POST /webapi/knowledge/v1/qna
-
Request Parameters:
Parameter Type Required Description answer string Yes Standard answer enable boolean No Whether enabled, default trueworkspaceId 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.14 API 14: Get Q&A List
-
Path: POST /webapi/knowledge/v1/qna/pagelist
-
Request Parameters:
Parameter Type Required Description PageIndex integer No Page number, default 1PageSize integer No Page size, default 20OrderField string No Sort field, default modifiedOrderType string No Sort order, default descConditions 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"
}
5.15 API 15: QnA List Query
-
Path: POST /webapi/lite_api/v2/api/qa_list
-
Authentication: HTTP Bearer authentication.
- Header:
Authorization: Bearer {token}(required)
- Header:
-
Request Parameters (JSON Body):
Parameter Type Required Description query string Yes Search query term k integer No Number of top results to return knowledge_ids array[string]| null No List of knowledge base IDs to search search_mode string No Search mode: hybrid/embedding/textqa_score number Yes QA threshold llm_use boolean No Whether to use an LLM for processing metadata string No Metadata processing mode: none/filter/weight -
Request Example:
{
"query": "How do I upload images using the API",
"k": 20,
"knowledge_ids": [
"kb123",
"kb456"
],
"search_mode": "hybrid",
"qa_score": 1,
"llm_use": false,
"metadata": "none"
} -
Response Example (200):
{
"code": 200,
"data": [
{
"metadata": null,
"documentid": "doc_001",
"chunkid": "chunk_001",
"filename": "api-guide.pdf",
"content": "The upload API supports multipart/form-data",
"score": 0.95,
"rank_score": 0.91,
"question": "How do I upload images using the API",
"timestamp": "2026-07-21T09:30:00Z",
"url": null,
"type": "QA"
}
],
"message": "qa retrieved successfully"
} -
Validation Error Example (422):
{
"code": 422,
"data": {
"detail": []
},
"message": "Validation Error"
} -
Status Codes:
- 200: Request succeeded and returned
IResponseModel[QAResponseList] - 422: Validation error returned
- 200: Request succeeded and returned
5.16 API 16: External Knowledge Base Retrieval
-
Path: POST /webapi/lite_api/v2/api/retrieval
-
Description: Used to connect independently maintained knowledge bases within a team and is suitable for Dify integration and secondary development by delivery teams.
-
Authentication: HTTP Bearer authentication.
- Header:
Authorization: Bearer {API_KEY}(required)
- Header:
-
Request Parameters (JSON Body):
Parameter Type Required Description knowledge_id string Yes Unique knowledge base ID query string Yes User query content retrieval_setting object Yes Retrieval parameter configuration metadata_condition object No Metadata filter condition (reserved and currently ineffective) -
retrieval_setting fields:
Parameter Type Required Description top_k integer Yes Maximum number of results returned score_threshold number Yes Relevance threshold from 0 to 1 search_type string No Search mode: hybrid/embedding/text, defaulthybridhybridpipeline UUID No Advanced orchestration pipeline ID -
Request Example:
{
"knowledge_id": "your-knowledge-id",
"query": "Your question",
"retrieval_setting": {
"top_k": 2,
"score_threshold": 0.5
}
} -
Response Example (200):
{
"records": [
{
"metadata": {
"Url": "{host}/knowledge-webapi/#/share/preview?fileId=4534399061070970880&objectType=2&previewType=file&mode=login",
"FileName": "demo.pdf",
"FileId": "4534399061070970880",
"FilePath": "/",
"Created": "2026-01-21T05:23:02.2404442Z",
"page": 5
},
"score": 0.61544959,
"title": "demo.pdf",
"content": "Dify: The innovation engine for GenAI applications"
}
]
} -
Common Errors:
- 403:
AccessDeniedException, indicating insufficient permissions. - 500:
InternalServerException, indicating an internal server error. - Business error codes:
- 403:
| error_code | Description |
|---|---|
| 1001 | Invalid Authorization header format (expected Bearer <api-key>) |
| 1002 | Authorization failure |
Note: This interface is controlled by product permissions; it can only verify access rights and cannot confirm whether the knowledge base exists. When an administrator passes a non-existent knowledge base ID, empty results are typically returned.
6. Security Standards
- Authentication: OAuth2.0/JWT/API Key.
- Data Encryption: Sensitive fields must be encrypted during transmission (for example, passwords).
- Rate Limiting: API call frequency should be controlled based on interface type, business sensitivity, and system load. Refer to the table 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 the API tier. |
| Internal System APIs | 100-1000 requests/min | Limits can be relaxed for internal service-to-service calls, but a single service should not consume excessive resources. |
| 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 be relaxed, but caching should be used 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. |
Note: The ranges above are for reference only. Actual settings should be determined based on interface performance, request source, resource consumption, and business peaks.