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?workspaceId={workspaceId}
  • Request Format: multipart/form-data
  • Request Parameters:
ParameterLocationTypeRequiredDescription
workspaceIdQuerystringYesWorkspace ID of the knowledge base
FilesForm DatabinaryYesFile to upload. For multiple files, repeat the same Files field
fullPathForm DatastringYesFull destination path. This field must not be empty. Use / for root
  • Request Example:
curl -X POST "https://{host}/webapi/knowledge/v1/file/ekb-knowledge-upload?workspaceId=7498998249697599488" \
-H "Authorization: Bearer {token}" \
-F "Files=@./brazil-led-label-compliance-sample.docx" \
-F "fullPath=/"
  • Response Example:
{
"code": 200,
"data": [
{
"id": "7500760195199418368",
"fullName": "brazil-led-label-compliance-sample.docx",
"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.