Access the BuildVu Microservice using cURL

Table of contents

1. Introduction
2. Prerequisites
3. Code Example
4. Configuration Options
5. Upload by URL
6. Using Authentication
7. Further details

Introduction

The following tutorial shows you how to convert PDF files to HTML or SVG using a hosted BuildVu cloud API, such as:

• the IDRsolutions trial server
• the IDRsolutions cloud subscription server
• your own self-hosted BuildVu microservice

All of the above services can be accessed with cURL using the REST API.

Prerequisites

Before you begin you will need to ensure cURL is installed. The set up varies based on your operating system, more details can be found on the curl website.

Code Example

Here is a basic code example to convert PDF files to HTML or SVG. Configuration options and advanced features can be found below.

curl -X POST -F 'input=upload' -F 'file=@myfile.pdf' 'http://exampleURL.com/buildvu'

# Variable token required when connecting to the IDRsolutions trial or cloud subscription servers, example below
curl -X POST -F 'input=upload' -F 'file=@myfile.pdf' -F 'token=Token'  'http://exampleURL.com/buildvu'

The response will be in JSON format containing a uuid.

 {"uuid" : "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"}

You can use to poll the progress of your conversion and retrieve the URL for the output once the conversion is complete.

curl 'http://exampleURL.com/buildvu?uuid=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'

The response will be in JSON format and provided the following details.

 {
     "state" : "processed", 
     "downloadUrl" : "output/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/myfile.zip",
     "previewUrl" : "output/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/myfile/index.html"
 }

You can use the previewURL to preview the output in your browser.

You may also download the converted output using the download URL. This can be done with the following cURL request.

# Download the file to the current directory as it is named, in this case "myfile.zip"
curl 'http://exampleURL.com/buildvu/output/=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/myfile.zip' -LO

# Download the file to the current directory with your own name, in this example we save it as output.zip
curl 'http://exampleURL.com/buildvu/output/=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/myfile.zip' -Lo 'output.zip'

Configuration Options

The BuildVu API accepts a stringified JSON object containing key value pair configuration options to customise your conversion. The settings should be added before the URL in the cURL command. A full list of the configuration options to convert PDF files to HTML or SVG can be found here.

-F 'settings={"key":"value","key":"value"}'

Upload by URL

As well as uploading a local file you can also provide a URL which the BuildVu Microservice will download and then perform the conversion. To do this you should replace the input and file values with the following.

-F 'input=download' -F 'url=http://exampleURL/exampleFile.pdf'

Using Authentication

If you have deployed your own BuildVu Microservice that requires a username and password to convert PDF files to HTML or SVG, you will need to provide them with each conversion. These are provided by adding the user flag with a username and password before the URL.

--user username:password

Further details

Offical cURL website
BuildVu Microservice API
BuildVu Microservice Use