API workflow

This guide will allow you to understand how to interact with the Visual PDF API through 3 simple steps: creating a file processing pipeline, executing the pipeline, downloading files.

1. Creating a pipeline

First, what exactly is a pipeline?

In the Visual PDF API, a pipeline corresponds to the description of a processing to be carried out on one or more files, through one or more tasks. It also describes different options, such as the format of the resulting files (zip, file names, etc.) and the waiting mode (should the request wait for the end of processing to return a result, or should it return a result as soon as possible and carry out processing in the background).

Using a pipeline rather than just a single task allows you to combine different tools and thus increase your possibilities tenfold. Obviously, it is entirely possible to use only one tool in your pipeline, without combining it with other tasks.

How pipelines work, their limitations and their options are more fully described in this guide.

Pipeline description

For the API to know what you want to do, it needs instructions. As we have just seen, these instructions are defined in the description of a pipeline.

Pipelines must be sent with a multipart/form-data encoding type. JavaScript for instance allows us to send data with this format via the FormData object. You can build manually the FormData (as shown in the following example) or simply bind it to a form HTML element.

Let's see a basic pipeline example:

    
      // Creating the form data for the pipeline
      const form = new FormData();

      // Adding PDF files (instances of the JavaScript File class)
      form.append('file-1', myFirstFile);
      form.append('file-2', mySecondFile);

      // Describing the pipeline tasks
      const tasks = [
        // For the 2 files, duplicate the first and last pages
        {
          tool: 'duplicate-pages',
          options: { pages: [0, 'last'] },
        },
        // Compress the resulting PDFs
        {
          tool: 'compress',
        },
      ];

      // Adding tasks description to the form data
      form.append('tasks', tasks);
    
  

That's it! We have built the pipeline description, saved into a JavaScript FormData object. This pipeline will upload 2 files, duplicate their first and last pages, compress the resulting files, and finally save them, waiting for them to be downloaded.

2. Executing the pipeline

Now that we have built our pipeline, we can send it to the Visual PDF API in order to process it.

Let's see how to do this, using the JavaScript Fetch API:

    
      // Executing the pipeline by calling the API endpoint
      const pipelineResponse = await fetch(
        'https://api.visualpdf.com/v1/process',
        {
          method: 'POST',
          body: form,
          headers: {
            Authorization: `Bearer ${your_API_key}`,  // Don't forget to replace ${your_API_key} with a key created in your admin panel
          }
        },
      )
    
  

And there you go! Your first pipeline has been processed successfully!

Since we left our pipeline with its default configuration (no options field added in our FormData), the request will wait for processing to complete before returning a result. pipelineResult therefore contains information about the pipeline, and especially the links allowing you to download the new files.

3. Downloading the files

The pipeline now has been processed, and the query result allows us to retrieve the download links of the files. You have up to 1 hour to download them, after which they will be deleted from our servers and will no longer be downloadable.

Let's see how we can download the first of our freshly created PDF files:

    
      // Downloading the first processed file
      const fileResponse = await fetch(
        pipelineResult.files[0].link,  // Just use the already-built link from the pipeline result
        {
          method: 'GET',
          headers: {
            Authorization: `Bearer ${your_API_key}`,  // Don't forget to replace ${your_API_key} with a key created in your admin panel
          }
        }
      )

      // Saving the file into a File object
      const file = new File([await fileResponse.blob()], 'myNewFile.pdf', { type: 'application/pdf' });
    
  

Simply repeat the process to download the second file.

Conclusion

You now know how to create a pipeline to interact with the Visual PDF API in 3 simple steps.

Of course, the examples in this guide are very basic and the Visual PDF API has a lot more to offer you. We suggest you continue with the guide on pipelines to discover all the possibilities they offer, but also their limits.