Skip to main content

Installation and operation of axesFlip REST Server

Janne Brönner
  • Updated

System requirements

Please refer to System requirements.

Download

Download the axesFlip ZIP package. Extract the ZIP package and copy it to a suitable location on your server: 
Download axesFlip

Configuration

Before using axesFlip REST Server, you must create a configuration file (flip.config.json) with your own settings. For details and sample configuration files, please refer to axesFlip REST Server configuration guide.

Start and stop axesFlip REST Server

Open a command-line interface, navigate to the axesFlip REST Server directory, and start the server by typing:

axesFlipServer.exe

axesFlipServer.exe is a Kestrel server that provides the functionality via a Web API.

Stop the the Kestrel server by typing Ctrl+C on your keyboard.

Demo mode

If no valid license key is configured, axesFlip operates in demo mode. You have access to all functions, but the resulting PDF files have watermarks and random color translations of individual characters. 

An exception applies if the environment is set to "Production"—in this case, axesFlip terminates with an error message instead of starting in demo mode.

API Swagger documentation

The API of axesFlip REST Server provides an integrated Swagger UI for exploring and testing all available endpoints.

The Swagger documentation is available at:

https://[HOSTNAME]:[PORT]/swagger

The default port is 29375.

In addition to serving as a reference, the Swagger UI allows you to interactively test API endpoints, experiment with settings, and test templates and documents directly from the browser.

OpenAPI specification

The OpenAPI specification is also available as a JSON file to import into to your own API client:

http://[HOSTNAME]:[PORT]/swagger/v1/swagger.json

API overview

The API provides REST endpoints for health monitoring, PDF remediation, and template management. 

Health endpoints

Check service availability

GET /v1/health/ping

Checks whether the service is running and reachable. 

Self-test

POST /v1/health/selftest

Runs a built-in self-test by remediating a predefined test PDF and returning the remediated result.

Remediation endpoint

Remediate PDF

POST /v1/remediation/remediate

Accepts documents as a file or stream and applies the template identified by the specified templateId. This endpoint returns the remediated PDF and serves as the primary endpoint for production workflows. A template must already be uploaded before this endpoint can be used.

Optionally, you can specify a file name for the remediated PDF using the X-File-Name header. You can also provide an X-Correlation-Id, which will be returned after the document has been remediated to support request tracking and correlation.

The following content types for PDF documents are supported:

  • application/pdf
  • application/octet-stream
  • multipart/form-data
  • application/json

Template endpoints

Check if a template exists

HEAD /v1/templates/{templateId}

Checks whether a template with the given ID exists.

Get template metadata

GET /v1/templates/{templateId}

Retrieves metadata for a specific template, such as its status.

Upload a template

POST /v1/templates/{templateId}

Uploads a new template in the selected media type. The following content types are supported:

Update an existing template

PUT /v1/templates/{templateId}

Updates an existing template in the selected media type.

Delete a template

DELETE /v1/templates/{templateId}

Deletes an existing template entirely, removing it from the system.

List all available templates

GET /v1/templates

Returns a list of all available templates, including their IDs and current status.

Download template content

GET /v1/templates/{templateId}/content

Downloads the template with the specified ID.

Enable a template

POST /v1/templates/{templateId}/enable

Enables a template, making it active and available for remediation. This is only necessary if the template has been disabled beforehand.

Disable a template

POST /v1/templates/{templateId}/disable

Disables a template without deleting it, preventing it from being used in remediation while preserving its configuration.

https-Certificate

A certificate is required for https, which must be installed on your computer and is referenced in the configuration.