Help Center/ CloudDevice/ API Reference/ APIs/ Instance Management/ Executing a Synchronization Command

Updated on 2025-10-30 GMT+08:00

View PDF

Executing a Synchronization Command

Function

This API is used to execute a synchronization command for an instance. Before calling this API, ensure that the tenant has purchased an instance. You can call this API to perform ADB operations on your instances.

This API is used for synchronization. If time-consuming ADB operations are performed, you are advised to use the API for executing an asynchronization command for an instance.

URI

POST /v1/instances/sync-command

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
x-request-id	Yes	String	Unique ID of a request.
X-Auth-Token	Yes	String	Tenant-level token.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
command	Yes	String	Command. The value can contain up to 1,024 bytes, including only letters, digits, underscores (_), dots (.), slashes (/), colons (:), and hyphens (-).
instance_ids	Yes	Array of strings	Instance list. A single instance can contain a maximum of 32 characters, and the list can contain a maximum of 100 columns.

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
error_code	String	Response code. The error code specification is KP.API.0001, and the number increases in ascending order.
error_msg	String	Response description.
data	CmdResultWrapper object	Command execution result.

**Table 4** CmdResultWrapper
Parameter	Type	Description
cmd_results	Array of CmdResult objects	Command execution result.

**Table 5** CmdResult
Parameter	Type	Description
instance_id	String	Instance ID.
status	Integer	Task status. 1: running 2: successful -1: failed
error_code	String	Task error code.
error_msg	String	Task error code description.
execute_msg	String	Content returned after a task is executed. The value can contain up to 1,024 bytes. The command output is returned regardless of whether the command is successfully executed.

Status code: 400

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	0: successful. KOOPHONE.API.1000: The request parameter is incorrect. KOOPHONE.API.1001: Insufficient instance permissions. KOOPHONE.API.9999: Internal service error.
error_info	String	Error message.

Status code: 500

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	0: successful. KOOPHONE.API.1000: The request parameter is incorrect. KOOPHONE.API.1001: Insufficient instance permissions. KOOPHONE.API.9999: Internal service error.
error_info	String	Error message.

Example Requests

/v1/instances/sync-command

{
  "command" : "ls -l /system",
  "instance_ids" : [ "a44uhlf7", "efjy72gs" ]
}

Example Responses

Status code: 200

Normal response.

{
  "data" : {
    "cmd_results" : [ {
      "instance_id" : "a44uhlf7",
      "status" : -1,
      "error_code" : "CPS.0191",
      "error_msg" : "Run command failed.",
      "execute_msg" : "ls: cannot access '/system': No such file or directory"
    }, {
      "instance_id" : "efjy72gs",
      "status" : 2,
      "error_code" : "",
      "error_msg" : "",
      "execute_msg" : "xxxxxx"
    } ]
  },
  "error_code" : "0",
  "error_msg" : "ok"
}