Available BarTender Cloud REST APIs

BarTender Cloud has four APIs available for use: Actions, Librarian, Printers, and Security.

Certain API calls, such as submitting POST and PATCH requests for Actions API scripts, may require an account with Administrator or Actions API Administrator role permissions. See Managing User Roles for more information on creating and managing user roles.

Actions API

The BarTender Cloud Actions API tells the BarTender Cloud to automate or update print jobs. While this resembles the BarTender REST API and has similar actions, the BarTender Cloud Actions API can only take calls in YAML and has actions limited by what is deemed safe to do in a cloud environment. Database actions and actions such as Execute SQL will be missing from the API. For a full list, see the BarTender Cloud API Reference section of this documentation.

In addition to printing labels, the Actions API can retrieve information about actions currently running and perform some actions on folders and files, though most folder tasks are handled by the Librarian API.

ClosedReliance on other APIs

If you don't know the exact location of a resource or the proper address, you can use other APIs to find the information for you.

  • Use the Librarian API for file location information

  • Use the Print API to find the printer name and information

As these are separate APIs, you will need more than one call to retrieve the needed information. If you already know it, you can skip the extra calls and make the action call right away.

Librarian API

The Librarian API is the REST API that works with files and folders stored within BarTender Cloud's Librarian spaces. You can think of it as the file and folder manager via API calls. This API has access to Librarian spaces and, if your subscription include Spaces, can work with files and folders in any of them. The Librarian API does not print documents.

ClosedLibrarian URIs

The Librarian space has its own set of URIs that can identify a file or folder, plus any additional information needed to retrieve the correct version item from within the Librarian, such as in which space the file or folder is located. The URIs are not only used in the Librarian API but also in the Actions API to reference any file stored in Librarian space. File URIs are used by both APIs but folder URIs are generally used only by the Librarian API.

The general syntax for a URI is

librarian://<space>/<path>[?parameter1=value1&parameter2=value2]

Values and parameters can be chained at the end using an &. The ? is only needed if parameters are present.

The two spaces always present are main and $temp. If your subscription includes Spaces, there may be addition, user-defined spaces storing files and folders as well.

ClosedExample URIs

Main space

librarian://Main/Shipping/Label.btw

librarian://Main/MyLabel.btw?version=3

$temp space

librarian://$temp/Work/File.txt

librarian://$temp/label.btw

Custom space

librarian://Warehouse/East/LabelEast.btw

librarian://Warehouse/AnotherLabel.btw?version=2

ClosedWhere Are Label Files Stored in Librarian?

Librarian handles all the file storage for BarTender Cloud. Each tenant space has its own Librarian space, and the size is determined by the subscription. By default, Librarian space can be broken up into two main spaces:

  • Main. Librarian's main storage space. What is visible to the user (depending on administration settings) and seen in the Librarian

  • $temp. Temporary storage, invisible, and generally used by the REST API (usually the Actions API).

If your subscription includes Spaces, you can also add user-defined spaces to Librarian and store files and folders there as well. These custom spaces are also available to the REST API.

Tenants include a third default space called $system. However, this space should not be visible to users and is used by BarTender Cloud to store configuration data pertinent to each tenant.

The two major Librarian spaces breakdown this way:

Main $temp
  • Permanent storage
  • Visible in the web interface
  • Supports files and folders
  • Versioned
  • Temporary storage
  • Hidden
  • Supports files and folders
  • Versionless

Main Space

The main space is the primary storage space in Librarian. When you open Librarian, all the files and folders here are stored in the main space. This space is generally managed by the Librarian via the web interface but can also be managed using the Librarian API.

User-Defined Spaces

If your subscription includes the ability to create user-defined spaces, then files and folders may be stored in these spaces and in the main space. User-defined spaces can also be accessed using the Librarian API.

The main and user-defined spaces are versioned, so each revision of a file is stored in the space as well. These versions can be referenced via the API.

$Temp Space

The $temp space behaves very similarly to how $temp on a PC or the temporary storage on an Integration would work. This space is invisible and is only accessible using an API call. The primary user of the $temp space is the Actions API. Any files and folders within $temp can be accessed using the Librarian API.

Unlike the main space, $temp space is versionless, and files and folders simply exist as they are.

At the moment, there is no garbage collector in the $temp space. This means that files in $temp space stay there until they are manually deleted. A garbage collector is planned for the future, but at the moment, users must clean up their own $temp litter.

ClosedFiles and Folders

Files

Files are the main occupants of Librarian spaces. In addition to containing all the BarTender information, they also have their own attachments. Attachments are information and details connected to a certain label and stored with it. Attachments can include (but are not limited to):

  • Metadata.Who created the file; when was the file created; etc.

  • Tags. Category tags like the ones you see in the Document Assistant.

  • Preview. A preview of the label.

Folders

Folders can be added to all spaces and can contain files, folders, or both. Folders are not required in Librarian but are useful for organizing files.

Restrictions

Files and folders have additional attachments to them that include permissions and restrictions. Both have the following restrictions which can be set:

  • Read

  • Write

  • Delete

  • Purge

In addition to these, folders also have a List permission, which lists the contents of a folder.

Deleting and Restoring

File/folder deletion and restoration are asynchronous operations. This means a deleted file might appear to be stuck in the cloud for a short period (in reality, the file has been deleted but the UI hasn't updated yet). Refreshing the UI will show the current deletion or restoration status.

Printers API

The Printers API (sometimes called Print Management API) handles everything associated with printers. This includes querying connected printers, obtaining printer information, and printing job statuses. This API also enables you to query print history.

Many of the API calls are handled by the Print Controller service, which communicates with the Print Gateway service running locally on client computers.

ClosedPrinter IDs

Printer IDs are a unique means to identify a printer within a tenant space. Each printer is identified by the client's name + the printer name

printer:<clientname>/<printer_name>

For example, if a Zebra was a networked printer and connected to multiple clients, each client would have their own ID for this same printer. So the printer could appear as printer:mariopc/Zebra_105, printer:luigipc/Zebra_105, and printer:bowserpc/Zebra105 to uniquely identify which client is going to print to this printer. These IDs do not affect licensing since licensing is not determined by printer, so there is no duplication. Printer IDs are simply an identification to tell the Print Controller service where to send the print job.

ClosedA Special Note About Local Printers and Tokens

Printers are only available in the Printers API if a client has logged into the BarTender Cloud and configured their Print Gateway. To use printers on a specific client system, the client must log into the cloud at least once to establish a connection. This configuration is done automatically if you install the Print Gateway from the Print dialog in BarTender Cloud itself.

  • If you installed the Print Gateway via installer, not from the BarTender Cloud Print dialog, you will need to log into BarTender Cloud at least once and open the Print dialog for the Print Gateway to be configured.

    Opening the Print dialog will cause BarTender Cloud to communicate with the locally installed Print Gateway and automatically populate the token field.

You can access this user access token from the Print Gateway Settings page (http://localhost:5952/settings).

  1. On the BarTender Print Gateway Settings page, click .

  2. Click .

  3. BarTender displays the User Access Token dialog which contains the current access token

These tokens will impersonate the user currently logged into BarTender Cloud and as such should only be added on trusted computers.

Security API

The Security API manages users, permissions, group management, and role management.

Security works a little differently in BarTender Cloud than in on-prem BarTender. The key difference is that there is no concept of a Deny permission.

On-prem BarTender has a concept of Deny, which overwrites any Allow permission for a particular user as long as that Deny is there (whether it is from a group or explicitly set on the user itself). This sets the user's effective permission as Always Deny even if something is allowed elsewhere.

BarTender Cloud does not have anything so explicit and instead operates on an allowed or not allowed permission system. BarTender Cloud creates a union of all sources (roles, groups, individual settings) to determine if a user is allowed an action or not. If a user is allowed to do something in one group, it is allowed to do that thing even if another one of the user's groups does not have an allow permission set. For example, if User A belongs to the Document Management group (which can manage documents) but also belongs to the Print Operator group (which only has permissions to print), User A has permissions to manage documents because it is included in one of the groups.

ClosedRole Management

Roles are essentially containers for permissions. These permissions are assigned to all users contained within that specific role.

Roles are assigned to groups and users to set their permissions. These permissions can be used to set permissions on files in the web interface or via the API. They also can control whether users or groups have access to specific APIs.

ClosedUser Management

Using the BarTender Cloud REST API you to do the following:

  • Create a user

  • Delete a user

  • Update user information