Render REST API

GET/POST /v1/reports/{reportKey}/render.{extension}
GET/POST /v1/render/{*reportKey}.{extension}

Renders a single report instance to a specific output format (for example PDF, Excel, or CSV) identified by the extension. This endpoint is used both by the ReportShell frontend viewer for HTML previews and exports, and by any custom web viewer calling the REST API directly.

Exports are handled by the JasperReports Library exporters or your own ReportExporter implementations. See Exporting Reports for more details.

The endpoint can be used in two ways:

On-demand Export

When called without the rs.executionId parameter, the endpoint fills the report and immediately exports it to the requested format. This behaves similarly to BIRT Viewer’s “Run and Render” mode. The filled print document is transient and is not stored as a persistent execution.

Caution

Report filling is synchronous. For large reports this can take a long time and may lead to HTTP timeouts.

Export from a Persistent Execution

When called with the rs.executionId parameter, the endpoint exports the report from an existing persistent execution. The report is not filled again; instead, the stored print document is reused.

Request Parameters

Parameter	Type	Description
rs.page	Integer?	Number of a single report page to export
rs.pages	String?	Report pages to export specified as a range (e.g., 1-5).
rs.offsetX	Integer?	Horizontal offset of the report from the left edge.
rs.offsetY	Integer?	Vertical offset of the report from the top edge.
rs.zoom	Float?	Zoom setting for HTML exports.
rs.executionId	String?	ID of a persistent execution to use.
rs.pagePerSheet	Boolean?	Whether to export each report page to its own sheet in Excel exports. Defaults to false when omitted.
rs.format	String?	Registration key of the exporter factory to use as the format specifier. See details below.
rs.interactive	Boolean?	Whether the HTML export is for an interactive context such as previews. Defaults to false when omitted.

Example Requests

On-demand Export to PDF

GET /v1/reports/123/render.pdf?param1=foo&param2=bar&rs.page=1&rs.locale=fr_FR

Export to CSV (Metadata) with rs.format

GET /v1/reports/123/render.csv?param1=foo&param2=bar&rs.page=1&rs.format=csv_metadata

Export to HTML with Execution ID

GET /v1/reports/123/render.html?rs.executionId=<uuid>&rs.zoom=1.25

Export with Multi-Segment Report Key

GET /v1/render/sales/summary.xlsx?param1=foo&param2=bar&rs.pagePerSheet=true

Export with HTTP POST

POST /v1/render/sales/summary.pdf
Content-Type: application/x-www-form-urlencoded

param1=foo&param2=bar&rs.page=1&rs.locale=fr_FR

Supported Formats

ReportShell supports exports to the following formats by default:

• html
• pdf
• xlsx
• docx
• csv
• csv_metadata

Supported formats depend on registered export factories as described in Exporting Reports

Extension vs Format

For formats that can be represented as a simple extension (for example .pdf), the URL extension is used as the export format identifier. ReportShell resolves an exporter factory registered for that identifier without the dot (for example pdf).

For formats that cannot be represented as an extension (for example csv_metadata), you must provide an additional rs.format parameter, such as rs.format=csv_metadata. ReportShell then uses this parameter to resolve the exporter factory. The URL extension is still used only for setting the Content-Disposition file name.

Example:

Below URL renders the file name with extension ‘.csv’ while using the format identifier ‘csv_metadata’ for resolving an exporter.

GET /v1/render/my-report.csv?param1=foo&param2=bar&rs.format=csv_metadata

HTML Exports

When the rs.executionId parameter is provided, the endpoint passes that ID to the exporters through ReportExportContext. You may choose to store dynamic (non-embedded) attachments such as images, charts, and scripts under a directory path containing that executionId to isolate the storage space. You will likely also need to isolate individual exports from each other within that execution-specific directory. To do so, pass an rs.extra.exportId GUID string, which is exposed to the exporter factory, and customize your HtmlExporter to use that id as a subdirectory.

For ad-hoc exports without an rs.executionId, you can pass another GUID or any other extra parameter to isolate the storage space as you wish.

Tip

The bundled frontend viewer supports a pre-request interceptor that lets you set these extra parameters. If you want to handle isolation based on, for example, the user session, register an OperationContextInitializer bean, set the relevant context attribute, and let your exporters or factories resolve parameters from the operation context.

The default HtmlExporterFactory does not configure any attachment storage and does not write HTML files to disk. It works with embedded images and charts only.

See the HtmlExporterFactory API docs for more details about resource handling.

Interactivity

The endpoint accepts an rs.interactive flag so callers can differentiate interactive previews from static exports. The framework itself does not act on this flag. If you need interactivity such as drill-downs or dynamic links, customize the default HtmlExporter or register your own exporter factory for interactive exports.