URL endpoints and resources
This shows an overview of the authentication settings in the library.
POST
/v1/authentication/passwordPolicy/factoryReset
Reset the password policy
settings back to the factory default.
POST
/v1/authentication/sessionPolicy/factoryReset
Reset the session policy
settings back to factory default.
GET
/v1/authentication/passwordPolicy
Retrieves information about password
policy for local user accounts that are configured on the library.
GET
/v1/authentication/sessions
Retrieves list sessions for user accounts
that are authenticated and logged in to with the library.
GET
/v1/authentication/sessions/{name}
Retrieves list of sessions for
specified user account that is logged in to the library.
GET
/v1/authentication/sessionPolicy
Retrieves the session policy for
sessions logged into the library.
PATCH
/v1/authentication/sessionPolicy {"autoLogout": <minutes|null>, "autoIMCLogin":
<enabled"|"disabled">}
Modify the session policy settings.
Cleaning tape cartridges are a special type of tape cartridge that does not hold data but instead are used to clean the heads of the tape drives. They have a limited number of cleaning cycles they support and must be replaced over time. Typically, the cleaning of tape drives is done automatically by the library. This resource tracks the most recent use for each cleaning cartridge and the number of cleans remaining.
GET
/v1/cleaningCartridges
Retrieves information about all cleaning
cartridges in the tape library.
GET
/v1/cleaningCartridges/<volser>
Retrieves information about the
cleaning cartridge with the specified VOLSER number.
GET
/v1/cleaningCartridges/<internalAddress>
Retrieves information about
the cleaning cartridge with the specified internalAddress.
Data tape cartridges hold information that is written by a host securely and reliably. This information is read from and written to the cartridge by a tape drive.
GET
/v1/dataCartridges
Retrieves information about all host-accessible or
unassigned data cartridges in the tape library. If a data cartridge is removed from the library or
missing during an inventory scan, it does not appear in this list.
GET
/v1/dataCartridges/<internalAddress>
Retrieves information about the
data cartridge with the specified internalAddress.
GET
/v1/dataCartridges/<volser>
Retrieves information about the data
cartridge with the specified VOLSER number.
GET
/v1/dataCartridges/lifetimeMetrics
Retrieves lifetime metrics for the
data cartridges.
GET
/v1/dataCartridges/<internalAddress>/lifetimeMetrics
Retrieves
information about the cartridge with the specified internalAddress.
GET
/v1/dataCartridges/<volser>/lifetimeMetrics
Retrieves information
about the cartridge with the specified VOLSER number.
Diagnostic cartridges are used periodically to test drive performance and troubleshoot problems.
GET
/v1/diagnosticCartridges
Retrieves information about all diagnostic
cartridges in the tape library.
GET
/v1/diagnosticCartridges/<volser>
Retrieves information about the
diagnostic cartridge with the specified VOLSER number.
GET
/v1/diagnosticCartridges/<internalAddress>
Retrieves information
about the diagnostic cartridge with the specified internalAddress.
GET
/v1/diagnosticCartridges/lifetimeMetrics
Retrieves lifetime metrics for
the diagnostic cartridges.
GET
/v1/diagnosticCartridges/<internalAddress>/lifetimeMetrics
Retrieves
information about the cartridge with the specified internalAddress.
GET
/v1/diagnosticCartridges/<volser>/lifetimeMetrics
Retrieves
information about the cartridge with the specified VOLSER number.
Ethernet ports allow network access to the tape library.
GET
/v1/ethernetPorts
Retrieves information about all Ethernet ports in the
tape library.
GET
/v1/ethernetPorts/<location>
Retrieves information about the Ethernet
port in the specified location.
PATCH /v1/ethernetPorts/{location} {"ipv4Address": <IPv4 address>,
"ipv4Subnet": <IPv4 subnet mask>, "ipv4Gateway": <IPv4 gatway address>, "ipv4Assignment":
<"static"|"dynamic">, "ipv4Primary": <IPv4 address>, "ipv4Secondary": <IPv4
address>}
Modifies the IPv4 settings of a Ethernet port. The parameters
are all optional and can be issued separately.
Library events are used to track all resource state changes within the library. The events are also listed in the GUI under the page. The cartridge movement is not a part of the events.
GET
/v1/events
Retrieves a list of all events. Events can be filtered by
date or time range and by a specific library component.
GET
/v1/events/<ID>
Retrieves information about the events with the
specified ID number.
GET
/v1/events/{ID}/fixProcedure
Retrieves fix procedure for the given
error or warning event.
Fibre Channel ports that are installed on the drives allow reading, writing, and library control operations to be passed to the drive and library over the storage area network (SAN). They are identified by their location within the library.
GET /v1/fcPorts
Retrieves information about
all Fibre Channel ports in the tape library.
GET /v1/fcports/{location}
Retrieves
information about the Fibre Channel ports in the specified location.
The frame in a library is the rack that houses all the components of the library and includes the front door, rear door, and side doors (if any).
GET
/v1/frames
Retrieves information about all frames in the tape
library.
GET
/v1/frames/<location>
Retrieves information about the frame in the
specified location.
GUI settings controls the behavior and view of the graphical user interface (GUI) that is used to manage the tape library.
GET
/v1/guiSettings
Retrieves information about the password and session
policy for the library.
I/O stations and magazines are used to insert or remove cartridges from the library without interrupting the operation of the library.
GET /v1/ioStations
Retrieves information about all I/O Stations in the tape library.
GET /v1/iostations/{location}
Retrieves information about the I/O station in the specified location.
The library represents the physical tape library and its current library level settings.
GET
/v1/library
Retrieves information about the library and its
settings.
POST
/v1/library/reset
Restarts the library.
PATCH /v1/library
{"ntpMode": <"enabled|"disabled">, "primaryNtpAddress": <address>, "secondaryNtpAddress":
<address>}
Modifies the settings for the NTP servers and NTP
mode.
GET
/v1/library/saveConfig
Saves the library configuration to a file
external to the library. For the TS4500, this file can be used with the restoreConfiguration
CLI command to restore the library configuration back to what it was before.
PATCH /v1/library
{"name":<new name>}
Sets the user-defined name of the library.
POST
/v1/library/restoreConfigContent-Type: application/octet-streamContent-Length: <length of
file><binary file data>
Restores the library configuration by using
a library configuration data exported earlier from the same library.
POST
/v1/library/prepareForShip
Issued before physical shipment of the
library to ensure cartridges, drives, and other library components are in a safe state during this
process.
PATCH
/v1/library {"time":<time>}
Sets the library time and date.
PATCH/v1/library {"timezone":<time
zone>}
Manually sets the time zone of the library.
PATCH
/v1/library {"capacityUtilThresh": <value>}
Modify the licensed
capacity warning threshold.
PATCH /v1/library
{"location":<install location description>, "address": <install address>, "city": <install
city>, "state": <install state>, "country": <install country>, "contact": <library admin>,
"telephone": <library admin phone>, "secondaryTelephone": <library admin backup
phone>}
Sets library customer information.
The local user accounts allowed to access the GUI, CLI, or REST API when local authentication is enabled.
GET
/v1/authentication/userAccounts
Retrieves the local user accounts that
are configured on this library.
GET
/v1/authenticati/userAccounts/{name}
Retrieves the user account of
specified name.
POST
/v1/authentication/userAccounts{"name": <name>, "role": <role>, "email": <email>,
"password": <password>, "expirePassword": <"yes"|"no">}
Creates a
local user account for the library.
POST
/v1/authentication/userAccounts/{name}/setPassword{"password": <new password or temporary
password>, "expirePassword": <"yes"|"no">}
Change a password for the
user account.
A logical library is a set of tape drives and tape cartridges that are defined as a virtualized library by a user. The ability to partition logical libraries makes it possible for similar and dissimilar hosts (servers) to share a single physical library. As a result, hosts can simultaneously run separate software applications in separate logical libraries.
POST
/v1/logicalLibraries/{name}/volserRanges {"start": <starting VOLSER>, "end": <ending VOLSER>,
"applyNow": <"yes"|"no">}
Adds the given volume serial (VOLSER)
ranges to a logical library.
POST
/v1/logicalLibraries/{name}/assignDataCartridges {"cartridges": [<VOLSER1|internalAddress1>,
<VOLSER2|internalAddress2> ...]}
Assign Data Cartridges directly to
Logical Library
POST
/v1/logicalLibraries/{name}/unassignDataCartridges {"cartridges": [<VOLSER1|internalAddress1>,
<VOLSER2|internalAddress2> ...]}
Unassign Data Cartridges from
Logical Library
POST
/v1/logicalLibraries/{name}/assignDrives {"drives": [<locationOrSN|sn>,
...]}
Assigns drives to the logical library.
POST
/v1/logicalLibraries/{name}/unassignDrives {"drives": [<locationOrSN|sn>,
...]}
Unassign drives from the logical library.
POST /v1/logicalLibraries/<name>/configureEncryption {"method":
<encryption method>}
Configure a logical library for encryption.
POST
/v1/logicalLibraries {"name": <LL name>, "drives": {<locationOrSN|sn>, ...], "mediaType":
<LTO"|"3592">}
Creates a logical library in the library.
GET
/v1/logicalLibraries
Retrieves information about the logical libraries
that are partitioned in the library.
GET
/v1/logicalLibraries/{name}
Retrieves information about the logical
library with the specified name.
GET
/v1/logicalLibraries/{name}/voslerRanges
Retrieves the VOLSER ranges
assigned to a given logical library that is partitioned in the library.
PATCH
/v1/logicalLibraries/{name} {"name": <new name>}
Renames the logical
library.
Logs contain debug information that is used by the IBM Support to ensure they have all the information that they need to troubleshoot and repair tape library components quickly and reliably. These log files are not designed to be directly consumed by users.
POST /v1/logs
{"location": <location>}
Initiates the creation of a log. This
immediately returns the file name of the log.
GET
/v1/logs
Retrieves a list of existing log files.
GET
/v1/logs/<filename>
Retrieves information about the log file with
the specified file name.
GET
/v1/logs/<filename>/export
Exports the log file with the specified
name.
Physical node cards within the library control all aspects of the library's operation.
GET
/v1/nodeCards
Retrieves information about all node cards in the tape
library.
GET
/v1/nodeCards/<ID>
Retrieves information about the specified node
card.
POST
/v1/nodeCards/<ID>/reset
Resets the specified node card.
Power supplies convert standard AC current to the lower voltage DC current used by the library.
GET
/v1/powerSupplies
Retrieves information about all power supplies in the
tape library.
GET
/v1/powerSupplies/<location>
Retrieves information about the power
supplies in the specified location.
The reports contain usage history and other data for resources in the library. The data in the report is presented in a consistent, time centered way and are used to populate graphs or charts.
GET
/v1/reports/library
Retrieves all reports for the last week.
GET
/v1/reports/drives
Retrieves all reports for the last week.
GET
/v1/reports/accessors
Retrieves all reports for the last week.
Robotic accessors move cartridges within the library in response to SCSI commands or manual move requests from the library’s interfaces. The accessor resource includes attributes that describe its two grippers and one bar code reader.
GET
/v1/accessors
Retrieves information about all robotic accessors in the
tape library.
GET
/v1/accessors/<location>
Retrieves information about the robotic
accessor in the specified location.
PATCH
/v1/accessors/<location> {"velocityScalingXY": <value>, "velocityScalingPivot":
<value>}
Adjusts the maximum speed at which an accessor can move.
User roles control how authenticated user accounts are authorized for command execution. The set of actions a user can perform depends on their role.
GET
/v1/authentication/roles
Gets information about all the roles that are
defined in the library.
GET
/v1/authentication/roles/{name}
Gets information about specified name
of the role that is defined in the library.
Serial Attached SCSI (SAS) ports installed on the drives allow reading, writing, and library control operations to be passed to the drive and library over the storage area network (SAN). The TS1160 and model 60S and 70S drives can provide SAS port information.
GET
/v1/sasPorts
Retrieves information about all SAS ports in the tape
library.
GET
/v1/sasPorts/{location}
Retrieves information about the SAS ports in the
specified location.
Cartridge storage slots in the tape library hold one or more tape cartridges. The TS4500 and Diamondback library offers high-density (HD) slots that are designed to greatly increase storage capacity without increasing frame size or required floor space. Each cartridge within a high-density slot stored is said to occupy a tier within in the slot.
GET
/v1/slots
Retrieves information about all storage slots in the tape
library.
GET
/v1/slots/<location>
Retrieves information about the storage slot in
the specified location.
If the library is configured to send syslog (system log) notifications, it sends a notification of each event to the syslog server. The syslog server keeps its own log of events and can be set to filter them, distribute more notifications, or record them in any was as needed. Events sent to Syslog servers can be filtered at the library level by severity level (error, warning, and/or information).
POST
/v1/notification/syslog/servers {"address": <address>, "port": <port>, "subscribed":
["error"|"warning"|"information", ...]}Register a Syslog server with the library to
receive Syslog notifications.
GET
/v1/notification/syslog/servers
Returns the list of Syslog servers that
are registered with the library to receive Syslog notifications and their current settings.
GET
/v1/notification/syslog/servers/{ipAddress}
Returns the list of Syslog
servers for a specified IP address or host name.
PATCH
/v1/notification/syslog/servers/{address} {"address": <address>, "port":
<port>}Modifies the address or port of the syslog server. This is used if there
are network changes that cause these addresses to change or to fix incorrect configurations.
PATCH
/v1/notification/syslog/servers/{address} {"subscribed": ["information" | "warning" | "error",
...]}Modifies the severity of notifications the syslog server is subscribed to
receive. All notifications of the selected verities will be returned.
DELETE
/v1/notification/syslog/servers/{address}Removes the syslog server from the library.
Notifications will no longer be sent to this syslog server.
A tape drive reads data from and writes data to a cartridge mounted in the drive. It communicates over the SCSI interface to the host system. Control path drives handle library actions from the host system. All drives communicate with the library over an internal network.
GET
/v1/drives
Retrieves information about all drives in the tape
library.
GET
/v1/drives/<location>
Retrieves information about the drive in the
specified location.
GET
/v1/drives/<sn>
Retrieves information about the drive with the
specified serial number.
POST
/v1/drives/<location>/clean
Initiates a cleaning operation for the
drive in the specified location.
POST
/v1/drives/<sn>/clean
Initiates a cleaning operation for the drive
with the specified serial number.
PATCH
/v1/drives/<location> {"use": <"access" | "controlPath" |
"verification">}
Modifies the use of the drive in the specified
location (data access, control path, or verification).
PATCH
/v1/drives/<sn> {"use": <"access" | "controlPath" |
"verification">}
Modifies the use of the drive with the specified
serial number (data access, control path, or verification).
POST
/v1/drives/<location>/reset {"mode": <"normal" | "hard">}
Restarts the drive in the specified location.
POST
/v1/drives/<sn>/reset {"mode": <"normal" | "hard">}
Restarts the
drive with the specified serial number.
PATCH
/v1/drives/<location> {"beacon": <"enabled" | "disabled">}
Turns
the beacon on or off.
PATCH
/v1/drives/<sn> {"beacon": <"enabled" | "disabled">}
Turns beacon
on or off for the drive with the specified serial number for the drive at the specified
location.
Tasks are used to submit and monitor asynchronous actions to the library.
Each task describes its type (describes the action being taken), current state (in
progress, completed, failed), and start time. After a
task completes successfully, it is removed from the library and is no longer reported in the task
list. To see the status of completed tasks, use the library event list.
GET
/v1/tasks
Retrieves information about all currently running tasks.
GET
/v1/tasks/<ID>
Retrieves information about the task with the
specified ID number.
POST
/v1/tasks {"type": "inventoryTier0and1", "location": <"library" | "frame_F<f>">}
Runs an inventory
scan on tiers 0 and 1 of the library or the specified frame. This starts a long-running task in the
library that is visible from the GUI.
POST
/v1/tasks [{"type": "inventoryAllTiers", "location": <"library" | "frame_F<f>">}]
Runs an inventory
scan on all tiers of the library or the specified frame. This starts a long-running task in the
library that is visible from the GUI.
POST
/v1/tasks {"type": "startDriveService", "location": "drive_F<f>C<c>R<r>"}
Initiates a service
action on the specified drive. This puts the drive in the inServiceMode state and
starts a long-running task in the library that is visible from the GUI.
POST
/v1/tasks {"type": "startDriveService", "sn": <serial number>}
Initiates a service action on the drive with the specified serial number. This puts the drive in the
inServiceMode state and starts a long-running task in the library that is visible
from the GUI.
POST
/v1/tasks {"type": "completeDriveService", "location": "drive_F<f>C<c>R<r>"}
Completes a service
action on the specified drive. This takes the drive out of the inServiceMode state
and starts a long-running task in the library that is visible from the GUI.
POST
/v1/tasks {"type": "completeDriveService", "sn": <serial
number>}
Completes a service action on the drive with the specified
serial number. This takes the drive out of the inServiceMode state and starts a
long-running task in the library that is visible from the GUI.
POST
/v1/tasks {"type": "calibrateLibrary", "accessor": "
accessor_A<a|b>"}
Runs the calibration task on the library. This starts a long-running task in the
library that is visible from the GUI.
POST /v1/tasks
{"type": "calibrateFrame", “location": "frame_F<f>",
"accessor": “accessor_A<a|b>"}
Runs the calibration task on the given frame. This starts a
long-running task in the library that is visible from the GUI.
POST
/v1/tasks {"type": "calibrateAccessor", "accessor": "accessor_A<a|b>"}
Runs the
calibration task on the given accessor. This starts a long-running task in the library that is
visible from the GUI.
POST
/v1/tasks {"type": "startAccessorService", "accessor": "accessor_A<a|b>"}
Initiates a
service action on the specified accessor. This puts the accessor in the
inServiceMode state and starts a long-running task in the library that is visible
from the GUI.
POST
/v1/tasks {"type": "completeAccessorService", "accessor": ”accessor_A<a|b>"}
Completes a service
action on the specified accessor. This takes the accessor out of the inServiceMode
state and starts a long-running task in the library that is visible from the GUI.
POST /v1/tasks
{"type": "testDrive", "location": "drive_F<f>C<c>R<r>"}
Starts a test drive operation by using a diagnostic cartridge.
This starts a long-running task in the library that is visible from the GUI.
POST /v1/tasks
{"type": "testDrive", "sn": <serial number>}
Starts a test operation
by using a diagnostic cartridge on the drive with the specified serial number. This starts a
long-running task in the library that is visible from the GUI.
POST /v1/tasks
{"type": "updateDriveFirmware", "location":"drive_F<f>C<c>R<r>"}
Content-Type:
application/octet-stream
Content-Length: <length of
file>
<drive firmware image file
data>
Updates the firmware of a drive with specified location.
POST /v1/tasks
{"type": "updateDriveFirmware", "sn": <serial number>}
Content-Type:
application/octet-stream
Content-Length: <length of
file>
<drive firmware image file
data>
Updates the firmware of a drive with specified serial number.
POST /v1/tasks {"type":
"updateLibraryFirmware"}
Content-Type: application/octet-stream
Content-Length: <length of
file>
<library
firmware image file data>Updates the library firmware.
POST /v1/tasks {"type":
"verifyLibrary", "testDrives": <"all"|"none>, "accessor": "accessor_A<a|b>"}
Starts a test that runs cartridge movement tests to verify library health.
Work items represent cartridge move requests within the library. They are stored in the library in a work item queue that the library uses to prioritize moves in the most efficient manner.
POST /v1/workItems {"type": "moveToSlot", "cartridge":
<volser>,"sourceInternalAddress": <internalAddress>,"destinationLocation": <location>}
Moves a cartridge to a slot chosen by the library.
POST /v1/workItems [{"type": "moveToDrive", "cartridge":
<volser>,"sourceInternalAddress": <internalAddress>, "destinationLocation": <location>,
"destinationSN": < serialNumber >}]
Moves a cartridge to the specified drive.
POST /v1/workItems [{"type": "moveToIOStation", "cartridge": <volser>,
"sourceInternalAddress": <internalAddress>, "destinationLocation": <location>}]
Moves a cartridge to an I/O station chosen by the library.