HTTP API

Template printing can be triggered directly through the HTTP API. Whether you are printing from a detail block or a table block, the underlying call is the templatePrint action on the current business resource.

curl -X POST \
	-H "Authorization: Bearer <JWT>" \
	-H "Content-Type: application/json" \
	"http://localhost:3000/api/<resource_name>:templatePrint" \
	--data-raw '{...}'

Notes:

• <resource_name> is the resource name of the current collection.
• The API returns a binary file stream rather than JSON.
• The caller must have query permission for the current resource and permission to use the corresponding template print button.
• You must pass a user-login-based JWT token in the Authorization header, otherwise access will be denied.

Request body parameters

Table block

Table blocks use the same endpoint, with blockName: "table" indicating list-print mode. The server runs a find query on the resource and passes the result array into the template.

Print selected records or current page results

This is suitable when printing selected rows from a table block, or when preserving the current page context for printing. The common approach is:

• Set queryParams.page and queryParams.pageSize to the current table page and page size.
• Build filter.id.$in from the primary keys of the selected records.

curl 'https://<your-host>/api/<resource_name>:templatePrint' \
	-H 'Authorization: Bearer <JWT>' \
	-H 'Content-Type: application/json' \
	--data-raw '{
		"queryParams": {
			"pageSize": 20,
			"filter": {
				"id": {
					"$in": [1, 2]
				}
			},
			"appends": [],
			"page": 1
		},
		"templateName": "9012hy7ahn4",
		"blockName": "table",
		"timezone": "Asia/Shanghai",
		"uid": "ixs3fx3x6is"
	}'

This request means:

• blockName is table, so the template is rendered with list data.
• filter.id.$in specifies the set of records to print.
• page and pageSize preserve the current paging context so the behavior matches the UI.
• appends can be used to include additional associations when needed.

Print all matching data

This is suitable for the "Print all records" action in a table block. In this mode, the API no longer limits the query to the current page, and instead loads all data matching the current filter conditions.

The key point is to explicitly set queryParams.page and queryParams.pageSize to null.

curl 'https://<your-host>/api/<resource_name>:templatePrint' \
	-H 'Authorization: Bearer <JWT>' \
	-H 'Content-Type: application/json' \
	--data-raw '{
		"queryParams": {
			"pageSize": null,
			"filter": {},
			"appends": [],
			"page": null
		},
		"templateName": "9012hy7ahn4",
		"blockName": "table",
		"timezone": "Asia/Shanghai",
		"uid": "ixs3fx3x6is"
	}'

This request means:

• page: null and pageSize: null disable pagination.
• filter: {} means no extra filter is added. If the UI already has filter conditions, you can pass them here directly.
• The server queries all matching data and renders the template in batch.

Note: a table block can print at most 300 records in a single request. If the limit is exceeded, the API returns a 400 error.

Detail block

Detail blocks use the same templatePrint action, but usually pass:

• blockName: "details"
• queryParams.filterByTk to identify the current record
• queryParams.appends to specify additional associations to load

The server then runs a findOne query on the resource and passes the result object into the template.

Response

When the call succeeds, the API directly returns a file stream. Typical response headers look like this:

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="<template-title>-<suffix>.<ext>"

Notes:

• If convertedToPDF is true, the returned file extension is .pdf.
• Otherwise, the API returns the original template type, such as .docx, .xlsx, or .pptx.
• Frontends usually trigger the browser download based on the filename in Content-Disposition.

Additional resources

• Using API keys in NocoBase