Rendering Service

priint:cloud rendering service API provides multiple endpoints to

... send a request to render a document synchronously or asynchronously,
... get a list of open rendering jobs in the queue,
... query the status of a rendering job,
... download the created artifact(s) of a rendering job.

All endpoints require an authorization header with a valid token with at least 'jobs' scope for the project at hand. See Authorization

The root URI is

https://api.priintcloud.com/rest

The basic URI pattern is

/rest/tenants/{tenant}/projects/{project}

Endpoints

Render Targets

The renderTarget defines the output format:

Render Target	Output File Type	MIME Type (synchronous response)`targetMimeType`	Extension
renderpdf	PDF	application/pdf	.pdf
renderpptx	PowerPoint	application/vnd.openxmlformats-officedocument.presentationml.presentation	.pptx

Render a document asynchronously

Asynchronous rendering is the default type of rendering and the only type recommended for production. In asynchronous rendering, a data payload (XML) is sent to the service without expecting an immediate PDF result. The data is enqueued into a job queue, and the request returns immediately with a JSON message and an HTTP 202 Accepted code. Asynchronous rendering is a 'fire and forget' procedure.

Renderings are requested by an HTTP POST of the following kind.

Request for asynchronous rendering
POST /rest/tenants/{tenant}/projects/{project}/{renderpdf}
Host: api.priintcloud.com
Authorization: Bearer {access_token} 
Content-Type: application/xml                               # or application/json or application/zip
Accept: application/json

<data>...</data>

For the details on the <data>...</data> payload see the chapter on xml-data-format.

Response for asynchronous rendering
202 Accepted
Content-Type: application/json

{ "tickets": ["{ticketId}"] }

Authorization requires a valid JWT token that can be acquired as given in the section below.
Payload is of type application/xml. It must follow the data.xml schema as described above.
On success the service responds with status 202 Accepted and a JSON body listing the internal ticket id.

Path Parameter	Description
tenant	Tenant name, e.g. "example.com"
project	Project name, e.g. "my-first-datasheet"

Accept Header	Description
application/xml	See XML Payload
application/zip	See ZIP Payload

Query-Parameter	Required	Default	Description	Support
callback	no		Pattern for callback URL. The placeholder `{location}` can be used to insert the priint cloud rendering URI or the output. This overrides the default callback defined in the restapi/config.ion.	all
error	no		Pattern for error callback URL. The placeholders `{errorCode}` and `{errorMessage}` can be used to insert these values. This overrides the default callback defined in the restapi/config.ion.	all
upload	no		Pattern for destination URL where priint cloud rendering should post the output. This overrides the default callback defined in the restapi/config.ion.	all
transform	no		Name of an optional user defined transformation to convert the data input before rendering. Only supported type is currently XSLT. Transformation names must therefore end on `.xslt`	all
documentTemplate	no	'default'	Name of the document template to be used for rendering. For PDF, default points to the `master-documents/default.w2ml` file in the comet_xml project. For PPTX, the master documents are PPTX files (e.g., default.pptx).	all
foreignKey	no		An arbitrary key controlled by the calling system to tag the current rendering process for analysis.	all
profile	no		Name of an optional configuration file stored as `restapi/config-{profileName}.ion`	all
custom	no		A custom parameter in the form `{key}:{value}`. Keys should not contain colons. This can be applied multiple times.	all
convert	no		Parameter for PDF to image conversion `(matrix style), like 'f=jpg;r=300;p=1`'.	PDF Only

A full URI with example values would look like e.g.

PDF Rendering: https://api.priintcloud.com/rest/tenants/example.com/projects/simple-datasheet/renderpdf?profile=acc&custom=refkey:bd6c313f5094d2a45834eb4d92c2caa7

PPTX Rendering: https://api.priintcloud.com/rest/tenants/example.com/projects/simple-datasheet/renderpptx?profile=acc&custom=refkey:bd6c313f5094d2a45834eb4d92c2caa7

Response States

Code	Label	Description
202	Accepted	Successfully enqueued rendering job.
400	Bad Request	Different reasons for this. Most probably a query parameter was given but did not match the expected data type.
401	Unauthorized	Invalid or empty bearer token.
403	Forbidden	Token user not entitled for the given tenant or project.
404	Not found	Tenant or project do not exist.

Render a document synchronously

Synchronous rendering is only recommended for test renderings. In synchronous rendering a data payload (XML) is sent to the service and the client waits for an immediate PDF result until a timeout.

In order to receive the result synchronously after the rendering has finished, the Accept-Header needs to be set to application/pdf (for rendering type pdf) and application/vnd.openxmlformats-officedocument.presentationml.presentation (for rendering type pptx) instead of application/json and the timeToWait parameter must be set to a timeout in msec.

POST Request to renderpdf synchronously
POST /rest/tenants/{tenant}/projects/{project}/{renderTarget}?timeToWait=20000
Accept: {targetMimeType}
Content-Type: application/xml                               # or application/json or application/zip

Examples

POST /rest/tenants/{tenant}/projects/{project}/renderpdf?timeToWait=20000
Accept: application/pdf

POST /rest/tenants/{tenant}/projects/{project}/renderpptx?timeToWait=20000
Accept: application/vnd.openxmlformats-officedocument.presentationml.presentation

Response in case success

Response for synchronous rendering (success)
200 Ok
Content-Type: {targetMimeType}

%PDF-1.7 ___REDACTED___ %%EOF

Response in case of timeout

Response for synchronous rendering (timeout)
408 Request Timeout 
Content-Type: application/json

{ "tickets": ["{ticketId}"] }

note

Requires JOBS or ADMIN scope on the project.
Supports the same query parameters as the asynchronous call to POST /renderpdf or POST /renderpptx.
Requires an additional query parameter timeToWait in msec
- minimum is 6000 for 6 sec
- maximum is 1200000 for 20 min
The payload can be XML or ZIP. For details see the other variants for POST /renderpdf or POST /renderpptx.
For details see the OpenAPI specification.

Query Parameter	Required	Default	Description
timeToWait	yes		Timeout in msec for the request.

If rendering succeeds before timeout then the generated target is returned as binary result. If timeout is reached consumers will get an HTTP 408 Request Timeout code together with a list of ticket IDs in a JSON object (same as the default POST /renderpdf or POST /renderpptx does). Processing continues in the background and consumers may ask for the result using the same endpoints as for an asynchronous rendering request.

Download Rendered Result

The download URI is typically returned by the callback notification. But it can also be composed if you prefer to "poll" the API - but this is discouraged.

Per default filename is {ticket} as returned with the original request plus the extension extension.

A request would look like this:

Request to download the PDF
GET /rest/tenants/{tenant}/projects/{project}/storage/{filename}
Host: api.priintcloud.com
Authorization: Bearer {access_token} 
Content-Type: application/pdf

Full URI might look like

https://api.priintcloud.com/rest/tenants/example.com/projects/my-first-datasheet/storage/76wirw7rwei842.pdf

Requires JOBS or ADMIN scope on the project.
Returns the PDF data in a stream.
This is an alternative for the similar call to GET /rest/tenants/{tenant}/projects/{project}/tickets/{ticket}/artifact
- An important difference to the artifact endpoint is that a successful call on the storage endpoint changes the status of the PDF from unshipped to shipped and thus does might trigger the deletion of the PDF if keepUntil was set to shipped or shippedOrExpired in the /renderpdf/config.ion.

Response for PDF download (success)
200 OK
Content-Type: application/pdf

%PDF-1.7 ___REDACTED___ %%EOF

List Open Tickets

Request to list open tickets

GET /rest/tenants/{tenant}/projects/{project}/tickets
Accept: application/json

Requires JOBS or ADMIN scope on the project.
Returns a JSON array of ticket IDs of jobs that have not yet completed.
Not completed means that the ticket is still being processed in a queue or waiting to be processed and the final status is not yet defined. Since tickets may be re-scheduled several times with delays in between depending on the configuration this can last for minutes or even hours in some cases, although it will be fast in most standard configurations.
For details see the openapi specification.

Response with IDs of open tickets
200 OK 
Content-Type: application/json

[
    "endygvoxfsjh2tvlv7wqck2rty",
    "drolgigdc7wouojssvtvqd7gha",
    "cmojlhvzg6h2tclfwnxiyieema",
    "czvmnsozp7wb62mhae4xqmbwqm",
    "f3ltaceckmxrexdejnlk2kyk4u",
    "qyj5rnliadmfwubmqx7v2lznr4"
]

Get Ticket Status

Request to get status of single ticket

GET /rest/tenants/{tenant}/projects/{project}/tickets/{ticket}/status
Accept: {targetMimeType}

Requires JOBS or ADMIN scope on the project.
Returns JSON object of type TicketStatusView containing fields like complete, created, updated, errorCode, next, processingMsecs, processingPages, redeliveries, status, etc.
For open tickets the most interesting information may be in next property (the next step in the processing queue for this ticket like priint-grid/queue/error) and in the status property (the completion status of the previous step in the queue for this ticket like renderpdf.failed).
For details see the openapi specification.

Response with IDs of open tickets
200 OK 
Content-Type: application/json

{
    "complete": false,
    "tenant": "example.com",
    "project": "my-first-datasheet",
    "ticket": "endygvoxfsjh2tvlv7wqck2rty",
    "status": "renderpdf.failed",
    "created": "2023-05-23T12:49:25.218437Z",
    "updated": "2023-05-23T12:49:25.419823Z",
    "next": "priint-grid/queue/renderpdf_shared_redeliver",
    "redeliveries": 0
}

For example, the webhook should record entries of the following format in requestMessages for all unsuccessful HTTP responses (excluding status code 401):

HTTP [500] (145 ms, 963 bytes sent, 1022 bytes received). POST https://my/foo/bar

For comprehensive diagnostics, inclusion of the HTTP response body is recommended. However, this data is only available when the system is executed with profile=trace.

Upload attempt failed 3 times (2 redeliveries) when sending a 195,563-byte PDF to the same target URL destination.

{
    "complete": true,
    "tenant": "nexoma.de",
    "project": "demo_acc",
    "ticket": "v2qc7u6l7tyjsu55cvbffbe7hu",
    "status": "error.succeeded",
    "messages": [
      "HTTP [500] (645 msec, 195563 sent, 1022 received). PUT https://my/foo/bar",
      "HTTP [500] (235 msec, 195563 sent, 1022 received). PUT https://my/foo/bar",
      "HTTP [500] (260 msec, 195563 sent, 1022 received). PUT https://my/foo/bar"
    ],
    "created": "2025-05-26T07:00:44.177804Z",
    "updated": "2025-05-26T07:00:52.480035Z",
    "redeliveries": 2,
    "processingMsecs": 4267,
    "processingPages": 2
}

Get Ticket Artifact (PDF)

Request to get the main ticket artifact (PDF)

GET /rest/tenants/{tenant}/projects/{project}/tickets/{ticket}/artifact
Content-Type: application/pdf

Requires JOBS or ADMIN scope on the project.
Returns the PDF data in a stream.
This is an alternative for the similar call to GET /tenants/{tenant}/projects/{project}/storage/{filename}.
- An important difference to the storage endpoint is that the artifact endpoint does not change the status of the PDF from unshipped to shipped and thus does not trigger the deletion of the PDF if keepUntil was set to shipped or shippedOrExpired in the /renderpdf/config.ion.
For details see the openapi specification.

Response for ticket artifact (pdf) (success)
200 Ok
Content-Type: application/pdf

%PDF-1.7 ___REDACTED___ %%EOF

Get Ticket Artifact (Powerpoint)

Request to get the main ticket artifact (### Get Ticket Artifact Powerpoint)

GET /rest/tenants/{tenant}/projects/{project}/tickets/{ticket}/artifact
Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation

Requires JOBS or ADMIN scope on the project.
Returns the Powerpoint data in a stream.
This is an alternative for the similar call to GET /tenants/{tenant}/projects/{project}/storage/{filename}.
- An important difference to the storage endpoint is that the artifact endpoint does not change the status of the PDF from unshipped to shipped and thus does not trigger the deletion of the PDF if keepUntil was set to shipped or shippedOrExpired in the /renderpptx/config.ion.
For details see the openapi specification.

Response for ticket artifact (pptx) (success)
200 Ok
Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation

%PDF-1.7 ___REDACTED___ %%EOF

Get Ticket Artifacts (ZIP)

Request to get status of single ticket

GET /rest/tenants/{tenant}/projects/{project}/tickets/{ticket}/artifact
Content-Type: application/zip

Requires JOBS or ADMIN scope on the project.
Returns all artifacts generated during rendering packed into a zip file.
Which files are collected depends on the kind and success of the rendering job. In case of a failed rendering it will contain comet.log, product data as xml, and optionally product list as xml. In case of success the PDF will also be part of this.
For details see the openapi specification.

Response for ticket artifact (zip) (success)
200 Ok
Content-Type: application/zip

PK...___REDACTED___

Example Contents of the Zip

Contents of artifacts zip for ticket 76wirw7rwei842
├── 76wirw7rwei842.pdf                # the PDF (only if the rendering was successful)
├── 76wirw7rwei842.comet.log          # the comet log file
├── 76wirw7rwei842.content.xml        # the actual XML input for the rendering
├── 76wirw7rwei842.items.xml          # the actual product list for the rendering (if simple "place" mode was used) 
└── 76wirw7rwei842.pdflib.log         # the PDFLib log file

Data Variants

XML Payload

The detailed description of the XML format as data payload for a rendering can be found here.

ZIP Payload

POST Request to renderpdf using a ZIP file with data and images
POST /rest/tenants/{tenant}/projects/{project}/renderpdf
Content-Type: application/zip
Accept: application/json

The payload MUST be a zip file. The zip MUST contain a file data.xml or data.json in the root. The zip MAY contain other resource files like images (png, jpg, pdf) or data (json, xml) in the root or in subfolders.

Example Zip Content

├── data.xml
├── images/my.pic.png
└── drawings/my.graph.pdf

note

Requires JOBS or ADMIN scope on the project.
Supports the same query parameters as the other calls to POST /renderpdf.
Returns the same tickets list as result as the other calls to POST /renderpdf when called with Accept: application/json.
For details see the OpenAPI specification.

tip

How to use the files from the zip in Comet?

Comet users can retrieve the files within the zip using the GRID_DATA_DIR environment variable in Python or CScript.

Endpoints​

Render Targets​

Render a document asynchronously​

Render a document synchronously​

Download Rendered Result​

List Open Tickets​

Get Ticket Status​

Get Ticket Artifact (PDF)​

Get Ticket Artifact (Powerpoint)​

Get Ticket Artifacts (ZIP)​

Data Variants​

XML Payload​

ZIP Payload​