API Reference

Magnus Box API Reference

The following API endpoints require an administrative account. This can be your login to the web dashboard, or you can request a dedicated administrative account for the API by emailing support. Note: Usage of the API is at your own risk. Any damage or deletion of data is solely your responsibility. If you have any questions about a particular endpoint, please contact our support channel before proceeding.

Endpoints

AdminAccountProperties: Retrieve properties about the current admin account 

Some key parameters are obscured, but the obscured values are safely recognised by the corresponding AdminAccountSetProperties API.

• Endpoint: POST /api/v1/admin/account/properties
• Return type: AdminAccountPropertiesResponse (JSON), or APIResponseMessage (JSON) on failure

AdminAccountRegenerateTotp: Generate a new TOTP secret 

The secret is returned as a data-uri image of a QR code. The new secret is immediately applied to the current admin account.

• Endpoint: POST /api/v1/admin/account/regenerate-totp
• Return type: TotpRegeneratedResponse (JSON), or APIResponseMessage (JSON) on failure

AdminAccountSessionRevoke: Revoke a session key (log out) 

• Endpoint: POST /api/v1/admin/account/session-revoke
• Return type: APIResponseMessage (JSON)

AdminAccountSessionStart: Generate a session key (log in)

• Endpoint: POST /api/v1/admin/account/session-start
• Return type: SessionKeyRegeneratedResponse (JSON), or APIResponseMessage (JSON) on failure

AdminAccountSetProperties: Update settings for your own admin account

Updating your account password requires you to supply your current password. To set a new plaintext password, use a password format of 0 (PASSWORD_FORMAT_PLAINTEXT). This API does not currently allow you to modify your TOTP secret or IP whitelist.

• Endpoint: POST /api/v1/admin/account/set-properties (>= 18.9.9)
• Return type: APIResponseMessage (JSON)

AdminAddUser: Add a new user account

• Endpoint: POST /api/v1/admin/add-user
• Return type: APIResponseMessage (JSON)

AdminAddUserFromProfile: Add a new user account (with all information)

This allows you to create a new account and set all its properties at once (e.g. during account replication). Developers creating a signup form may find it simpler to use the AdminAddUser and AdminGetUserProfile / AdminSetUserProfile APIs separately.

You must supply administrator authentication credentials to use this API. This API requires the Auth Role to be enabled.

• Endpoint: POST /api/v1/admin/add-user-from-profile
• Return type: APIResponseMessage (JSON)

AdminDeleteUser: Delete user account 

This does not remove any storage buckets. Unused storage buckets will be cleaned up by the Constellation Role. Any stored data can not be decrypted without the user profile. Misuse can cause data loss! This also allows to uninstall software from active devices under the user account

• Endpoint: POST /api/v1/admin/delete-user
• Return type: APIResponseMessage (JSON)

AdminDispatcherApplyRetentionRules: Instruct a live connected device to apply retention rules now

• Endpoint: POST /api/v1/admin/dispatcher/apply-retention-rules (>= 17.6.9)
• Return type: APIResponseMessage (JSON)

AdminDispatcherListActive: List live connected devices

• Endpoint: POST /api/v1/admin/dispatcher/list-active
• Return type: Dictionary<string, LiveUserConnection> (JSON), or APIResponseMessage (JSON) on failure

AdminDispatcherRequestStoredObjects: Request a list of stored objects inside an existing backup job 

The remote device must have given consent for an MSP to browse their files.

• Endpoint: POST /api/v1/admin/dispatcher/request-stored-objects (>= 19.3.0)
• Return type: DispatcherStoredObjectsResponse (JSON), or APIResponseMessage (JSON) on failure

AdminDispatcherRequestVaultSnapshots: Request a list of Storage Vault snapshots from a live connected device

• Endpoint: POST /api/v1/admin/dispatcher/request-vault-snapshots
• Return type: DispatcherVaultSnapshotsResponse (JSON), or APIResponseMessage (JSON) on failure

AdminDispatcherRunBackup: Instruct a live connected device to run a scheduled backup

• Endpoint: POST /api/v1/admin/dispatcher/run-backup
• Return type: APIResponseMessage (JSON)

AdminDispatcherRunBackupCustom: Instruct a live connected device to run a backup

• Endpoint: POST /api/v1/admin/dispatcher/run-backup-custom
• Return type: APIResponseMessage (JSON)

AdminDispatcherRunRestore: Instruct a live connected device to perform a local restore 

• Endpoint: POST /api/v1/admin/dispatcher/run-restore (>= 17.9.3)
• Return type: APIResponseMessage (JSON)

AdminDispatcherRunRestoreCustom: Instruct a live connected device to perform a local restore

• Endpoint: POST /api/v1/admin/dispatcher/run-restore-custom (>= 18.6.0)
• Return type: APIResponseMessage (JSON)

AdminDispatcherUninstallSoftware: Instruct a live connected device to self-uninstall the software

• Endpoint: POST /api/v1/admin/dispatcher/uninstall-software (>= 20.3.5)
• Return type: APIResponseMessage (JSON)

AdminDispatcherUpdateSoftware: Instruct a live connected device to download a software update

• Endpoint: POST /api/v1/admin/dispatcher/update-software
• Return type: APIResponseMessage (JSON)

AdminGetJobLog: Get the report log entries for a single job, in plaintext format 

• Endpoint: POST /api/v1/admin/get-job-log
• Return type: Body in text/plain encoding, or APIResponseMessage (JSON) on failure

AdminGetJobsForCustomSearch: Get jobs (for custom search)

The jobs are returned in an unspecified order.

• Endpoint: POST /api/v1/admin/get-jobs-for-custom-search (>= 18.9.2)
• Return type: List<BackupJobDetail> (JSON), or APIResponseMessage (JSON) on failure

AdminGetJobsForUser: Get jobs (for user)

The jobs are returned in an unspecified order.

• Endpoint: POST /api/v1/admin/get-jobs-for-user
• Return type: List<BackupJobDetail> (JSON), or APIResponseMessage (JSON) on failure

AdminGetUserProfile: Get user account profile 

• Endpoint: POST /api/v1/admin/get-user-profile
• Return type: UserProfileConfig (JSON), or APIResponseMessage (JSON) on failure

AdminListUsers: List all user accounts

• Endpoint: POST /api/v1/admin/list-users
• Return type: List<string> (JSON), or APIResponseMessage (JSON) on failure

AdminListUsersFull: List all user account profiles

• Endpoint: POST /api/v1/admin/list-users-full
• Return type: Dictionary<string, UserProfileConfig> (JSON), or APIResponseMessage (JSON) on failure

AdminMetaVersion: Get server properties 

Retrieve the version number and basic properties about the server.

• Endpoint: POST /api/v1/admin/meta/version
• Return type: ServerMetaVersionInfo (JSON), or APIResponseMessage (JSON) on failure

AdminRequestStorageVault: Request a new Storage Vault on behalf of a user

This action does not respect the "Prevent creating new Storage Vaults (via Request)" policy setting. New Storage Vaults can be requested regardless of the policy setting.

• Endpoint: POST /api/v1/admin/request-storage-vault (>= 18.6.2)
• Return type: RequestStorageVaultResponseMessage (JSON), or APIResponseMessage (JSON) on failure

AdminRequestStorageVaultProviders: Get the available options for Requesting a Storage Vault

• Endpoint: POST /api/v1/admin/request-storage-vault-providers (>= 18.6.2)
• Return type: Dictionary<string, string> (JSON), or APIResponseMessage (JSON) on failure

AdminRevokeDevice: Revoke device from user account 

It's possible to simply remove the Device section from the user's profile, however, using this dedicated API will also gracefully handle live connections.

• Endpoint: POST /api/v1/admin/revoke-device
• Return type: APIResponseMessage (JSON)

AdminSetUserProfile: Modify user account profile

• Endpoint: POST /api/v1/admin/set-user-profile
• Return type: APIResponseMessage (JSON)

Structures

AdminAccountPropertiesResponse

class AdminAccountPropertiesResponse {
    string               OrganizationID
    AdminUserPermissions Permissions
    AdminSecurityOptions Security
}

AdminSecurityOptions

class AdminSecurityOptions {
    int                        PasswordFormat
    string                     Password
    bool                       AllowPasswordLogin
    bool                       AllowPasswordAndTOTPLogin
    bool                       AllowPasswordAndU2FLogin
    List<AdminU2FRegistration> U2FRegistrations // Omission from JSON document implies an empty array
    int                        TOTPKeyEncryptionFormat // Omission from JSON document implies 0
    string                     TOTPKey // Omission from JSON document implies empty string
    string                     IPWhitelist // Omission from JSON document implies empty string
}

AdminUF2Registration

class AdminU2FRegistration {
    string     Description
    int        RegisterTime
    List<byte> Registration
}

AdminUserPermissions

class AdminUserPermissions {
    bool PreventEditServerSettings // Omission from JSON document implies false
    bool PreventServerShutdown // Omission from JSON document implies false
    bool PreventChangePassword // Omission from JSON document implies false
    bool AllowEditBranding // Omission from JSON document implies false
    bool AllowEditRemoteStorage // Omission from JSON document implies false
}

APIResponseMessage

class APIResponseMessage {
    int    Status
    string Message
}

BackupJobAdvancedOptions

class BackupJobAdvancedOptions {
    bool SkipAlreadyRunning
    int  StopAfter
    int  LimitVaultSpeedBps
    bool ReduceDiskConcurrency
    bool UseOnDiskIndexes
    bool AllowZeroFilesSuccess
}

BackupJobDetail

class BackupJobDetail {
    string            GUID
    string            Username
    int               Classification
    int               Status
    int               StartTime
    int               EndTime
    string            SourceGUID
    string            DestinationGUID
    string            DeviceID
    string            SnapshotID // Omission from JSON document implies empty string
    string            ClientVersion
    int               TotalDirectories
    int               TotalFiles
    int               TotalSize
    int               TotalChunks
    int               UploadSize
    int               DownloadSize
    string            CancellationID // Omission from JSON document implies empty string
    BackupJobProgress Progress // Omission from JSON document implies zero-initialised BackupJobProgress class instance
}

BackupJobProgress

class BackupJobProgress {
    int Counter
    int SentTime
    int RecievedTime
    int BytesDone
    int ItemsDone
}

DestinationConfig

class DestinationConfig {
    string                Description
    int                   CreateTime
    int                   ModifyTime
    List<string>          PreExec
    List<string>          ThawExec
    List<string>          PostExec
    int                   EncryptionKeyEncryptionMethod
    string                EncryptedEncryptionKey
    int                   RepoInitTimestamp
    bool                  StorageLimitEnabled
    int                   StorageLimitBytes
    DestinationStatistics Statistics // Omission from JSON document implies zero-initialised DestinationStatistics class instance
    RetentionPolicy       DefaultRetention
    bool                  RebrandStorage
}<br>

DispatcherStoredObjectsResponse

class DispatcherStoredObjectsResponse extends APIResponseMessage {
    List<StoredObject> StoredObjects
}

DispatcherVaultSnapshotsResponse

class DispatcherVaultSnapshotsResponse extends APIResponseMessage {
    List<VaultSnapshot> Snapshots
}<br>

LiveUserConnection

class LiveUserConnection {
    string Username
    string DeviceID
    string ReportedVersion
    string ReportedPlatform
    OSInfo ReportedPlatformVersion // Omission from JSON document implies zero-initialised OSInfo class instance
    string IPAddress // Omission from JSON document implies empty string
    int    ConnectionTime
    bool   AllowsFilenames
}

OSInfo

class OSInfo {
    string version // Omission from JSON document implies empty string
    string distribution // Omission from JSON document implies empty string
    string build // Omission from JSON document implies empty string
}<br>

RequestStorageVaultResponseMessage

class RequestStorageVaultResponseMessage extends APIResponseMessage {
    string DestinationID
}<br>

RestoreJobAdvancedOptions

class RestoreJobAdvancedOptions {
    int          Type
    bool         OverwriteExistingFiles
    string       DestPath
    List<string> ExactDestPaths
    int          ArchiveFormat
}

SearchClause

class SearchClause {
    string             ClauseType
    string             RuleField
    string             RuleOperator
    string             RuleValue
    List<SearchClause> ClauseChildren // Omission from JSON document implies an empty array
}

ServerMetaVersionInfo

class ServerMetaVersionInfo {
    string       Version
    string       VersionCodename
    bool         StorageRole
    bool         AuthenticationRole
    bool         SoftwareBuildRole
    bool         OverseerRole
    bool         ConstellationRole
    List<string> ExperimentalOptions // Omission from JSON document implies an empty array
    int          ServerStartTime
    string       ServerStartHash
    int          CurrentTime
    string       ServerLicenseHash
    int          LicenseValidUntil
    int          EmailsSentSuccessfully
    int          EmailsSentErrors
    int          EmailsWaitingInQueue
    int          ScheduledEmailThreadCurrentState
    int          ScheduledEmailThreadLastCalculateDurationNanos
    int          ScheduledEmailThreadWaitingUntil
    int          ScheduledEmailThreadLastWakeTime
    bool         ScheduledEmailThreadLastWakeSentEmails
}<br>

SessionKeyRegeneratedResponse

class SessionKeyRegeneratedResponse extends APIResponseMessage {
    string SessionKey
    string SessionType
}<br>

SourceConfig

class SourceConfig {
    string                              Engine
    string                              Description
    string                              OwnerDevice
    int                                 CreateTime
    int                                 ModifyTime
    List<string>                        PreExec
    List<string>                        ThawExec
    List<string>                        PostExec
    Dictionary<string, string>          EngineProps
    Dictionary<string, RetentionPolicy> OverrideDestinationRetention // Omission from JSON document implies an empty Dictionary
    SourceStatistics                    Statistics // Omission from JSON document implies zero-initialised SourceStatistics class instance
}

SourceStatistics

class SourceStatistics {
    BackupJobDetail LastBackupJob
}

StoredObject

class StoredObject {
    string name
    int    mtime
    string type
    string subtree
    int    size
    bool   r // Omission from JSON document implies false
    int    f // Omission from JSON document implies 0
    int    b // Omission from JSON document implies 0
    int    d // Omission from JSON document implies 0
}

TotpRegeneratedResponse

class TotpRegeneratedResponse extends APIResponseMessage {
    string Image
    string URL
    string ProfileHash
}

UninstallConfig

class UninstallConfig {
    bool UninstallFlag
    bool RemoveConfigFile
}

UserProfileConfig

class UserProfileConfig {
    string                                      Username
    string                                      AccountName
    string                                      LocalTimezone
    string                                      LanguageCode
    string                                      OrganizationID // Omission from JSON document implies empty string
    List<string>                                Emails
    Dictionary<string, UserCustomEmailSettings> OverrideEmailSettings
    bool                                        SendEmailReports
    Dictionary<string, DestinationConfig>       Destinations
    Dictionary<string, SourceConfig>            Sources
    Dictionary<string, BackupRuleConfig>        BackupRules
    Dictionary<string, DeviceConfig>            Devices
    bool                                        IsSuspended
    bool                                        AllProtectedItemsQuotaEnabled
    int                                         AllProtectedItemsQuotaBytes
    int                                         MaximumDevices
    string                                      PolicyID
    UserPolicy                                  Policy
    int                                         PasswordFormat
    string                                      PasswordHash
    string                                      PasswordRecovery // Omission from JSON document implies empty string
    bool                                        AllowPasswordLogin
    bool                                        AllowPasswordAndTOTPLogin
    int                                         TOTPKeyEncryptionFormat
    string                                      TOTPKey
    bool                                        RequirePasswordChange
    int                                         CreateTime
    string                                      CreationGUID
}

VaultSnapshot

class VaultSnapshot {
    string Snapshot
    string Source
    int    CreateTime
}