Restores

9 routes de l'API publique. Textes de la source : openapi-csp.json du dépôt platform.

Create mssql restore

POST /endpoints/{id}/mssql/restores

Accès : Clé API du MSP, portée operate.

Paramètres

Nom	Emplacement	Type	Obligatoire	Description
id	chemin	string (uuid)	oui

Corps de la requête (application/json)

Nom	Type	Obligatoire	Description
snapshot_id	string	oui
target_endpoint_id	string (uuid)	non	Agent that restores, same client. Absent: the source agent.
instance	string	oui	Instance of the target agent.
items	array of object	oui	Éléments : 1 à 100.
items[].database_name	string	oui	Database of the snapshot; not a system database. Longueur : 1 à 128.
items[].target	object	oui
items[].files	any	non	Refused: the agent picks the files.
safety_full	boolean	non	A full of each replace target before it is overwritten. Off by default, never forced. Défaut : false.
checkdb	boolean	non	DBCC CHECKDB after each restore. Défaut : false.
confirmation_token	string	non	confirmation_token of POST .../mssql/restores/preview for this exact request: required with an OAuth token (MCP), single use. Longueur : 1 à 128.
files	any	non	Refused: the agent picks the files.

Réponses

Code	Description
202	Success
default	Error (400, 401, 403, 404, 409, 415, 422, 429, 500, 502, 503 or 504)

Réponse 202 (application/json)

Nom	Type	Obligatoire	Description
restore_session_id	string (uuid)	oui

Preview mssql restore

POST /endpoints/{id}/mssql/restores/preview

Accès : Clé API du MSP, portée operate.

Paramètres

Nom	Emplacement	Type	Obligatoire	Description
id	chemin	string (uuid)	oui

Corps de la requête (application/json)

Nom	Type	Obligatoire	Description
snapshot_id	string	oui
target_endpoint_id	string (uuid)	non	Agent that restores, same client. Absent: the source agent.
instance	string	oui	Instance of the target agent.
items	array of object	oui	Éléments : 1 à 100.
items[].database_name	string	oui	Database of the snapshot; not a system database. Longueur : 1 à 128.
items[].target_database	string	non	New database name; absent: the api proposes one. Longueur : 1 à 100.
checkdb	boolean	non	DBCC CHECKDB after each restore. Défaut : false.

Réponses

Code	Description
200	Success
default	Error (400, 401, 403, 404, 409, 415, 422, 429, 500, 502, 503 or 504)

Réponse 200 (application/json)

Nom	Type	Obligatoire	Description
request	object	oui	The request the token is bound to.
request.snapshot_id	string	oui
request.target_endpoint_id	string (uuid)	oui
request.instance	string	oui	MSSQLSERVER for the default instance, else the instance name.
request.items	array of object	oui	Éléments : 1 à 100.
request.checkdb	boolean	oui
databases	array of object	oui	Éléments : 1 à 100.
databases[].database_name	string	oui	Database name as SQL Server gives it, 1 to 128 UTF-16 code units. Longueur : 1 à 128.
databases[].target_database	string	oui	New database name: 1 to 100 UTF-16 code units, Unicode letters and digits, _, -, ., space; not a Windows reserved name or a system database. Longueur : 1 à 100.
databases[].target_proposed	boolean	oui	The api chose the name.
databases[].size_bytes	integer | null	oui	Size of the stored backup.
databases[].data_size_bytes	integer | null	oui	Space the database takes on the target.
databases[].recovery_model	"FULL" | "BULK_LOGGED" | "SIMPLE" | null	oui
databases[].server_version	string	oui	SQL Server version of the backup.
snapshot_created_at	string (date-time)	oui
source_endpoint_id	string (uuid)	oui
target_server_version	string	oui	Checked: not older than the version of each backup.
data_size_bytes	integer	oui	Sum of data_size_bytes Valeur minimum : 0.
data_free_bytes	integer | null	oui	Free space of the data volume of the target instance at its last inventory; null if unknown.
confirmation_token	string	oui	Longueur : 1 à 128.
confirmation_expires_at	string (date-time)	oui

List restore sessions

GET /endpoints/{id}/restore-sessions

Accès : Clé API du MSP, portée read.

Paramètres

Nom	Emplacement	Type	Obligatoire	Description
id	chemin	string (uuid)	oui
limit	requête	integer	non	Défaut : 50. Valeur : 1 à 100.
cursor	requête	string	non	Longueur minimum : 1.

Réponses

Code	Description
200	Success
default	Error (400, 401, 403, 404, 409, 415, 422, 429, 500, 502, 503 or 504)

Réponse 200 (application/json)

Nom	Type	Obligatoire	Description
items	array of object	oui
items[].id	string (uuid)	oui
items[].endpoint_id	string (uuid)	oui
items[].repo_id	string (uuid)	oui
items[].opened_at	string (date-time)	oui
items[].expires_at	string (date-time)	oui
items[].closed_at	string (date-time) | null	oui
items[].origin	"agent" | "portal"	non
items[].status	"pending" | "running" | "succeeded" | "partial" | "failed" | "cancelled" | null	non	Null for a CLI session: it is open, closed or expired.
items[].cause	"no_ack" | "stalled" | "agent_restarted" | "cancelled_by_user" | "unknown_order_type" | "restore_busy" | "restore_disabled" | "target_forbidden" | "target_not_directory" | "invalid_order" | "agent_error" | "restore_failed" | null	non
items[].snapshot_id	string | null	non
items[].source_hostname	string	non	Name of the source agent (endpoint_id)
items[].target_endpoint_id	string (uuid) | null	non
items[].target_hostname	string | null	non
items[].target_client_id	string (uuid) | null	non	Client of the target agent: another client than the source's is a Q11 restore.
items[].requested_by	string (uuid) | null	non
items[].requested_by_name	string | null	non	Null if the user was deleted.
items[].request	object | null	non
items[].stats	object | null	non
items[].errors	array of object | null	non	At most 100 file errors. Null for msp_readonly (that role sees the counters, not the paths) and for a call with an OAuth access token (MCP)
items[].error_codes	array of object | null	non	Count per code of the stored file errors (errors, at most 100), most frequent first, without paths: for every role and for an OAuth access token (MCP). Null without stored errors.
items[].progress	object | null	non	Only while running
items[].vm	object | null	non	Restore of a Hyper-V VM; then request and stats are null. Null otherwise.
next_cursor	string | null	oui

Create restore

POST /endpoints/{id}/restores

Accès : Clé API du MSP, portée operate.

Paramètres

Nom	Emplacement	Type	Obligatoire	Description
id	chemin	string (uuid)	oui

Corps de la requête (application/json)

Nom	Type	Obligatoire	Description
snapshot_id	string	oui	Snapshot of the source agent's repo, known to the backend and not forgotten.
paths	array of string	oui	Files or directories of the snapshot, 1 to 1000. ["/"] = the whole snapshot. A path under another one of the list is dropped by the api. Éléments : 1 à 1000.
target_endpoint_id	string (uuid)	non	Agent that restores. Absent: the source agent.
target	object	oui
overwrite	"never" | "if_changed"	non	Défaut : "never".
confirm_cross_client	boolean	non	Required and true when the target agent belongs to another client of the MSP (Q11)
bytes_estimated	integer	non	Size of the selection, if the portal computed it. Information only, not checked. Valeur minimum : 0.

Réponses

Code	Description
202	Success
default	Error (400, 401, 403, 404, 409, 415, 422, 429, 500, 502, 503 or 504)

Réponse 202 (application/json)

Nom	Type	Obligatoire	Description
restore_session_id	string (uuid)	oui

List vm restore targets

GET /endpoints/{id}/vm-restore-targets

Accès : Clé API du MSP, portée read.

Paramètres

Nom	Emplacement	Type	Obligatoire	Description
id	chemin	string (uuid)	oui
snapshot_id	requête	string	oui	Snapshot of a VM or container of the source agent: its configuration version (Hyper-V) or machine version (Proxmox VM) decides config_version_unsupported or machine_version_unsupported

Réponses

Code	Description
200	Success
default	Error (400, 401, 403, 404, 409, 415, 422, 429, 500, 502, 503 or 504)

Réponse 200 (application/json)

Nom	Type	Obligatoire	Description
hypervisor	"hyperv" | "proxmox"	non	Hypervisor of the snapshot. Absent: older backend, Hyper-V.
config_version	string | null	oui	Hyper-V: configuration version of the VM in the last inventory of the source; null if unknown or Proxmox (the agent checks it)
machine	string | null	non	Proxmox VM: machine of the VM in the last inventory of the source (S2 § 6.7); null if unknown, not set or a container (the agent checks it)
items	array of object	oui	Éléments maximum : 500.
items[].endpoint_id	string (uuid)	oui
items[].name	string	oui	Name of the endpoint.
items[].hostname	string | null	oui
items[].source	boolean	oui	The source host or node of the snapshot.
items[].online	boolean	oui
items[].host	object | null	oui	Hyper-V host data of the last inventory: switches, default folder, free space of the volumes. Null for a Proxmox node.
items[].proxmox_host	object | null	non	Proxmox node data of the last inventory: versions, storages, bridges. Null for a Hyper-V host or before the first inventory. Absent: older backend.
items[].unavailable	"target_not_hyperv" | "config_version_unsupported" | "agent_too_old" | "target_agent_deleting" | "agent_offline" | "target_not_proxmox" | "pve_unsupported_version" | "machine_version_unsupported" | null	oui	Null: the host can be the target. Else the 409 that createVmRestore would answer.
items[].tpm	"preserved" | "empty" | null	oui	The TPM of the VM after the restore on this host. Null: the VM has no TPM.
items[].tpm_reason	"guardian_present_on_target" | "guardian_in_backup" | "guardian_not_in_backup" | null	oui	Null if and only if tpm is null.
truncated	boolean	oui	More than 500 agents: the first ones by name.

Preview vm restore

POST /endpoints/{id}/vm-restores/preview

Accès : Clé API du MSP, portée operate.

Paramètres

Nom	Emplacement	Type	Obligatoire	Description
id	chemin	string (uuid)	oui

Corps de la requête (application/json)

Nom	Type	Obligatoire	Description
snapshot_id	string	oui	Snapshot of a VM or a container, known to the backend and not forgotten.
target_endpoint_id	string (uuid)	non	Agent of the same hypervisor that restores. Absent: the source agent.
target_path	string | null	non	Hyper-V only (422 otherwise)
name	string	non	Absent: <name>-restore-<YYYYMMDD> Longueur : 1 à 100.
keep_macs	boolean	non	Défaut : false.
switch	string | null	non	Absent: the switch of each NIC of the source if the target host has it, else not connected (the agent reads the manifest)
start	boolean	non	Défaut : false.
target_storage	string	non	Proxmox only (422 otherwise). An active storage of the target node that accepts images (VM) or rootdir (container), else 409 target_storage_invalid before any write when the inventory of the node is known. Absent: the source storage of each disk, with the same rule.
target_format	"raw" | "qcow2"	non	Proxmox VM only. Absent: qcow2 on a dir storage, raw elsewhere.
bridge	string | null	non	Proxmox only. Absent: the bridge of each source NIC if the target node has it, else link_down=1
confirm_tpm_reset	boolean	non	Proxmox VM with a TPM: required true, else 409 tpm_confirmation_required (S2 § 6.6). The user has the BitLocker recovery key.

Réponses

Code	Description
200	Success
default	Error (400, 401, 403, 404, 409, 415, 422, 429, 500, 502, 503 or 504)

Réponse 200 (application/json)

Nom	Type	Obligatoire	Description
snapshot_id	string	oui
vm_key	string	oui	hyperv:<endpoint id>:<VM GUID> or proxmox:<endpoint id>:<uuid>, lower case.
vm_name	string	oui	Name of the VM in the last inventory of the source host, else the GUID.
captured_at	string (date-time) | null	oui	Point in time of the snapshot; null if the backend has no result for it.
consistency	"app_consistent" | "fs_frozen" | "crash" | "stopped" | null	oui
source_endpoint_id	string (uuid)	oui
target_endpoint_id	string (uuid)	oui
target_name	string	oui	Name of the target endpoint.
same_host	boolean	oui
name	string	oui	Name of the new VM. Longueur : 1 à 100.
target_path	string | null	oui	Null: the default folder of the disks of the target host.
switch	string | null	non	Null: NICs not connected. Absent: the switch of each source NIC if the target host has it, else not connected.
keep_macs	boolean	oui
start	boolean	oui
hypervisor	"hyperv" | "proxmox"	non	Absent: Hyper-V (answers before Proxmox)
kind	"vm" | "ct"	non	Proxmox: vm or ct (container). Absent: vm
target_storage	string | null	non	Proxmox: the storage of the new disks; null, the source storage of each disk.
target_format	"raw" | "qcow2" | null	non	Proxmox VM: null, the default of the storage.
bridge	string | null	non	Proxmox: null, NICs with link_down=1. Absent: the bridge of each source NIC if the target node has it.
bytes	integer | null	oui	Bytes of the disk files of the snapshot (read at backup); null if unknown.
free_bytes	integer | null	oui	Free bytes of the target volume (Hyper-V) or of the target storage (Proxmox, when all the disks go to one storage) in the last inventory of the target; null if unknown.
space_ok	boolean | null	oui	free_bytes >= bytes x 1.1; null if unknown (the agent checks it: restore_no_space)
tpm	"preserved" | "empty" | null	oui	The TPM of the VM after the restore on this host. Null: the VM has no TPM.
tpm_reason	"guardian_present_on_target" | "guardian_in_backup" | "guardian_not_in_backup" | null	oui	Null if and only if tpm is null.
warnings	array of "tpm_other_host" | "keep_macs_source_running" | "space_unknown" | "ct_static_ip_source_running"	oui	tpm_other_host: tpm is empty (another host without the guardian, none in the snapshot), BitLocker in the guest asks for its recovery key. keep_macs_source_running: the MACs are kept and the source VM runs: address conflict on the same network. ct_static_ip_source_running: the container has a fixed IP address and the source runs: the new container gets the same address, address conflict on the same bridge. Do not start it after the restore: change its address first.
confirmation_token	string	non	Through MCP only.
confirmation_expires_at	string (date-time)	non

Create vm restore

POST /endpoints/{id}/vm-restores

Accès : Clé API du MSP, portée operate.

Paramètres

Nom	Emplacement	Type	Obligatoire	Description
id	chemin	string (uuid)	oui

Corps de la requête (application/json)

Nom	Type	Obligatoire	Description
snapshot_id	string	oui	Snapshot of a VM or a container, known to the backend and not forgotten.
target_endpoint_id	string (uuid)	non	Agent of the same hypervisor that restores. Absent: the source agent.
target_path	string | null	non	Hyper-V only (422 otherwise)
name	string	non	Absent: <name>-restore-<YYYYMMDD> Longueur : 1 à 100.
keep_macs	boolean	non	Défaut : false.
switch	string | null	non	Absent: the switch of each NIC of the source if the target host has it, else not connected (the agent reads the manifest)
start	boolean	non	Défaut : false.
confirmation_token	string	non	Through MCP only, and then required: the confirmation_token of previewVmRestore for this exact request Longueur : 1 à 128.
target_storage	string	non	Proxmox only (422 otherwise). An active storage of the target node that accepts images (VM) or rootdir (container), else 409 target_storage_invalid before any write when the inventory of the node is known. Absent: the source storage of each disk, with the same rule.
target_format	"raw" | "qcow2"	non	Proxmox VM only. Absent: qcow2 on a dir storage, raw elsewhere.
bridge	string | null	non	Proxmox only. Absent: the bridge of each source NIC if the target node has it, else link_down=1
confirm_tpm_reset	boolean	non	Proxmox VM with a TPM: required true, else 409 tpm_confirmation_required (S2 § 6.6). The user has the BitLocker recovery key.

Réponses

Code	Description
202	Success
default	Error (400, 401, 403, 404, 409, 415, 422, 429, 500, 502, 503 or 504)

Réponse 202 (application/json)

Nom	Type	Obligatoire	Description
restore_session_id	string (uuid)	oui

Get restore session

GET /restore-sessions/{id}

Accès : Clé API du MSP, portée read.

Paramètres

Nom	Emplacement	Type	Obligatoire	Description
id	chemin	string (uuid)	oui

Réponses

Code	Description
200	Success
default	Error (400, 401, 403, 404, 409, 415, 422, 429, 500, 502, 503 or 504)

Réponse 200 (application/json)

Nom	Type	Obligatoire	Description
id	string (uuid)	oui
endpoint_id	string (uuid)	oui
repo_id	string (uuid)	oui
opened_at	string (date-time)	oui
expires_at	string (date-time)	oui
closed_at	string (date-time) | null	oui
origin	"agent" | "portal"	non
status	"pending" | "running" | "succeeded" | "partial" | "failed" | "cancelled" | null	non	Null for a CLI session: it is open, closed or expired.
cause	"no_ack" | "stalled" | "agent_restarted" | "cancelled_by_user" | "unknown_order_type" | "restore_busy" | "restore_disabled" | "target_forbidden" | "target_not_directory" | "invalid_order" | "agent_error" | "restore_failed" | null	non
snapshot_id	string | null	non
source_hostname	string	non	Name of the source agent (endpoint_id)
target_endpoint_id	string (uuid) | null	non
target_hostname	string | null	non
target_client_id	string (uuid) | null	non	Client of the target agent: another client than the source's is a Q11 restore.
requested_by	string (uuid) | null	non
requested_by_name	string | null	non	Null if the user was deleted.
request	object | null	non
stats	object | null	non
errors	array of object | null	non	At most 100 file errors. Null for msp_readonly (that role sees the counters, not the paths) and for a call with an OAuth access token (MCP)
error_codes	array of object | null	non	Count per code of the stored file errors (errors, at most 100), most frequent first, without paths: for every role and for an OAuth access token (MCP). Null without stored errors.
progress	object | null	non	Only while running
vm	object | null	non	Restore of a Hyper-V VM; then request and stats are null. Null otherwise.

Cancel restore session

POST /restore-sessions/{id}/cancel

Accès : Clé API du MSP, portée operate.

Paramètres

Nom	Emplacement	Type	Obligatoire	Description
id	chemin	string (uuid)	oui

Réponses

Code	Description
202	Success
default	Error (400, 401, 403, 404, 409, 415, 422, 429, 500, 502, 503 or 504)

Réponse 202 (application/json)

Nom	Type	Obligatoire	Description
id	string (uuid)	oui
endpoint_id	string (uuid)	oui
repo_id	string (uuid)	oui
opened_at	string (date-time)	oui
expires_at	string (date-time)	oui
closed_at	string (date-time) | null	oui
origin	"agent" | "portal"	non
status	"pending" | "running" | "succeeded" | "partial" | "failed" | "cancelled" | null	non	Null for a CLI session: it is open, closed or expired.
cause	"no_ack" | "stalled" | "agent_restarted" | "cancelled_by_user" | "unknown_order_type" | "restore_busy" | "restore_disabled" | "target_forbidden" | "target_not_directory" | "invalid_order" | "agent_error" | "restore_failed" | null	non
snapshot_id	string | null	non
source_hostname	string	non	Name of the source agent (endpoint_id)
target_endpoint_id	string (uuid) | null	non
target_hostname	string | null	non
target_client_id	string (uuid) | null	non	Client of the target agent: another client than the source's is a Q11 restore.
requested_by	string (uuid) | null	non
requested_by_name	string | null	non	Null if the user was deleted.
request	object | null	non
stats	object | null	non
errors	array of object | null	non	At most 100 file errors. Null for msp_readonly (that role sees the counters, not the paths) and for a call with an OAuth access token (MCP)
error_codes	array of object | null	non	Count per code of the stored file errors (errors, at most 100), most frequent first, without paths: for every role and for an OAuth access token (MCP). Null without stored errors.
progress	object | null	non	Only while running
vm	object | null	non	Restore of a Hyper-V VM; then request and stats are null. Null otherwise.