Endpoints
Skip to sectionPOST | /v1/reports |
GET | /v1/reports/{id}/status |
Queue a new report request generation.
Facts POST /v1/reports
Rate limit required | Special (10 requests per minute) |
Request Body POST /v1/reports
application/json | Definition of the report request. Please note that sense-story-x.0, sense-excel-template-1.0, sense-data-x.0 and qv-data-x.0 types are only for internal use. Each report request type requires a specific template to be provided:
Each template type supports specific output types:
Each output type requires a specific output to be provided:
|
Responses POST /v1/reports
202 application/json object | Report request accepted. |
400 application/json | Bad request, malformed syntax, errors in params or the report request is not valid. |
401 application/json | Unauthorized, JWT invalid or not provided. |
403 application/json | Forbidden, the user does not have access rights. |
404 application/json | Not found. |
429 application/json | Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting". |
500 application/json | Internal server error. |
POST/v1/reports
curl "https://your-tenant.us.qlikcloud.com/api/v1/reports" \
-X POST \
-H "Authorization: Bearer <API-key>" \
-H "Content-type: application/json" \
-d '{"type":"composition-1.0","output":{"type":"pdfcomposition","outputId":"composition1","pdfCompositionOutput":{"pdfOutputs":[{"size":"A4","align":{"vertical":"middle","horizontal":"center"},"resizeType":"autofit","orientation":"A"},{"size":"A4","align":{"vertical":"middle","horizontal":"center"},"resizeType":"autofit","orientation":"A"}]}},"definitions":{"selectionsByState":{"sel1":{"$":[{"values":[{"text":"Arizona","isNumeric":false}],"fieldName":"Region","defaultIsNumeric":false}]}}},"compositionTemplates":[{"type":"sense-sheet-1.0","senseSheetTemplate":{"appId":"2451e58e-a1b9-4047-abf6-315e91d8a610","sheet":{"id":"5ffe3801-1b6d-439d-a849-84d0748358f1"},"selectionsByStateDef":"sel1"}},{"type":"sense-sheet-1.0","senseSheetTemplate":{"appId":"2451e58e-a1b9-4047-abf6-315e91d8a610","sheet":{"id":"ffrxJyA"},"selectionsByStateDef":"sel1"}}]}'
Request POST /v1/reports
{
"type": "composition-1.0",
"output": {
"type": "pdfcomposition",
"outputId": "composition1",
"pdfCompositionOutput": {
"pdfOutputs": [
{
"size": "A4",
"align": {
"vertical": "middle",
"horizontal": "center"
},
"resizeType": "autofit",
"orientation": "A"
},
{
"size": "A4",
"align": {
"vertical": "middle",
"horizontal": "center"
},
"resizeType": "autofit",
"orientation": "A"
}
]
}
},
"definitions": {
"selectionsByState": {
"sel1": {
"$": [
{
"values": [
{
"text": "Arizona",
"isNumeric": false
}
],
"fieldName": "Region",
"defaultIsNumeric": false
}
]
}
}
},
"compositionTemplates": [
{
"type": "sense-sheet-1.0",
"senseSheetTemplate": {
"appId": "2451e58e-a1b9-4047-abf6-315e91d8a610",
"sheet": {
"id": "5ffe3801-1b6d-439d-a849-84d0748358f1"
},
"selectionsByStateDef": "sel1"
}
},
{
"type": "sense-sheet-1.0",
"senseSheetTemplate": {
"appId": "2451e58e-a1b9-4047-abf6-315e91d8a610",
"sheet": {
"id": "ffrxJyA"
},
"selectionsByStateDef": "sel1"
}
}
]
}
Get report request processing status.
Facts GET /v1/reports/{id}/status
Rate limit required | Tier 1 (1000 requests per minute) |
Path Parameters GET /v1/reports/{id}/status
id required string | Identifier of the request. |
Responses GET /v1/reports/{id}/status
200 application/json | Returns the request processing status. |
400 application/json | Bad request. Malformed syntax, errors in params. |
401 application/json | Unauthorized, JWT invalid or not provided. |
403 application/json | Forbidden, user did not authenticate. |
404 application/json | Not found. |
429 application/json | Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting". |
500 application/json | Internal server error. |
GET/v1/reports/{id}/status
curl "https://your-tenant.us.qlikcloud.com/api/v1/reports/{id}/status" \
-H "Authorization: Bearer <API-key>"
Response GET /v1/reports/{id}/status
{
"status": "done",
"results": [
{
"location": "https://qlikcloud.com:443/api/v1/temp-contents/619baab68023910001efcb86?inline=1",
"outputId": "output1"
}
],
"statusLocation": "/reports/01562a37-23e3-4b43-865d-84c26122276c/status",
"resolutionAttempts": 1
}
AppError
Error in resource handling
Properties
appId string | app id |
method string | The method that is failing. |
parameters object | Parameters of method that fails. |
AppErrors
Array<AppError>Errors occurring when dealing with the app.
Properties
appId string | app id |
method string | The method that is failing. |
parameters object | Parameters of method that fails. |
CallBackAction
The callback to be performed once the report is done.
Properties
httpRequest | Http callback. The provided uri will be called once the report is done. |
ComposableTemplate
Properties
type required string | Template type and version using semantic versioning. It must have the following name convention, dashed-separated-template-name-MAJOR.MINOR Enum: sense-image-1.0 sense-sheet-1.0 |
senseImageTemplate | Used to export a single visualization as pdf or png. |
senseSheetTemplate | Used to export a sheet as pdf. |
Definitions
Definitions of common properties that are shared between templates, e.g. selectionsByState can be the same for all templates within a composition of templates.
Properties
selectionsByState object | It maps an ID to a selectionsByState object. |
DocProperties
Properties of the document. In case of multiple composition, only properties specified in the composition output are taken and the ones specified in each output item are ignored.
Properties
title string | No description |
author string | No description |
subject string | No description |
Error
objectProperties
errors | Errors occured during report generation. |
ExcelOutput
Output to be used to export a excel template.
Properties
outFormat default='xlsx' string | The image format of the report to be produced. Enum: xlsx |
ExportError
objectError occured during report generation.
Properties
code required string | The unique code for the error
|
meta | Define the export error metadata. Each property is filled if it is related to the export error type. |
title required string | A summary in english explaining what went wrong. |
detail string | Optional. MAY be used to provide more concrete details. |
ExportErrors
Array<ExportError>Errors occured during report generation.
Properties
code required string | The unique code for the error
|
meta | Define the export error metadata. Each property is filled if it is related to the export error type. |
title required string | A summary in english explaining what went wrong. |
detail string | Optional. MAY be used to provide more concrete details. |
Float64
number<float64>HttpRequest
Http callback. The provided uri will be called once the report is done.
Properties
uri string | URI of the request. |
ImageOutput
Output to be used to export a single visualization as image.
Properties
outDpi maximum=1000 integer<int32> | Image resolution in DPI (default 96 DPI). |
outZoom number<float> | The scale factor to be applied in image scaling. A zoom greater than 5 will not be applied to the device pixel ratio which will remain fixed at 5. |
outFormat default='png' string | The image format of the report to be produced. Enum: png jsondata |
Meta
Define the request metadata. It includes priority, deadline and future settings on execution policy of the request.
Properties
outputTtl string<iso8601> | Time to live of the final result artifacts in ISO8601 duration format. After that duration the request and underlying output files will not be guaranteed to be available. Default is 1 hour. |
exportDeadline string<iso8601> | The maximum interval, starting from the time the API request is received, within which a report must be produced, past this interval the report generation fails. The default value is 10 minutes, the maximum allowed value is 2 hours. |
MetaExportError
Define the export error metadata. Each property is filled if it is related to the export error type.
Properties
appErrors | Errors occurring when dealing with the app. |
selectionErrors | Errors occurring in selections. |
NxPatch
Patches to apply to sense charts. Patches are soft properties meaning that are not persistent and they live within a session.
Properties
qOp required string | No description Enum: add remove replace |
qPath required string | Path to the property to add, remove or replace. |
qValue string | Corresponds to the value of the property to add or to the new value of the property to update. |
OutputItem
Properties
type required string | The generated report type. Each template type supports specific output types:
Each output type requires a specific output to be provided:
Enum: image xlsx jsondata pdfcomposition excel pptx pptxcomposition csv |
outputId required string | The output identifier which uniquely identifies an output (PDF, image etc.) within the same request. It does not need to be a GUID. No spaces and colons are allowed in the outputId string. |
pdfOutput | Output to be used to export a single visualization or a sheet as pdf. |
pptxOutput | Output to be used to export a single visualization or a sheet as PowerPoint presentation. |
excelOutput | Output to be used to export a excel template. |
imageOutput | Output to be used to export a single visualization as image. |
callBackAction | The callback to be performed once the report is done. |
pdfCompositionOutput | Output to be used to export a composition of templates as pdf. |
pptxCompositionOutput | Output to be used to export a composition of templates as pptx. |
PdfCompositionOutput
Output to be used to export a composition of templates as pdf.
Properties
pdfOutputs | The ordered list of PDF outputs, the number must match the composable templates. |
properties | Properties of the document. In case of multiple composition, only properties specified in the composition output are taken and the ones specified in each output item are ignored. |
PdfOutput
Output to be used to export a single visualization or a sheet as pdf.
Properties
size default='A4' string | Size of the pdf page. Enum: A1 A2 A3 A4 A5 A6 Letter Legal Tabloid |
align | Content alignment. |
properties | Properties of the document. In case of multiple composition, only properties specified in the composition output are taken and the ones specified in each output item are ignored. |
resizeData object | The area where the object (eg. sheet, chart) is printed. Required in case of "fit" resizeType. |
resizeType default='none' string | The type of resize to be performed:
Enum: none autofit fit |
orientation default='P' string | P for portrait, L for landscape and A for auto-detect. Auto-detect sets the orientation depending on the content width and height proportions: if content width > height the orientation is automatically set to landscape, portrait otherwise. Enum: P L A |
imageRenderingDpi default=300, maximum=1000 number<int32> | This value is used for rendered images only, set to a default of 300 dpi. |
PptxCompositionOutput
Output to be used to export a composition of templates as pptx.
Properties
pptxOutput | Output to be used to export a single visualization or a sheet as PowerPoint presentation. |
PptxOutput
Output to be used to export a single visualization or a sheet as PowerPoint presentation.
Properties
size default='Widescreen' string | Size of the PowerPoint slide:
Enum: Widescreen OnScreen OnScreen16x9 OnScreen16x10 |
properties | Properties of the document. In case of multiple composition, only properties specified in the composition output are taken and the ones specified in each output item are ignored. |
resizeType default='autofit' string | The type of resize to be performed. Autofit automatically fits the visualization, sheet or story into the output size (i.e. Widescreen, OnScreen etc.). Enum: autofit |
orientation default='L' string | L for landscape, P for portrait and A for auto-detect. Auto-detect sets landscape, the default PowerPoint orientation. Enum: L P A |
imageRenderingDpi default=200, maximum=1000 number<int32> | This value is used for rendered images only, set to a default of 200 dpi. |
QFieldValue
In order to apply a selection just one of text/number needs to be set, this must be associated with the correct isNumeric bool. In some scenarios both text and number may be set.
Properties
text string | String value of the field value. |
number | No description |
isNumeric boolean | IsNumeric tells whether the field value is text or number. Default value is equal to defaultIsNumeric property in QSelection. |
QSelection
Properties
values required | The values of the field to be selected. |
fieldName required string | The name of the field to be selected. |
defaultIsNumeric required boolean | Default value that QFieldValue isNumeric property takes if missing. |
Reason
Properties
traceId string | No description |
outputId string | The output identifier which uniquely identifies an output (PDF, image etc.) within the same request. |
exportErrors | Errors occured during report generation. |
ReportRequest
Properties
meta | Define the request metadata. It includes priority, deadline and future settings on execution policy of the request. |
type required string | Template type and version using semantic versioning. It must have the following name convention: dashed-separated-template-name-MAJOR.MINOR. Please note that sense-story-x.0, sense-excel-template-1.0, sense-data-x.0 and qv-data-x.0 are only for internal use. Each type requires a specific template to be provided:
Each template type supports specific output types:
Enum: composition-1.0 sense-image-1.0 sense-data-1.0 sense-sheet-1.0 sense-story-1.0 qv-data-1.0 qv-data-2.0 sense-excel-template-1.0 |
output required | No description |
definitions | Definitions of common properties that are shared between templates, e.g. selectionsByState can be the same for all templates within a composition of templates. |
senseImageTemplate | Used to export a single visualization as pdf or png. |
senseSheetTemplate | Used to export a sheet as pdf. |
compositionTemplates | Composition of senseSheetTemplate and/or senseImageTemplate templates. |
ReportStatus
objectProperties
status required string | Status of the requested report. Enum: queued processing done failed aborted visiting aborting |
reasons | Present when status is failed. |
results | Present when the status is "done". |
statusLocation string<uri> | Relative path to status location. |
resolutionAttempts integer<int32> | Count how many times the resolution of this report was attempted. |
Result
objectResult and info about the generated report.
Properties
location required string<uri> | Location to download the generated report. |
outputId required string | The output identifier which uniquely identifies an output (PDF, image etc.) within the same request. |
exportErrors | Errors occured during report generation. |
SelectionError
Selection error related to a fieldName. The field name is missing or some of his selection values are missing or a state is missing
Properties
detail string | Details about the field selection error. |
errorType string | No description Enum: fieldMissing fieldValuesMissing stateMissing |
fieldName string | The field name that is missing. |
stateName string | The state name that is missing. |
missingValues | No description |
isFieldNameMissing deprecated boolean | Deprecated, use errorType instead. True if the fieldName is missing. The missingValues array is empty in this case |
SelectionErrors
Array<SelectionError>Errors occurring in selections.
Properties
detail string | Details about the field selection error. |
errorType string | No description Enum: fieldMissing fieldValuesMissing stateMissing |
fieldName string | The field name that is missing. |
stateName string | The state name that is missing. |
missingValues | No description |
isFieldNameMissing deprecated boolean | Deprecated, use errorType instead. True if the fieldName is missing. The missingValues array is empty in this case |
SelectionStrategy
stringEnum:
failOnErrors
ignoreErrorsReturnDetails
ignoreErrorsNoDetails
SenseImageTemplate
Used to export a single visualization as pdf or png.
Properties
appId required string | No description |
visualization required | No description |
selectionStrategy default='ignoreErrorsNoDetails' | No description Enum: failOnErrors ignoreErrorsReturnDetails ignoreErrorsNoDetails |
selectionsByState object | Map of selections to apply by state. Maximum number of states allowed is 125. Maximum number of fields allowed is 125 and maximum number of overall field values allowed is 150000. |
selectionsByStateDef string | The definition ID referring to a selectionsByState definition declared in definitions. |
SenseSheetTemplate
Used to export a sheet as pdf.
Properties
appId required string | No description |
sheet required | It refers to the Sense Sheet to be exported. Note that if widthPx and heightPx are not specified, default values will be applied depending on the actual size and layout properties of the Sense Sheet object. |
selectionStrategy default='ignoreErrorsNoDetails' | No description Enum: failOnErrors ignoreErrorsReturnDetails ignoreErrorsNoDetails |
selectionsByState object | Map of selections to apply by state. Maximum number of states allowed is 125. Maximum number of fields allowed is 125 and maximum number of overall field values allowed is 150000. |
selectionsByStateDef string | The definition ID referring to a selectionsByState definition declared in definitions. |
Sheet
It refers to the Sense Sheet to be exported. Note that if widthPx and heightPx are not specified, default values will be applied depending on the actual size and layout properties of the Sense Sheet object.
Properties
id required string | The id of the sheet. |
jsOpts object | A JSON object that is passed as-is to the mashup page while rendering, this will be applied to all charts within the sheet. It includes properties of the whole sheet such as theme, gradient etc. |
widthPx minimum=20, maximum=4000 number<float> | The width of the sheet in pixels. Default value is: - 1680 pixels for responsive sheet - 1120 pixels for extended sheet - same width set in sheet properties for custom sheet |
heightPx minimum=20, maximum=4000 number<float> | The height of the sheet in pixels. Default value is: - 1120 pixels for responsive sheet - 1680 pixels for extended sheet - same height set in sheet properties for custom sheet |
jsOptsById object | A map for applying jsOpts to specific visualization IDs within the sheet. |
patchesById object | A map for applying soft properties, aka patches, to specific visualization IDs within the sheet. |
Visualization
Properties
id required string | The sense visualization id or json definition. |
type string | Choose visualization to export an image of a sense chart, sessionobject for a visualization to be created on-the-fly. An empty value leads to the type being inferred by its id. Enum: visualization sessionobject |
jsOpts object | A JSON object that is passed as-is to the mashup page while rendering. |
patches | Soft properties, aka patches, to be applied to the visualization. |
widthPx required, minimum=5, maximum=4000 number<float> | Width in pixels. |
heightPx required, minimum=5, maximum=4000 number<float> | Height in pixels. |