ThermalLabel Web API for Docker

Advanced Barcode Label Generator for Docker

ThermalLabel Web API can be used for designing from simple to complex labels layout supporting Texts, Barcodes, Graphics and Images, RFID Tags, and Shapes like circles, ellipses, rectangles, and lines. It provides an unified object model which will allow you to create one label design and export/convert it to either raw Zebra, EPSON & Honeywell-Intermec, HP PCL printer commands as well as to image or document formats like JPEG/JPG, PNG, PCX, SVG, HTML, and PDF!

It works with any programming language: send an HTTP POST with the label template (JSON, XML or Base64) and optional data, and choose the output format with the Accept header. It runs as a Linux Docker container (amd64 & arm64) on your own servers, Kubernetes cluster or cloud account, so label and customer data never leave your infrastructure. It uses the same label engine and template format as the ThermalLabel SDK for .NET.

ThermalLabel Web Editor Add-on

Design labels from Windows, Linux, Mac & Android!

ThermalLabel Web Editor Add-on is a first-class barcode label designer component for any website which empowers your WebApps by providing an end-user visual label editor!

With the ThermalLabel Web Editor component, you can allow your end-users to create, load, edit and save ThermalLabel objects in the form of XML/JSON template files definition from Windows, Linux, Mac & Android Clients with latest browsers!

How it works with Docker: the container exposes the /ThermalLabelEditor endpoint, which is the server-side backend the editor needs (item rendering, preview, PDF/image export and printer commands), so no .NET server is required. Register the editor license with the EDITOR_LICENSE_OWNER and EDITOR_LICENSE_KEY environment variables and point the editor to the container:

var TLE = Neodynamic.Web.Editor.ThermalLabelEditor;
TLE.websiteRootAbsoluteUrl = "http://localhost:8080";
TLE.thermalLabelWebEditorControllerName = "ThermalLabelEditor";

var editor = new TLE("#editorHost");
editor.enableEditor();

 Download ThermalLabel Web Editor sample project...

IMPORTANT: This label editor is optional and sold separately. You can use the Web API without needing the Web label editor. Learn more about the Web Editor.

Overview

Designed by following some of the REST principles, ThermalLabel Web API for Docker responds to simple HTTP GET & POST requests by specifying the right parameters through a JSON object in the request body, returning the output processing in the raw commands, image or document formats specified through the Accept header.

Help Doc Topics

Download and run ThermalLabel Web API for Docker

ThermalLabel Web API for Docker is available at Docker Hub registry.

• To pull/download the Docker image, please type the following from a Terminal:

  AMD
  docker pull neodynamic/thermallabelwebapi:7.0.1
  ARM
  docker pull neodynamic/thermallabelwebapi:7.0.1-arm64

• To run the Docker image, please type the following from a Terminal:

  AMD
  docker run -it --rm -p 8080:8080 neodynamic/thermallabelwebapi:7.0.1
  ARM
  docker run -it --rm -p 8080:8080 neodynamic/thermallabelwebapi:7.0.1-arm64
   License Registration •  Evaluation Mode Limitations •  Change Log
  
  

  Special Parameters

  • Auto HTTPS Redirection: By default, HTTPS redirection is enabled. It can be disabled by specifying the following parameter -e "USE_HTTPS_REDIRECTION=false"
  • Swagger UI: By default, Swagger UI is enabled. It can be disabled by specifying the following parameter -e "SWAGGER_UI_ENABLED=false"

Run ThermalLabel WebAPI on a Custom Port

By default, our Docker image exposes port 8080 only. If you want to expose and use another different port, then do the following. Note that docker run options such as -e and -u must go before the image name.

1. Let's suppose you want to use port 12345, then run the docker image with the following parameters:
   
   
   AMD

   docker run -it --rm -p 12345:12345 -e ASPNETCORE_HTTP_PORTS=12345 neodynamic/thermallabelwebapi:7.0.1

   ARM

   docker run -it --rm -p 12345:12345 -e ASPNETCORE_HTTP_PORTS=12345 neodynamic/thermallabelwebapi:7.0.1-arm64
2. Special case for port 80: If you need to use port 80, then run the docker image with the following parameters:
   
   
   AMD

   docker run -it --rm -p 80:80 -u root -e ASPNETCORE_HTTP_PORTS=80 neodynamic/thermallabelwebapi:7.0.1

   ARM

   docker run -it --rm -p 80:80 -u root -e ASPNETCORE_HTTP_PORTS=80 neodynamic/thermallabelwebapi:7.0.1-arm64

How To Use It: Samples in Python, Node.js, Java, PHP, C# & more

The following code sends a JSON label template plus a JSON data source to POST /ThermalLabel/Convert and saves the result as a multipage PDF (one page per data row). Change the Accept header to get ZPL, EPL, ESC/POS, Fingerprint, Direct Protocol, PCL, PNG, SVG and more. For all the parameters see the API reference.

•   CURL
•   PHP
•   RUBY
•   PYTHON
•   PERL
•   JAVA
•   C#
•   JS/XHR
•   NODE

                    
# label.json holds the template; jq embeds it as a string
jq -n --rawfile tpl label.json --arg data '[{"ProductName":"Olive Oil","ProductId":"ABC01"},{"ProductName":"Chocolate","ProductId":"ABC02"}]' \
   '{thermalLabel: $tpl, dataSource: $data}' |
curl -X POST "http://localhost:8080/ThermalLabel/Convert" \
     -H "Content-Type: application/json" \
     -H "Accept: application/pdf" \
     --data-binary @- \
     --output labels.pdf
                        
                

                    
$template = <<<'JSON'
{
  "unitType": "Inch", "width": 4, "height": 3, "gapLength": 0.2,
  "items": [
    { "typeName": "TextItem", "x": 0.2, "y": 0.2, "width": 3.6, "height": 0.5,
      "text": "Product Name", "dataField": "ProductName" },
    { "typeName": "BarcodeItem", "x": 0.2, "y": 1, "width": 3.6, "height": 1.5,
      "symbology": "Code128", "code": "ABC01", "dataField": "ProductId",
      "barHeight": 0.75, "barWidth": 0.0104 }
  ]
}
JSON;
$data = '[{"ProductName":"Olive Oil","ProductId":"ABC01"},{"ProductName":"Chocolate","ProductId":"ABC02"}]';

$options = array(
  'http' => array(
    'method'  => 'POST',
    'content' => json_encode(array('thermalLabel' => $template, 'dataSource' => $data)),
    'header'  => "Content-Type: application/json\r\n" .
                 "Accept: application/pdf\r\n"
  )
);

$response = file_get_contents('http://localhost:8080/ThermalLabel/Convert', false, stream_context_create($options));
file_put_contents('labels.pdf', $response);
                        
                

                    
require 'net/http'
require 'uri'
require 'json'

template = <<~'JSON'
{
  "unitType": "Inch", "width": 4, "height": 3, "gapLength": 0.2,
  "items": [
    { "typeName": "TextItem", "x": 0.2, "y": 0.2, "width": 3.6, "height": 0.5,
      "text": "Product Name", "dataField": "ProductName" },
    { "typeName": "BarcodeItem", "x": 0.2, "y": 1, "width": 3.6, "height": 1.5,
      "symbology": "Code128", "code": "ABC01", "dataField": "ProductId",
      "barHeight": 0.75, "barWidth": 0.0104 }
  ]
}
JSON
data = '[{"ProductName":"Olive Oil","ProductId":"ABC01"},{"ProductName":"Chocolate","ProductId":"ABC02"}]'

uri = URI.parse("http://localhost:8080/ThermalLabel/Convert")
header = {'Accept' => 'application/pdf', 'Content-Type' => 'application/json'}

http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = {thermalLabel: template, dataSource: data}.to_json

response = http.request(request)
File.binwrite('labels.pdf', response.body)
                        
                

                    
import requests

template = """{
  "unitType": "Inch", "width": 4, "height": 3, "gapLength": 0.2,
  "items": [
    { "typeName": "TextItem", "x": 0.2, "y": 0.2, "width": 3.6, "height": 0.5,
      "text": "Product Name", "dataField": "ProductName" },
    { "typeName": "BarcodeItem", "x": 0.2, "y": 1, "width": 3.6, "height": 1.5,
      "symbology": "Code128", "code": "ABC01", "dataField": "ProductId",
      "barHeight": 0.75, "barWidth": 0.0104 }
  ]
}"""
data = '[{"ProductName":"Olive Oil","ProductId":"ABC01"},{"ProductName":"Chocolate","ProductId":"ABC02"}]'

response = requests.post(
    "http://localhost:8080/ThermalLabel/Convert",
    json={"thermalLabel": template, "dataSource": data},
    headers={"Accept": "application/pdf"}
)
response.raise_for_status()
with open("labels.pdf", "wb") as f:
    f.write(response.content)
                        
                

                    
use LWP::UserAgent;
use JSON::PP;

my $template = <<'JSON';
{
  "unitType": "Inch", "width": 4, "height": 3, "gapLength": 0.2,
  "items": [
    { "typeName": "TextItem", "x": 0.2, "y": 0.2, "width": 3.6, "height": 0.5,
      "text": "Product Name", "dataField": "ProductName" },
    { "typeName": "BarcodeItem", "x": 0.2, "y": 1, "width": 3.6, "height": 1.5,
      "symbology": "Code128", "code": "ABC01", "dataField": "ProductId",
      "barHeight": 0.75, "barWidth": 0.0104 }
  ]
}
JSON
my $data = '[{"ProductName":"Olive Oil","ProductId":"ABC01"},{"ProductName":"Chocolate","ProductId":"ABC02"}]';

my $ua  = LWP::UserAgent->new;
my $req = HTTP::Request->new(POST => "http://localhost:8080/ThermalLabel/Convert");
$req->header('Content-Type' => 'application/json');
$req->header('Accept' => 'application/pdf');
$req->content(encode_json({ thermalLabel => $template, dataSource => $data }));

my $resp = $ua->request($req);
open(my $fh, '>:raw', 'labels.pdf');
print $fh $resp->content;
close($fh);
                        
                

                    
// Java 15+ (text blocks) and java.net.http, no extra dependencies
String template = """
    {
      "unitType": "Inch", "width": 4, "height": 3, "gapLength": 0.2,
      "items": [
        { "typeName": "TextItem", "x": 0.2, "y": 0.2, "width": 3.6, "height": 0.5,
          "text": "Product Name", "dataField": "ProductName" },
        { "typeName": "BarcodeItem", "x": 0.2, "y": 1, "width": 3.6, "height": 1.5,
          "symbology": "Code128", "code": "ABC01", "dataField": "ProductId",
          "barHeight": 0.75, "barWidth": 0.0104 }
      ]
    }
    """;
String data = "[{\"ProductName\":\"Olive Oil\",\"ProductId\":\"ABC01\"},{\"ProductName\":\"Chocolate\",\"ProductId\":\"ABC02\"}]";

String body = "{\"thermalLabel\":\"" + escape(template) + "\",\"dataSource\":\"" + escape(data) + "\"}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create("http://localhost:8080/ThermalLabel/Convert"))
    .header("Content-Type", "application/json")
    .header("Accept", "application/pdf")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("labels.pdf")));

// minimal JSON string escaping (use Jackson or Gson in real code)
static String escape(String s) {
    return s.replace("\\", "\\\\").replace("\"", "\\\"").replace("\n", "\\n");
}
                        
                

                    
// .NET 7+ (raw string literals). For .NET apps you can also use the ThermalLabel SDK directly.
using var http = new HttpClient();

string template = """
    {
      "unitType": "Inch", "width": 4, "height": 3, "gapLength": 0.2,
      "items": [
        { "typeName": "TextItem", "x": 0.2, "y": 0.2, "width": 3.6, "height": 0.5,
          "text": "Product Name", "dataField": "ProductName" },
        { "typeName": "BarcodeItem", "x": 0.2, "y": 1, "width": 3.6, "height": 1.5,
          "symbology": "Code128", "code": "ABC01", "dataField": "ProductId",
          "barHeight": 0.75, "barWidth": 0.0104 }
      ]
    }
    """;
string data = """[{"ProductName":"Olive Oil","ProductId":"ABC01"},{"ProductName":"Chocolate","ProductId":"ABC02"}]""";

string json = JsonSerializer.Serialize(new { thermalLabel = template, dataSource = data });
var request = new HttpRequestMessage(HttpMethod.Post, "http://localhost:8080/ThermalLabel/Convert")
{
    Content = new StringContent(json, Encoding.UTF8, "application/json")
};
request.Headers.Accept.ParseAdd("application/pdf");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync("labels.pdf", await response.Content.ReadAsByteArrayAsync());
                        
                

                    
// Browser (inside a <script type="module">): preview the first label as PNG
const template = {
  unitType: "Inch", width: 4, height: 3, gapLength: 0.2,
  items: [
    { typeName: "TextItem", x: 0.2, y: 0.2, width: 3.6, height: 0.5,
      text: "Product Name", dataField: "ProductName" },
    { typeName: "BarcodeItem", x: 0.2, y: 1, width: 3.6, height: 1.5,
      symbology: "Code128", code: "ABC01", dataField: "ProductId",
      barHeight: 0.75, barWidth: 0.0104 }
  ]
};
const data = [
  { ProductName: "Olive Oil", ProductId: "ABC01" },
  { ProductName: "Chocolate", ProductId: "ABC02" }
];

const response = await fetch("http://localhost:8080/ThermalLabel/Convert", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Accept": "image/png" },
  body: JSON.stringify({ thermalLabel: JSON.stringify(template), dataSource: JSON.stringify(data) })
});
const blob = await response.blob();
document.getElementById("label").src = URL.createObjectURL(blob);
                        
                

                    
// Node.js 18+ (built-in fetch). Save as convert.mjs (ES module, top-level await)
import fs from "fs";
const template = {
  unitType: "Inch", width: 4, height: 3, gapLength: 0.2,
  items: [
    { typeName: "TextItem", x: 0.2, y: 0.2, width: 3.6, height: 0.5,
      text: "Product Name", dataField: "ProductName" },
    { typeName: "BarcodeItem", x: 0.2, y: 1, width: 3.6, height: 1.5,
      symbology: "Code128", code: "ABC01", dataField: "ProductId",
      barHeight: 0.75, barWidth: 0.0104 }
  ]
};
const data = [
  { ProductName: "Olive Oil", ProductId: "ABC01" },
  { ProductName: "Chocolate", ProductId: "ABC02" }
];

const response = await fetch("http://localhost:8080/ThermalLabel/Convert", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Accept": "application/pdf" },
  body: JSON.stringify({ thermalLabel: JSON.stringify(template), dataSource: JSON.stringify(data) })
});
fs.writeFileSync("labels.pdf", Buffer.from(await response.arrayBuffer()));
                        
                

The Accept Header

The desired output rendering format must be specified through the Accept header. The supported formats are the following:

Web API Reference

Endpoints

POST /ThermalLabel/Convert – request body (ConvertData)

pdfMetadata (PdfMetadata) accepts author, creator, producer, subject, title, useVectorDrawing and rasterEncodingQuality.

POST /ThermalLabel/Thumbnail – request body (ThumbnailData)

ThermalLabel template object

The object you serialize (as JSON or XML) into the thermalLabel field. Every item in items needs a typeName (TextItem, BarcodeItem, ImageItem, RectangleShapeItem, CircleShapeItem, EllipseShapeItem, LineShapeItem, TableShapeItem, RepeaterItem, LiteralItem or RFIDTagItem). BarcodeItem.symbology supports 186 barcode types.

Errors

If the conversion fails (for example, an invalid template or data source), the API returns HTTP 500 with an RFC 7807 ProblemDetails JSON body:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
  "title": "An error occurred while processing your request.",
  "status": 500,
  "detail": "<error message>"
}

Check detail for the cause. Common causes are a template that is not valid JSON/XML, an unknown typeName, or a dataSource that is not a JSON array or XML document.

Interactive Web API Doc (OpenAPI)

The same reference rendered from swagger.json. The container also serves Swagger UI unless you set SWAGGER_UI_ENABLED=false.

How to configure Custom TTF Fonts

Most labels that are designed might contain some texts, and these texts need to be rendered by using a given set of fonts. To make these fonts available for the ThermalLabel Web API for Docker to preview, render and convert the labels to the target format, then a special configuration must be performed.

The following steps show how to configure the ThermalLabel Web API for Docker to add support for Arial Unicode TTF font for rendering texts in different languages.

Custom Fonts Configuration Steps

• Be sure you download the Arial Unicode font (in some Windows systems, that font is located at c:\Windows\Fonts\ARIALUNI.TTF). Remember that any added font remain the exclusive property of their specific owners and require a license from their owners.
• Once you have the ARIALUNI.TTF font file, copy it to the Linux box where the ThermalLabel Web API instance will be running on.
• In the home dir of your Linux box, create the following directory: MyThermalLabelSettings
• Copy the ARIALUNI.TTF to the MyThermalLabelSettings directory
• Create a plain text file and name it to fonts.json and then write or copy/paste the following content:
  
  

  
  [
    {
      "name": "Arial Unicode MS",
      "fileName": "ARIALUNI.TTF"
    }                                
  ]
                              

  
  This is a JSON Array for each font you want to upload to the virtual printer storage. Each JSON object representing a given custom font must be specified with the name of the font (it must be the same font family name specified by the TTF file) and the fileName which points to the physical font file.
  
  
• Finally, to make the custom fonts available in the ThermalLabel Web API instance, we have to mount a volume to the instance in this way:
  
  AMD
  docker run -it -v ~/MyThermalLabelSettings:/app/Config --rm -p 8080:8080 neodynamic/thermallabelwebapi:7.0.1
  ARM
  docker run -it -v ~/MyThermalLabelSettings:/app/Config --rm -p 8080:8080 neodynamic/thermallabelwebapi:7.0.1-arm64

• What about font family and styles like Bold and Italic?

  Font styles must be explicitly specified in the JSON file described above. For example, the following JSON will allow deploying the Arial Narrow Normal, Bold, Italic and Bold + Italic font files:
  
  

  
  [
    {
      "name": "Arial Narrow",
      "fileName": "ARIALN.TTF"
    },
    {
      "name": "Arial Narrow",
      "fileName": "ARIALNB.TTF",
      "bold": true
    },
    {
      "name": "Arial Narrow",
      "fileName": "ARIALNI.TTF",
      "italic": true
    },
    {
      "name": "Arial Narrow",
      "fileName": "ARIALNBI.TTF",
      "bold": true,                            
      "italic": true
    }                                
  ]
                              

Licensing

On-Premise - Full Deployment Control

ThermalLabel Web API is licensed for Private On-Premise environments giving you full control on the infrastructure where our product will run on. Please refer to Licensing model and prices...

 License Registration

When you buy a commercial license of ThermalLabel Web API for Docker, you are provided with license information (LICENSE_OWNER & LICENSE_KEY for the Web API - EDITOR_LICENSE_OWNER & EDITOR_LICENSE_KEY for the Web Label Editor) to register the product. The license information must be specified to the Docker image as environment variables as follows:

Which ThermalLabel Edition Do I Need?

The same label engine and the same XML/JSON label template format are shared by all ThermalLabel products, so a label designed in an editor can be printed with the SDK or converted with the Web API.

Building with .NET? Use the SDK. Any other language, or a microservice architecture? Use the Web API for Docker. Need your end users to design their own labels? Add the Windows Editor (desktop, SDK only) or the Web Editor (browser, SDK or Docker).

ThermalLabel Web API for Docker FAQ

How do I generate ZPL from a JSON label template with a REST API?

Run docker run -p 8080:8080 neodynamic/thermallabelwebapi:7.0.1, then POST a JSON body with the template in the thermalLabel field to http://localhost:8080/ThermalLabel/Convert with the header Accept: application/vnd.zpl. The response is the ZPL code, which you can send raw to a Zebra printer, for example to port 9100.

Which output formats are supported?

Printer commands for Zebra ZPL and EPL, EPSON ESC/POS, Honeywell-Intermec Fingerprint and Direct Protocol, and HP PCL, plus PDF, PNG, JPEG, SVG, PCX and HTML. The format is selected with the Accept header; the +json and +zip variants return every label as a JSON array of Base64 data URIs or as a ZIP file.

How do I print many labels from a database or a list?

Bind text and barcode items to fields with dataField and send the rows in the dataSource field as a JSON array or XML. The API generates one label per row, and counters, data masking and 100+ expressions are applied, so you get a multipage PDF or a single stream of printer commands for the whole batch.

Where do I get the label template?

A template is the ThermalLabel object serialized as JSON or XML. You can write it by hand, export it from the ThermalLabel SDK for .NET with GetJsonTemplate(), let users design it in the ThermalLabel Web Editor, or start from the default objects returned by GET /ThermalLabel and GET /Items/{type}.

Can my users design labels visually with this Web API?

Yes. The ThermalLabel Web Editor (sold separately) can use the Web API container as its backend through the /ThermalLabelEditor endpoint, so no .NET server is needed. Register it with the EDITOR_LICENSE_OWNER and EDITOR_LICENSE_KEY environment variables; a sample project is available on GitHub (neodynamic/ThermalLabel-Web-API-Docker).

Does the Web API send the labels to the printer?

No. It returns the printer commands or documents, and your application sends them to the printer: over TCP port 9100, through a print queue such as CUPS (lpr -o raw), or from the browser to a client printer with JSPrintManager.

Which programming languages can I use?

Any language that can send an HTTP POST with JSON: Python, Node.js, JavaScript, Java, PHP, C#, Go, Ruby, Perl or curl. There is no SDK to install.

Does it run on ARM64 and Kubernetes?

Yes. Images are published for amd64 (neodynamic/thermallabelwebapi:7.0.1) and arm64 (neodynamic/thermallabelwebapi:7.0.1-arm64), and the container can run on any Docker host, Kubernetes cluster or cloud container service.

How do I use custom TrueType fonts?

Copy the TTF files and a fonts.json file that lists each font name, file name and style into a folder, and mount it in the container at /app/Config, for example -v ~/MyThermalLabelSettings:/app/Config.

How is it licensed and how much does it cost?

It is licensed for private on-premise deployments, with the license passed in the LICENSE_OWNER and LICENSE_KEY environment variables. Licenses start at USD 499 and include one year of updates and priority support.

What are the limitations of the evaluation version?

The trial is fully functional and does not expire, but it adds a TRIAL stamp to the output and SVG output is blank. A 30-day evaluation key is available on request to test without those limits.

Should I use the Web API for Docker or the ThermalLabel SDK for .NET?

Use the SDK for .NET applications that need an in-process library or want to print directly to USB, serial or Windows printers. Use the Web API for Docker for any other language, for microservices, or when you want a single label service shared by several applications.

 Latest Release: v7.0.1 2026-10-30

• New! I18N props for Items Display Name.
• Fixed! AutoSize for data-bound TextItem and BarcodeItem.

Full change log (all versions since v1.0) →