API V3 Specification

API V3 follows RESTful design principles. URLs are resource-oriented, HTTP methods indicate the intended operation, and data is exchanged in JSON format.

---

1. API Components

A complete API request consists of five parts: HTTP method, request URL, authentication, request parameters, and response.

1.1 HTTP Methods

HTTP methods specify the operation to perform on a resource.

Method	Purpose	Description	Example
GET	Retrieve	Retrieves a single resource or a list of resources without modifying them	Get application details, get record details, get logs
POST	Create	Creates a new resource. The server assigns the resource ID. Also used for complex query requests	Create a worksheet, create a record, get a filtered record list
PUT	Replace	Replaces an entire resource. Fields omitted from the request are cleared	—
PATCH	Update	Updates only the specified fields while leaving all others unchanged	Update a record, batch update records
DELETE	Delete	Deletes the specified resource	Delete a worksheet, delete a record, batch delete

1.2 Request URL (Host + URL)

The request URL identifies the target resource. It consists of a Host and a resource path.

https://api.mingdao.com   +   /v3/app/worksheets/{worksheet_id}/rows
        ↑ Host (environment domain)        ↑ URL (resource path)

1.3 Authentication

Authentication verifies the caller's identity and permissions. Credentials are passed in the request headers, and every request must include authentication information.

API V3 supports the following authentication methods:

Method	Header	Description
AppKey + Sign	HAP-Appkey, HAP-Sign	Application key authentication. Created by an administrator and accesses data with application administrator permissions.
PAT	Authorization: Bearer {{access_token}}, HAP-Appid (required for some APIs)	Personal Access Token (PAT). Created by individual users and operates with the user's permissions. Supports configurable expiration and permission scopes.
OAuth 2.0	Authorization: Bearer {{access_token}}, HAP-Appid (required for some APIs)	User authorization through OAuth 2.0. Supports configurable permission scopes, short-lived access tokens, and automatic token refresh.

Comparison of authentication methods:

Category	AppKey + Sign	PAT	OAuth 2.0
Created by	Administrator	Individual user	Integration developer
Operates as	Application administrator	Individual user	Authorized user
Token lifetime	Long-lived	Configurable	Short-lived with automatic refresh
Typical use case	Server-side integrations	Personal scripts or tools	Third-party application integrations

1.4 Request Parameters

Parameter locations vary depending on the HTTP method. API V3 supports three parameter types.

Path Parameters — Resource identifiers embedded in the URL. These are required.

/v3/app/worksheets/{worksheet_id}/rows/{row_id}
                    ↑ Required: worksheet ID      ↑ Required: record ID

Query Parameters — Appended after ? in the URL. Typically used by GET requests for simple query conditions.

GET /v3/app/worksheets/{worksheet_id}/rows/{row_id}?pageSize=50&pageIndex=1

Body Parameters — Sent in the request body (JSON format). Typically used by POST and PATCH requests for complex data.

{
  "fields": [...],
  "triggerWorkflow": true
}

1.5 Response

All API responses are returned in JSON format.

{
  "success": true,       // Indicates whether the request succeeded
  "error_code": 1,       // Error code. `1` indicates success
  "error_msg": "string", // Error message
  "data": {}             // Business data, returned as an object or an array of objects
}

2. Environment Endpoints

Environment	Host
HAP SaaS	https://api.mingdao.com
HAP Server	{private deployment host}/api (Example: https://p-demo.mingdaoyun.cn/api)

3. URL Naming Conventions

URLs are organized around resource hierarchies. The URL path identifies the target resource, while the HTTP method defines the operation.

3.1 Resource Hierarchy

Child resources are nested under their parent resources.

/v3/app                                          # Application (top-level resource)
/v3/app/worksheets                               # Worksheet collection (under application)
/v3/app/worksheets/{worksheet_id}                # Single worksheet
/v3/app/worksheets/{worksheet_id}/rows           # Record collection (under worksheet)
/v3/app/worksheets/{worksheet_id}/rows/{row_id}  # Single record

3.2 CRUD Operations

The combination of the HTTP method and the resource path defines the operation.

GET    /v3/app/worksheets/{worksheet_id}/rows/list       # List records (use POST + /list for complex filters)
GET    /v3/app/worksheets/{worksheet_id}/rows/{row_id}   # Get record details
POST   /v3/app/worksheets/{worksheet_id}/rows            # Create a record
PATCH  /v3/app/worksheets/{worksheet_id}/rows/{row_id}   # Update a record
DELETE /v3/app/worksheets/{worksheet_id}/rows/{row_id}   # Delete a record

3.3 Batch Operations

Batch operations use the collection path with the /batch suffix.

POST    /v3/app/worksheets/{worksheet_id}/rows/batch     # Batch create
PATCH   /v3/app/worksheets/{worksheet_id}/rows/batch     # Batch update
DELETE  /v3/app/worksheets/{worksheet_id}/rows/batch     # Batch delete

3.4 Specialized Operations

Specialized operations append a descriptive endpoint name using lowercase words or hyphen-separated names.

GET  /v3/app/worksheets/{worksheet_id}/rows/pivot                       # Pivot data
POST /v3/app/worksheets/{worksheet_id}/rows/{row_id}/share-link         # Generate a share link
GET  /v3/app/worksheets/{worksheet_id}/rows/{row_id}/logs               # Operation logs
GET  /v3/app/worksheets/{worksheet_id}/rows/{row_id}/discussions        # Discussions
GET  /v3/app/worksheets/{worksheet_id}/rows/{row_id}/relations/{field}  # Related records

4. Parameter Naming Conventions

Location	Naming Convention	Example
Authentication headers	HAP- prefix	HAP-Appkey, HAP-Sign, HAP-Appid
Resource names in paths	Lowercase words or hyphen-separated	app, worksheets, share-link
Resource IDs in paths	Snake case enclosed in braces	{worksheet_id}, {row_id}, {app_id}
Query parameters (GET)	camelCase	pageSize, pageIndex, responseFormat
Body parameters (POST/PATCH)	camelCase	triggerWorkflow, rowIds, fields
Response fields	camelCase	total, pageIndex, pageSize
System fields	_ prefix + camelCase	_createdBy, _owner, _createdAt, _updatedAt

5. Input and Output Structure Conventions

The data field directly returns either an object or an array. Within nested objects, the unique identifier is consistently named id without resource-specific prefixes.

Example 1: Request Object

Within the fields array, the field name is simply name rather than fieldName.

{
  "name": "New Product Catalog",
  "sectionId": "",
  "createDefaultView": false,
  "fields": [
    {
      "name": "Product Name",
      "alias": "",
      "type": "2",
      "required": true,
      "isTitle": true
    },
    {
      "name": "Category",
      "alias": "",
      "type": "11",
      "options": [
        { "value": "Option 1", "index": 1 },
        { "value": "Option 2", "index": 2 }
      ],
      "config": {
        "isColorOptions": true
      }
    }
  ]
}

Example 2: data Returns an Array

Retrieve the worksheet list.

{
  "success": true,
  "error_code": 0,
  "error_msg": "string",
  "data": [
    {
      "id": "string",
      "name": "string",
      "remark": "string"
    }
  ]
}

Example 3: data Returns Nested Objects

Retrieve a record list.

{
  "success": true,
  "error_code": 0,
  "error_msg": "string",
  "data": {
    "rows": [
      {
        "id": "row123",
        "fields": [
          {
            "id": "field1",
            "value": "Sample Value",
            "type": "2",
            "controlName": "Text Field"
          }
        ],
        "_createdBy": {
          "accountId": "user123",
          "fullname": "John Smith"
        },
        "_owner": {
          "accountId": "user123",
          "fullname": "John Smith"
        },
        "_createdAt": "2024-03-25T15:52:58.000Z",
        "_updatedAt": "2024-03-25T15:52:58.000Z",
        "_updatedBy": {
          "accountId": "user123",
          "fullname": "John Smith"
        }
      }
    ],
    "total": 100,
    "pageIndex": 1,
    "pageSize": 20
  }
}

6. System Fields

System fields are maintained automatically by the platform. They all use the _ prefix and do not occupy the namespace for custom fields.

API V3 introduces more descriptive and semantic field names compared with API V2.

Description	V2 Field	V3 Field
Owner	ownerid	_owner
Created By	caid	_createdBy
Created At	ctime	_createdAt
Updated At	utime	_updatedAt
Updated By	uaid	_updatedBy
Process Name	wfname	_processName
Node Assignees	wfcuaids	_nodeAssignees
Initiated By	wfcaid	_initiatedBy
Initiated At	wfctime	_initiatedAt
Node Started At	wfrtime	_nodeStartedAt
Approval Completed At	wfcotime	_approvalCompletedAt
Due At	wfdtime	_dueAt
Remaining Time	wfftime	_remainingTime
Process Status	wfstatus	_processStatus

7. API Reference

Users

API	Method	URL
Get User's Organization List	GET	/v3/orgs/list
Get Current User Info	GET	/v3/users/me

Application Management

API	Method	URL
Get Application List	GET	/v3/apps/list
Create Application	POST	/v3/apps
Get Application Info	GET	/v3/app
Create Application Item Group	POST	/v3/app/sections/batch
Batch Create Application Items	POST	/v3/app/items/batch
Update Application	POST	/v3/app
Delete Application	DELETE	/v3/app

Worksheets

API	Method	URL
Get Worksheet List	POST	/v3/app/worksheets/list
Create Worksheet	POST	/v3/app/worksheets
Get Worksheet Schema	GET	/v3/app/worksheets/{worksheet_id}
Update Worksheet Schema	POST	/v3/app/worksheets/{worksheet_id}/structure
Delete Worksheet	DELETE	/v3/app/worksheets/{worksheet_id}

Records

API	Method	URL
Get Record List	POST	/v3/app/worksheets/{worksheet_id}/rows/list
Get Record Details	GET	/v3/app/worksheets/{worksheet_id}/rows/{row_id}
Create Record	POST	/v3/app/worksheets/{worksheet_id}/rows
Update Record	PATCH	/v3/app/worksheets/{worksheet_id}/rows/{row_id}
Delete Record	DELETE	/v3/app/worksheets/{worksheet_id}/rows/{row_id}
Batch Create Records	POST	/v3/app/worksheets/{worksheet_id}/rows/batch
Batch Update Records	PATCH	/v3/app/worksheets/{worksheet_id}/rows/batch
Batch Delete Records	DELETE	/v3/app/worksheets/{worksheet_id}/rows/batch
Get Related Records	GET	/v3/app/worksheets/{worksheet_id}/rows/{row_id}/relations/{field}
Get Record Pivot Data	POST	/v3/app/worksheets/{worksheet_id}/rows/pivot
Generate Record Share Link	POST	/v3/app/worksheets/{worksheet_id}/rows/{row_id}/share-link
Get Record Logs	GET	/v3/app/worksheets/{worksheet_id}/rows/{row_id}/logs
Get Record Discussions	GET	/v3/app/worksheets/{worksheet_id}/rows/{row_id}/discussions

Views

API	Method	URL
Batch Create Views	POST	/v3/app/worksheets/{worksheet_id}/views/batch

Charts

API	Method	URL
Create Chart	POST	/v3/app/worksheets/{worksheet_id}/charts

Custom Pages

API	Method	URL
Update Custom Page	PUT	/v3/app/custom-pages/{page_id}

Workflows

API	Method	URL
Get Triggered Workflow List	GET	/v3/app/workflow/processes
Get Triggered Workflow Details	GET	/v3/app/workflow/processes/{process_id}
Trigger Workflow	POST	/v3/app/workflow/hooks/{process_id}
Create Workflow	POST	/v3/app/workflows
Batch Create Workflow Nodes	POST	/v3/app/workflows/{workflow_id}/nodes/batch
Delete Workflow Node	DELETE	/v3/app/workflows/{workflow_id}/nodes/{node_id}
Delete Workflow	DELETE	/v3/app/workflows/{workflow_id}
Get Workflow Schema	GET	/v3/app/workflows/{workflow_id}
Validate Workflow	POST	/v3/app/workflows/{workflow_id}/validate
Publish Workflow	POST	/v3/app/workflows/{workflow_id}/publish

Workflow To-dos

API	Method	URL
Get User's Workflow To-do List	GET	/v3/app/workflow/instance/list
Get Approval To-do Details	GET	/v3/app/workflow/instance/{instance_id}
Batch Approve	POST	/v3/app/workflow/instance/batch
Revoke Workflow	POST	/v3/app/workflow/instance/{instance_id}/revoke
Return Workflow	POST	/v3/app/workflow/instance/{instance_id}/return
Terminate Workflow	POST	/v3/app/workflow/instance/{instance_id}/terminate
Nudge Workflow	POST	/v3/app/workflow/instance/{instance_id}/urge

ChatBots

API	Method	URL
Create ChatBot	POST	/v3/app/chatbots

Roles

API	Method	URL
Get Role List	GET	/v3/app/roles
Create Role	POST	/v3/app/roles
Get Role Details	GET	/v3/app/roles/{role_id}
Delete Role	DELETE	/v3/app/roles/{role_id}
Add Role Members	POST	/v3/app/roles/{role_id}/members
Remove Role Members	DELETE	/v3/app/roles/{role_id}/members
Remove User from All Roles	DELETE	/v3/app/roles/users/{user_id}

Vector Knowledge Bases

API	Method	URL
List Vector Knowledge Bases	POST	/v3/app/knowledge/list
Search Vector Knowledge Base	POST	/v3/app/knowledge/search

Organizations

API	Method	URL
Lookup Departments	GET	/v3/departments/lookup
Lookup Regions	GET	/v3/regions/lookup

Others

API	Method	URL
Lookup Orgnization Users	GET	/v3/users/lookup
List Option Sets	GET	/v3/app/optionsets
Create Option Set	POST	/v3/app/optionsets
Update Option Set	PUT	/v3/app/optionsets/{optionset_id}
Delete Option Set	DELETE	/v3/app/optionsets/{optionset_id}

Error Codes

General Error Codes

Error Code	Description
0	Request failed
1	Success
51	Request rate limited
10000	Access denied. IP address is restricted.
10001	Invalid request parameters
10002	Invalid parameter value
10005	Insufficient permission to perform this operation
10006	Data already exists
10007	Data does not exist or has been deleted
10101	Token not found
10102	Invalid signature
10105	User access token has expired or is invalid
10106	User organization access token is restricted
100005	Duplicate field value
100006	Option limit exceeded
100007	Attachment limit exceeded
430013	Worksheet not found in the application
430014	Insufficient field permissions for the worksheet
430017	Application attachment uploads quota exceeded
430018	Draft record limit exceeded
430019	Required field is empty
430020	Invalid subform data
430021	Data does not satisfy business rules
430022	Worksheet not found
90000	Request limit exceeded
99999	Data operation failed

OAuth Error Codes

Category	Error Code	Error Message	Description
Token & Authorization	600100	Access token is invalid or has expired	The access token does not exist, has expired, or has an invalid signature.
Token & Authorization	600101	Authorization has expired. Please authorize again.	The authorization has been revoked, or the requested scope has changed and reauthorization is required.
Token & Authorization	600102	Refresh token is invalid or has expired	The refresh token has expired, been revoked, or can no longer be used.
Token & Authorization	600103	Refresh token cannot be used to obtain a new access token	The authorization has been revoked, or the application is no longer available.
Token & Authorization	600104	Authorization not found	The specified authorization relationship does not exist.
Application Status	600300	Integration application has been disabled	The integration application is in the Disabled state.
Application Status	600302	Integration application is unavailable	The application is unavailable due to an abnormal application state.
Scope & Permissions	600311	Invalid scope requested	The requested scope is not configured or does not exist.
Scope & Permissions	600312	Permissions have changed. Please authorize again.	The application's scope has changed and requires reauthorization.
User Permissions	600320	The current user does not have permission to perform this operation	The token is valid, but the user does not have permission to access the requested resource (for example, the user is not a member of the organization, project, or workspace, or lacks the required role, row-level, or field-level permissions).
Authorization Flow	600000	Invalid authorization request parameters	Invalid parameters were provided to the authorization or token request.
Authorization Flow	600001	redirect_uri does not match	The callback URL does not match the configured redirect URI.
Authorization Flow	600002	Authorization code is invalid or has already been used	The authorization code does not exist, has expired, or has already been consumed.
Authorization Flow	600003	Authorization request was canceled	The user canceled the authorization request.
Authorization Flow	600004	State validation failed	The state parameter validation failed.
Client Credentials	600112	Invalid client credentials	The client_id or client_secret is incorrect.
Client Credentials	600113	Client IP address is not whitelisted	The client IP address is not included in the configured IP whitelist.