The radixAPI is a REST-JSON API acording the OpenAPI specification. Every endpoint response with a application/json content-type.
See bottom if this site for a version history
radixAPI has the following features
if not noted otherwise, the following reponses are returned
| HTTP Status Code | Reason | Response Model |
|---|---|---|
| 200 | OK | JSON |
| 401 | Unauthorized | JSON |
| 404 | not found | JSON |
| 500 | Internal server error | JSON |
| 900 | pdfToolbox general error | JSON |
| 904 | pdfToolbox can't open file error | JSON |
| 905 | pdfToolbox file is encrypted error | JSON |
| 906 | pdfToolbox can't save file error | JSON |
| 907 | pdfToolbox file is damaged error | JSON |
| 942 | pdfToolbox timeout error | JSON |
radixPreflight API collection V2
For testing you also need a postman environment. It will provided to gether with your login credentials per eMail.
All routes are defined there with examples.
Except the login call, every API calls require an authentication using an AccessToken. An AccessToken gets generated together with a RefreshTocken via the login call.
An AccessToken is valid for 24h. A RefreshToken is valid for 7 days.
New users can get registered via the API. Upon new registration, a demo license valid for 30 days gets generated. After that period, linceses must get purchased thru the regular sales channel.
Every process starts with an io process, which defines the file to be processed. If the file was already processed by a former call it is possible to use these existing files instead of sending/loading a new file.
The next step is at least one process that creates one or more new files. A typical example is the modification/fixing of a PDF file that creates a new version of this file, together with some reports.
As last step, the created files are uploaded to a cloud storage. This step is optional, as the files can also get downloaded from the radixAPI via http(s).
Files in the radixAPI are referred to as Resources. Such Resources have additional metadata for easier differentiation.
As PDF processing can be time consuming, the calls to process resouces are asynchronous calls. The result can either be sent to a defined webhook. Or the client keeps polling until the created workflow until the workflow is done.
callback URLs are defined as query paramater callback=<callbackURL>
The easiest way to process resources is to use any of our predefined routes (aka marketing endpoints).
Almost every marketing endpoint allow to define the following query parameter
| key | value |
|---|---|
| inputUrl | URL of input resource http(s) - s3 - repository - container - radix - file |
| outputURL | URL of output folder - optional - only S3 is supported at the moment |
| callback | {{callbackUrl}} |
| externalId | {{string}} - this property is also defined in the response for easier usage an the client side |
| customData | {{object}} - this property is also defined in the response for easier usage an the client side |
When a process is triggered, a partly populated workflow object gets returned. When receiving this response the posted payload was validated (syntactically) files via form-data got stored and the proesses got queued.
reponse objects get pupulated over time until the final response
this gets returned when calling a marketing endpoint or a complete workflow
Example
{
"createdAt": "2025-04-01T15:55:53.220Z",
"updatedAt": "2025-04-01T15:55:53.220Z",
"name": "splitpdf",
"status": "created",
"webhook": {
"url": "http://services-1.calibrate.at:1880/callback"
},
"keycloakUserId": "8cc7357e-3715-4aa3-8139-c09d4b6172e6",
"externalId": "12",
"customData": [
{
"key": "resourceId",
"value": 12
}
],
"workflowSpecId": 9,
"error": null,
"isLegacy": false,
"userId": null,
"id": 475,
"deletedAt": null
}
Almost every marketing endpoint allow to define the following query parameter
| key | value |
|---|---|
| id | {{workflowId}} - can be used to query the status of the workflow |
| status | can be any of created, queued, processing, done or error |
A workflow stops processing when the status is either done or error. See below for Error object
Example
{
"createdAt": "2025-04-01T15:55:53.220Z",
"updatedAt": "2025-04-01T15:55:55.740Z",
"id": 475,
"deletedAt": null,
"name": "splitpdf",
"status": "done",
"error": null,
"isLegacy": false,
"webhook": {
"url": "http://services-1.calibrate.at:1880/callback"
},
"workflowSpecId": 9,
"userId": null,
"keycloakUserId": "8cc7357e-3715-4aa3-8139-c09d4b6172e6",
"externalId": "12",
"customData": [
{
"key": "resourceId",
"value": 12
}
],
"current_process": {},
"processes": [
{
"createdAt": "2025-04-01T15:55:53.227Z",
"updatedAt": "2025-04-01T15:55:53.291Z",
"id": 1277,
"deletedAt": null,
"node": "io",
"customId": "io-input",
"status": "done",
"error": null,
"containerId": 524,
"workflowId": 475,
"children": [
{
"customId": "splitpdf"
}
]
},
{
"createdAt": "2025-04-01T15:55:53.235Z",
"updatedAt": "2025-04-01T15:55:53.892Z",
"id": 1278,
"deletedAt": null,
"node": "splitpdf",
"customId": "splitpdf",
"status": "done",
"error": null,
"containerId": 524,
"workflowId": 475,
"children": []
}
],
"output": {
"resources": [
{
"createdAt": "2025-04-01T15:55:55.692Z",
"updatedAt": "2025-04-01T15:55:55.692Z",
"type": "production",
"usage": "sidecar",
"id": 3014,
"deletedAt": null,
"customId": null,
"name": "input_01.pdf",
"originalName": "input_01.pdf",
"direction": "output",
"path": "/root/data/containers/5d9fe032-7cae-457e-80b2-0a1afcc30d5d/input_01.pdf",
"uri": "file:///root/data/containers/5d9fe032-7cae-457e-80b2-0a1afcc30d5d/input_01.pdf",
"inputURL": null,
"outputURL": null,
"downloadURL": "/api/v1/containers/524/download/input_01.pdf",
"mimeType": "application/pdf",
"isFolder": false,
"fileSize": "2991823",
"repositoryId": null,
"containerId": 524,
"processId": 1278,
"workflowId": 475
},
{
"createdAt": "2025-04-01T15:55:55.698Z",
"updatedAt": "2025-04-01T15:55:55.698Z",
"type": "production",
"usage": "sidecar",
"id": 3015,
"deletedAt": null,
"customId": null,
"name": "input_03.pdf",
"originalName": "input_03.pdf",
"direction": "output",
"path": "/root/data/containers/5d9fe032-7cae-457e-80b2-0a1afcc30d5d/input_03.pdf",
"uri": "file:///root/data/containers/5d9fe032-7cae-457e-80b2-0a1afcc30d5d/input_03.pdf",
"inputURL": null,
"outputURL": null,
"downloadURL": "/api/v1/containers/524/download/input_03.pdf",
"mimeType": "application/pdf",
"isFolder": false,
"fileSize": "2030254",
"repositoryId": null,
"containerId": 524,
"processId": 1278,
"workflowId": 475
}
]
}
}
When no error occured, all created resources are listed.
created resouces are defined in the final response at output.resources
{
"createdAt": "2025-04-01T15:55:55.698Z",
"updatedAt": "2025-04-01T15:55:55.698Z",
"type": "production",
"usage": "sidecar",
"id": 3015,
"deletedAt": null,
"customId": null,
"name": "input_03.pdf",
"originalName": "input_03.pdf",
"direction": "output",
"path": "/root/data/containers/5d9fe032-7cae-457e-80b2-0a1afcc30d5d/input_03.pdf",
"uri": "file:///root/data/containers/5d9fe032-7cae-457e-80b2-0a1afcc30d5d/input_03.pdf",
"inputURL": null,
"outputURL": null,
"downloadURL": "/api/v1/containers/524/download/input_03.pdf",
"mimeType": "application/pdf",
"isFolder": false,
"fileSize": "2030254",
"repositoryId": null,
"containerId": 524,
"processId": 1278,
"workflowId": 475
}
| key | value |
|---|---|
| downloadURL | {{id}} - file can get downloaded directly using this route - requires Authentication |
| outputURL | {{url}} - external URL to access the upload file in cloud storage |
| direction | output - for all created files |
| type | production - report - asset |
| usage | sidecar - |
| customId | used when generating multiple files, like for saveasimg, for better differentiation |
| uri | can be used for subsequent calls when a process shall use an already existing resource |
in case of an error, the occured errors are listed in the errors collection of the result object. Example of an error object:
{
"message": "An encrypted PDF file could not be opened for writing",
"name": "PlatformPDFTBProcessFileEncrypted",
"statusCode": 905,
"details": {
"process": {
"id": "5f2c10fcd432ee00558fac85",
"name": "profile"
},
"error": {
"cli": "ProcessID\t129\t\nProfile\t/root/data/common/calibrate masterPreflight.kfpx\t\nInput\t/root/data/5f2c10fc618c780055a5b5bb/open_secured.pdf\t\nDuration\t00:04\t\nError\t1011\tCould not open encrypted file /root/data/5f2c10fc618c780055a5b5bb/open_secured.pdf: 10\t\n",
"input": "/root/data/5f2c10fc618c780055a5b5bb/open_secured.pdf",
"filter": null,
"server": null,
"code": 105
},
"output": null
}
}
| property | type | comment |
|---|---|---|
| message | string | human readable describes about what triggered the error |
| name | enum | unique name for the type of error |
| statusCode | integer | status code for the type of error |
| details | object | detailed information about the module causing the error with additional information |
| code | name |
|---|---|
| 400 | URIFormatUnsupportedError |
| 401 | RequestAuthorizationError |
| 401 | RequestAuthenticationError |
| 404 | ResourceNotFoundError |
| 404 | S3ResourceError |
| 404 | S3InvalidCredentialsError |
| 404 | S3InvalidURIError |
| 409 | |
| 413 | |
| 422 | |
| 423 | |
| 500 | |
| 501 | |
| 900 | PlatformPDFTBProcessError |
| 904 | PlatformPDFTBProcessFileCannotopen |
| 905 | PlatformPDFTBProcessFileEncrypted |
| 906 | PlatformPDFTBProcessFileCannotsave |
| 907 | PlatformPDFTBProcessFileDamaged |
| 942 | PlatformPDFTBProcessTimeout |