Skip to main content

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

VersionRevision DateRevision Details
v1.02025-07-18Initial draft
v1.12026-06-05Added 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 CodeMeaningRecommended Action
200Success-
422Invalid parameter-
40001Missing parameterCheck required fields
50001Internal server errorContact 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

ItemLTS VersionNEXT Version
Cross-origin restrictionNo 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:

    ParameterTypeRequiredDescription
    userIdPathYesUser 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:

    ParameterTypeRequiredDescription
    usernamestringYesUsername
    real_namestringYesReal name
    is_aadbooleanYesWhether it is an AAD domain account
    is_superuserbooleanYesWhether it is a super administrator account
    avatarstringYesUser 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:

    ParameterTypeRequiredDescription
    infoobjectYesAssistant information and name
    masksarrayNoAssistant masks
    knowledge_basesarrayNoKnowledge bases
    skillsarrayNoSkills
    mcpsarrayNoData models
    data_sourcesarrayNoData sources
    keywords_filterobjectNoKeyword filter
    feedback_accountsarrayNoFeedback 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)
  • Path Parameters:

    ParameterTypeRequiredDescription
    robot_idUUIDYesUnique 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:
ParameterTypeRequiredDescription
FilesarrayYesFiles uploaded in this request
WorkspaceIdstringYesstring
fullPathstringNoFull 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:

    ParameterTypeRequiredDescription
    localeHeaderNoLocale, 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:

    ParameterTypeRequiredDescription
    namearrayYesKnowledge base name, multilingual array
    descriptionarrayYesKnowledge base description, multilingual array
    sortintegerNoSort order
    quotaobjectNoKnowledge base quota configuration
    parent_idstringNoParent knowledge base ID
    modeintegerNoKnowledge 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:

    ParameterTypeRequiredDescription
    kb_idPathYesKnowledge base ID
    localeHeaderNoLocale, 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:

    ParameterTypeRequiredDescription
    workspaceIdQueryYesAssociated knowledge base ID
    namestringYesFolder name
    fullPathstringYesFull 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:

    ParameterTypeRequiredDescription
    PageIndexintegerNoPage number, default 1
    PageSizeintegerNoPage size, default 20
    OrderFieldstringNoSort field, default modified
    OrderTypestringNoSort order, default desc
    ConditionsarrayNoQuery 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:

    ParameterTypeRequiredDescription
    cQueryYesContainer name
    nQueryYesFile name or Blob name
    uQueryYesUser ID
    sQueryNoSource system, default ecm
    wQueryNoWatermark 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:

    ParameterTypeRequiredDescription
    fileIdintegerYesFile ID
    objectTypeintegerYesObject 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:

    ParameterTypeRequiredDescription
    answerstringYesStandard answer
    enablebooleanNoWhether enabled, default true
    workspaceIdintegerYesAssociated knowledge base ID
    questionsarrayYesQuestion list
    metadataExpansionobjectNoExtended 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:

    ParameterTypeRequiredDescription
    PageIndexintegerNoPage number, default 1
    PageSizeintegerNoPage size, default 20
    OrderFieldstringNoSort field, default modified
    OrderTypestringNoSort order, default desc
    ConditionsarrayNoQuery 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)
  • Request Parameters (JSON Body):

    ParameterTypeRequiredDescription
    querystringYesSearch query term
    kintegerNoNumber of top results to return
    knowledge_idsarray[string]| nullNoList of knowledge base IDs to search
    search_modestringNoSearch mode: hybrid / embedding / text
    qa_scorenumberYesQA threshold
    llm_usebooleanNoWhether to use an LLM for processing
    metadatastringNoMetadata 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

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)
  • Request Parameters (JSON Body):

    ParameterTypeRequiredDescription
    knowledge_idstringYesUnique knowledge base ID
    querystringYesUser query content
    retrieval_settingobjectYesRetrieval parameter configuration
    metadata_conditionobjectNoMetadata filter condition (reserved and currently ineffective)
  • retrieval_setting fields:

    ParameterTypeRequiredDescription
    top_kintegerYesMaximum number of results returned
    score_thresholdnumberYesRelevance threshold from 0 to 1
    search_typestringNoSearch mode: hybrid / embedding / text, default hybrid
    hybridpipelineUUIDNoAdvanced 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:
error_codeDescription
1001Invalid Authorization header format (expected Bearer <api-key>)
1002Authorization 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.
ScenarioTypical LimitsNotes
Open APIs (for third-party access)10-100 requests/minFor example, WeChat Pay and Alipay Open APIs typically allow 50-200 requests/min depending on the API tier.
Internal System APIs100-1000 requests/minLimits can be relaxed for internal service-to-service calls, but a single service should not consume excessive resources.
User Behavior APIs5-60 requests/minSensitive 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 APIs100-5000 requests/minHigh-frequency query APIs may be relaxed, but caching should be used to reduce database pressure.
High-Concurrency Core APIsDynamic 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.