Skip to content
Documentation/OPEN API

Approval Open API

Requires purchasing and enabling the Approval Center extension module.

Last updated

Approval Open API

  • Production base URL: https://open.musedam.ai/api/muse
  • Approval path: /approval-api
  • Full endpoint: POST https://open.musedam.ai/api/muse/approval-api
  • Availability: This API is available only after purchasing and enabling the Approval Center extension module.

Request conventions

  • Method: POST
  • Content-Type: application/json
  • Body must be valid JSON
  • Use service to select the capability
  • Include header: Authorization: Bearer your_api_key

Supported service values:

  • subscriptionQuery
  • subscriptionChange
  • listTemplates
  • createApproval
  • taskStatusQuery

Unified response

json
{
"code": "0",
"message": "success",
"result": {},
"traceId": "trace_xxx"
}

Common error codes:

  • 400: invalid payload
  • 401: authentication failed
  • 403: permission denied
  • 404: resource not found
  • 500: internal error

listTemplates

Path: /approval-api

Request parameters:

FieldTypeRequiredDescription
serviceStringYesFixed value: listTemplates

Response (result): an array of templates.

FieldTypeDescription
idStringTemplate ID
nameStringTemplate name
descriptionStringTemplate description
enabledBooleanWhether the template is enabled
usageCountNumberNumber of uses
autoImportEnabledBooleanWhether auto-import is enabled
targetFolderObject | nullTarget folder for auto-import
workflowArrayApproval workflow node definitions

Request:

json
{
"service": "listTemplates"
}

result is an array of templates with fields such as: id, name, description, enabled, usageCount, autoImportEnabled, targetFolder, workflow.

curl:

bash
curl --location --request POST 'https://open.musedam.ai/api/muse/approval-api' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"service": "listTemplates"
}'

createApproval

Path: /approval-api

Request parameters:

FieldTypeRequiredDescription
serviceStringYesFixed value: createApproval
templateIdStringYesApproval template ID
createdByStringYesInitiator user ID
assetsArrayConditionalRequired if groups/groupList is not provided; normal asset list (>=1)
groupsArrayConditionalRequired if top-level assets is not provided; grouped assets
groupListArrayConditionalCompatibility alias of groups; required if top-level assets is not provided
sourceContextObjectNoBusiness context
reasonStringNoSubmission reason

assets[] fields:

FieldTypeRequiredDescription
nameStringYesAsset name; original filename is recommended
urlStringYesPublicly accessible http/https URL
sizeNumberNoFile size in bytes
mimeTypeStringNoMIME type
extensionStringNoFile extension

groups[] / groupList[] fields:

FieldTypeRequiredDescription
groupIdStringYesGroup ID
groupNameStringNoGroup name
coverAssetIdStringNoCover asset ID
assetsArrayNoAsset list under this group; takes precedence when provided

groups[i].assets[] fields:

FieldTypeRequiredDescription
nameStringYesAsset name
urlStringYesPublicly accessible http/https URL
sizeNumberNoFile size in bytes
mimeTypeStringNoMIME type
extensionStringNoFile extension

Response fields:

FieldTypeDescription
taskIdStringApproval task ID

Required fields:

  • templateId
  • createdBy
  • assets (or groups/groupList; at least one source is required)
  • assets[].url must be a public http/https URL
  • groups / groupList for grouped approvals:
    • groupId is required for each group
    • groupName, coverAssetId, and nested assets are optional
    • if both top-level assets and groups/groupList are provided, the task is treated as mixed subject (mixed_assets)

Request example:

json
{
"service": "createApproval",
"templateId": "101",
"createdBy": "10086",
"assets": [
{
"name": "demo.mp4",
"url": "https://cdn.example.com/m/asset_1.mp4"
}
]
}

Success example:

json
{
"code": "0",
"message": "success",
"result": {
"taskId": "9527"
}
}

curl:

bash
curl --location --request POST 'https://open.musedam.ai/api/muse/approval-api' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"service": "createApproval",
"templateId": "101",
"createdBy": "10086",
"assets": [
{
"name": "demo.mp4",
"url": "https://cdn.example.com/m/asset_1.mp4"
}
]
}'

curl (grouped assets approval):

bash
curl --location --request POST 'https://open.musedam.ai/api/muse/approval-api' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"service": "createApproval",
"templateId": "101",
"createdBy": "10086",
"groups": [
{
"groupId": "group_10001",
"groupName": "New KV Group",
"assets": [
{
"assetId": "asset_1",
"name": "demo.mp4",
"url": "https://cdn.example.com/m/asset_1.mp4"
}
]
}
]
}'

taskStatusQuery

Path: /approval-api

Request parameters:

FieldTypeRequiredDescription
serviceStringYesFixed value: taskStatusQuery
taskIdStringYesApproval task ID (positive integer)

Response fields:

FieldTypeDescription
taskIdStringTask ID
statusStringPENDING / PROCESSING / APPROVED / REJECTED / CANCELED
statusLabelStringStatus label
progressPercentNumberProgress percentage
currentNodeNameString | nullCurrent node name
currentNodeSignModeString | nullCurrent node sign mode (and / or)
currentNodeProgressObjectCurrent node progress summary
currentNodeApproversArrayCurrent node approver status list
operatorString | nullLatest operator
updatedAtStringLast updated time (ISO)

Request:

json
{
"service": "taskStatusQuery",
"taskId": "9527"
}

result.status values: PENDING | PROCESSING | APPROVED | REJECTED | CANCELED.

curl:

bash
curl --location --request POST 'https://open.musedam.ai/api/muse/approval-api' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"service": "taskStatusQuery",
"taskId": "9527"
}'

Note (grouped assets query): grouped approval tasks are queried via the same taskStatusQuery; pass the grouped task taskId.

curl (query grouped approval task):

bash
curl --location --request POST 'https://open.musedam.ai/api/muse/approval-api' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"service": "taskStatusQuery",
"taskId": "9527"
}'

Subscription and callbacks

Query subscription status (subscriptionQuery)

Path: /approval-api

Request parameters:

FieldTypeRequiredDescription
serviceStringYesFixed value: subscriptionQuery

Response fields:

FieldTypeDescription
subscribedBooleanWhether subscription is active
callbackUrlString | nullCurrent callback URL
updatedAtString | nullLast updated time (ISO)

Check subscription:

json
{
"service": "subscriptionQuery"
}

curl:

bash
curl --location --request POST 'https://open.musedam.ai/api/muse/approval-api' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"service": "subscriptionQuery"
}'

Change subscription (subscriptionChange)

Path: /approval-api

Request parameters:

FieldTypeRequiredDescription
serviceStringYesFixed value: subscriptionChange
operationStringNoADD or DELETE; default is ADD
callbackUrlStringConditionalRequired when operation = ADD; must be http/https

Response fields:

FieldTypeDescription
resultBooleantrue means subscribed, false means unsubscribed

Add subscription:

json
{
"service": "subscriptionChange",
"operation": "ADD",
"callbackUrl": "https://example.com/webhook/approval"
}

Cancel subscription:

json
{
"service": "subscriptionChange",
"operation": "DELETE"
}

curl (ADD):

bash
curl --location --request POST 'https://open.musedam.ai/api/muse/approval-api' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"service": "subscriptionChange",
"operation": "ADD",
"callbackUrl": "https://example.com/webhook/approval"
}'

curl (DELETE):

bash
curl --location --request POST 'https://open.musedam.ai/api/muse/approval-api' \
--header 'Authorization: Bearer your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"service": "subscriptionChange",
"operation": "DELETE"
}'

Callback payload specification

After subscriptionChange with operation = ADD succeeds, approval state changes are posted to your callbackUrl.

Callback request basics

  • Method: POST
  • Content-Type: application/json

Callback body:

json
{
"eventId": "evt_xxx",
"eventType": "APPROVAL",
"eventTime": "1760258885000",
"payload": {
"eventName": "TASK_APPROVED",
"orgId": "233",
"taskId": "9527",
"taskStatus": "APPROVED"
}
}

Field notes:

FieldTypeDescription
eventIdStringUnique event id (recommended idempotency key)
eventTypeStringAlways APPROVAL
eventTimeStringMillisecond timestamp string
payloadObjectBusiness payload

Common payload fields

Every callback payload contains at least:

FieldTypeDescription
eventNameStringEvent name
orgIdStringOrganization ID (system populated)
taskIdStringApproval task ID
taskStatusStringPROCESSING / APPROVED / TIMEOUT

Full event set

eventNameTrigger
NODE_STARTEDTriggered when a node starts (first node, normal transition, or resubmit transition)
APPROVER_SUBMITTEDTriggered when an approver submits a decision (can happen multiple times in one node)
NODE_COMPLETEDTriggered when a node is completed (approved/rejected)
NODE_TRANSFERREDTriggered when flow transfers to another node (normal, resubmit, timeout transfer)
SUBMITTER_RESUBMITTEDTriggered when submitter resubmits assets in resubmit step
TASK_APPROVEDTriggered when the task reaches final approved status
NODE_TIMEOUTTriggered when a node times out (timeout transfer or pending reassignment)

Field definitions

payload.node
FieldTypeDescription
nodeIdStringNode ID (always present)
nodeOrderNumberNode order (present in some events)
nodeRoleStringnormal / resubmit_submitter / resubmit_approver (event-specific)
nodeStatusStringCommon values: pending / processing / approved / rejected / timeout_transferred / re_assigned
signModeStringand / or (event-specific)
approverCountNumberApprover count (event-specific)
approversArrayApprover results on NODE_COMPLETED; item fields: id, name, status
startedAtStringNode start time (ISO)
completedAtStringNode completion time (ISO)
timeoutHoursNumberTimeout threshold in hours (timeout events)
payload.approver (APPROVER_SUBMITTED)
FieldTypeDescription
idStringApprover user ID
nameStringApprover name
decisionStringapproved / rejected
commentStringApproval comment
submittedAtStringSubmitted time (ISO)
payload.submitter (SUBMITTER_RESUBMITTED)
FieldTypeDescription
idStringSubmitter user ID
nameStringSubmitter name
commentStringResubmission comment
submittedAtStringSubmitted time (ISO)
payload.timeout
FieldTypeDescription
transferToObject | nullTimeout transfer target; when present: { "id": "...", "name": "..." }, otherwise null
payload.latestAssets (SUBMITTER_RESUBMITTED)
FieldTypeDescription
assetIdStringAsset ID
filePathIdStringFile path ID
versionNumberAsset version
oldStorePathStringPrevious storage path
newStorePathStringNew storage path
updatedAtStringUpdated time (ISO)
payload.transferReason (NODE_TRANSFERRED)
EnumDescription
NEXT_NODENormal transition to the next approval node
RESUBMIT_SUBMITTERTransition to submitter resubmission node
RESUBMIT_APPROVERTransition to approver re-review node after resubmission
TIMEOUT_TRANSFERTransition after timeout transfer

Callback examples (all events)

TASK_APPROVED:

json
{
"eventId": "evt_2a93f5f5f4d64907a2f3b73cb8f0f201",
"eventType": "APPROVAL",
"eventTime": "1760258885000",
"payload": {
"eventName": "TASK_APPROVED",
"orgId": "233",
"taskId": "9527",
"taskStatus": "APPROVED",
"operator": {
"id": "10086",
"name": "张三"
},
"finishedAt": "2026-10-12T08:08:05.000Z"
}
}

NODE_STARTED:

json
{
"eventId": "evt_d3a39140643a4d73afedf0a47c0a601d",
"eventType": "APPROVAL",
"eventTime": "1760258700000",
"payload": {
"eventName": "NODE_STARTED",
"orgId": "233",
"taskId": "9527",
"taskStatus": "PROCESSING",
"node": {
"nodeId": "12001",
"nodeOrder": 1,
"nodeRole": "normal",
"nodeStatus": "processing",
"signMode": "and",
"approverCount": 2,
"startedAt": "2026-10-12T08:05:00.000Z"
}
}
}

APPROVER_SUBMITTED:

json
{
"eventId": "evt_8bc9f92f83564f10adf8270b598f95d2",
"eventType": "APPROVAL",
"eventTime": "1760258820000",
"payload": {
"eventName": "APPROVER_SUBMITTED",
"orgId": "233",
"taskId": "9527",
"taskStatus": "PROCESSING",
"node": {
"nodeId": "12001",
"nodeOrder": 1,
"nodeStatus": "processing",
"signMode": "and"
},
"approver": {
"id": "10086",
"name": "张三",
"decision": "approved",
"comment": "同意",
"submittedAt": "2026-10-12T08:07:00.000Z"
},
"approverCount": 2
}
}

NODE_COMPLETED:

json
{
"eventId": "evt_652d4d8c09d24477af9fdb21624fd070",
"eventType": "APPROVAL",
"eventTime": "1760258855000",
"payload": {
"eventName": "NODE_COMPLETED",
"orgId": "233",
"taskId": "9527",
"taskStatus": "PROCESSING",
"node": {
"nodeId": "12001",
"nodeOrder": 1,
"nodeStatus": "approved",
"signMode": "and",
"approvers": [
{
"id": "10086",
"name": "张三",
"status": "approved"
},
{
"id": "10087",
"name": "李四",
"status": "approved"
}
],
"completedAt": "2026-10-12T08:07:35.000Z"
}
}
}

NODE_TRANSFERRED (normal transition):

json
{
"eventId": "evt_21881077723e4a17aa4e2e58ee78ce79",
"eventType": "APPROVAL",
"eventTime": "1760258856000",
"payload": {
"eventName": "NODE_TRANSFERRED",
"orgId": "233",
"taskId": "9527",
"taskStatus": "PROCESSING",
"transferReason": "NEXT_NODE",
"fromNode": {
"nodeId": "12001",
"nodeOrder": 1,
"nodeStatus": "approved"
},
"node": {
"nodeId": "12002",
"nodeOrder": 2,
"nodeRole": "normal",
"nodeStatus": "pending"
}
}
}

NODE_TRANSFERRED (rejected -> resubmit):

json
{
"eventId": "evt_e612f8b5e1de4960bb712d3df18e2617",
"eventType": "APPROVAL",
"eventTime": "1760258900000",
"payload": {
"eventName": "NODE_TRANSFERRED",
"orgId": "233",
"taskId": "9527",
"taskStatus": "PROCESSING",
"transferReason": "RESUBMIT_SUBMITTER",
"fromNode": {
"nodeId": "12001",
"nodeOrder": 1,
"nodeStatus": "rejected"
},
"node": {
"nodeId": "13001",
"nodeOrder": 2,
"nodeRole": "resubmit_submitter",
"nodeStatus": "pending"
}
}
}

NODE_TRANSFERRED (resubmit -> re-review):

json
{
"eventId": "evt_f0c43dd5ca5d4fca9e4adbe536fbb8f5",
"eventType": "APPROVAL",
"eventTime": "1760259005000",
"payload": {
"eventName": "NODE_TRANSFERRED",
"orgId": "233",
"taskId": "9527",
"taskStatus": "PROCESSING",
"transferReason": "RESUBMIT_APPROVER",
"fromNode": {
"nodeId": "13001",
"nodeOrder": 2,
"nodeStatus": "approved"
},
"node": {
"nodeId": "13002",
"nodeOrder": 3,
"nodeRole": "resubmit_approver",
"nodeStatus": "pending"
}
}
}

NODE_TIMEOUT (transferred on timeout):

json
{
"eventId": "evt_b0d67fb6f3de42e79a60b8f9df6ad20d",
"eventType": "APPROVAL",
"eventTime": "1760260000000",
"payload": {
"eventName": "NODE_TIMEOUT",
"orgId": "233",
"taskId": "9527",
"taskStatus": "TIMEOUT",
"node": {
"nodeId": "12002",
"nodeStatus": "timeout_transferred",
"timeoutHours": 24
},
"timeout": {
"transferTo": {
"id": "10100",
"name": "王五"
}
}
}
}

NODE_TIMEOUT (not transferred):

json
{
"eventId": "evt_2e4372871f0c4a7eb95a9d7c638de8a0",
"eventType": "APPROVAL",
"eventTime": "1760260100000",
"payload": {
"eventName": "NODE_TIMEOUT",
"orgId": "233",
"taskId": "9527",
"taskStatus": "TIMEOUT",
"node": {
"nodeId": "12002",
"nodeStatus": "re_assigned",
"timeoutHours": 24
},
"timeout": {
"transferTo": null
}
}
}

SUBMITTER_RESUBMITTED:

json
{
"eventId": "evt_5d017db5b458443697f6c10d5f6370df",
"eventType": "APPROVAL",
"eventTime": "1760259000000",
"payload": {
"eventName": "SUBMITTER_RESUBMITTED",
"orgId": "233",
"taskId": "9527",
"taskStatus": "PROCESSING",
"node": {
"nodeId": "12002",
"nodeOrder": 3,
"nodeStatus": "approved",
"signMode": "and"
},
"submitter": {
"id": "10010",
"name": "李四",
"comment": "已更新素材,重新提交",
"submittedAt": "2026-10-12T08:10:00.000Z"
},
"latestAssets": [
{
"assetId": "asset_1",
"filePathId": "30001",
"version": 3,
"oldStorePath": "assets/old/asset_1_v2.mp4",
"newStorePath": "assets/new/asset_1_v3.mp4",
"updatedAt": "2026-10-12T08:10:00.000Z"
}
],
"latestAssetCount": 1
}
}

NODE_TRANSFERRED (after timeout transfer):

json
{
"eventId": "evt_15f4348dd4f34a4b9d51ec93313f4dff",
"eventType": "APPROVAL",
"eventTime": "1760260001000",
"payload": {
"eventName": "NODE_TRANSFERRED",
"orgId": "233",
"taskId": "9527",
"taskStatus": "PROCESSING",
"transferReason": "TIMEOUT_TRANSFER",
"node": {
"nodeId": "12002",
"nodeStatus": "timeout_transferred"
},
"timeout": {
"transferTo": {
"id": "10100",
"name": "王五"
}
}
}
}

Event sequence (key flows)

Delivery is at-least-once. Use eventId for idempotent processing.

Normal pass (multi-node)
  1. NODE_STARTED (first node)
  2. APPROVER_SUBMITTED (may repeat for each approver)
  3. NODE_COMPLETED
  4. If next node exists: NODE_TRANSFERRED -> NODE_STARTED
  5. Repeat 2-4 until final node is complete
  6. TASK_APPROVED
Rejected then resubmitted
  1. APPROVER_SUBMITTED (decision = rejected)
  2. NODE_COMPLETED (nodeStatus = rejected)
  3. NODE_TRANSFERRED (transferReason = RESUBMIT_SUBMITTER)
  4. NODE_STARTED (nodeRole = resubmit_submitter)
  5. SUBMITTER_RESUBMITTED
  6. NODE_COMPLETED (resubmission node)
  7. NODE_TRANSFERRED (transferReason = RESUBMIT_APPROVER)
  8. NODE_STARTED (re-review node)
  9. Back to normal approval flow (APPROVER_SUBMITTED ...)
Timeout transfer / no transfer
  1. Node timeout triggers NODE_TIMEOUT (taskStatus = TIMEOUT)
  2. If timeout transfer target exists: NODE_TRANSFERRED (transferReason = TIMEOUT_TRANSFER) and task returns to PROCESSING
  3. If no transfer target: only NODE_TIMEOUT (commonly nodeStatus = re_assigned) until manual follow-up
MuseDAM Developer PlatformAPI · Integrations · MCP
    Approval Open API | MuseDAM Developers