Printing a report via the API?

nfshoobs · August 13, 2026, 9:51pm

Is there presently a way to run a report query (and thus generate a label or report) for a record (or set of records) via the API?

I imagine not, because the report runner doesn’t have a unique URL response and the reports do not persist on the server after the report runner is closed, right?

Could potentially be grouped with my previous post here, under the broader theme of “improvements to report runner” Feature Request: Allow customization of filenames in Report Runner

Grant · August 17, 2026, 7:58pm

Hi @nfshoobs,

Technically there is an API for it, via POST /report_runner/run/, since Specify just POSTs a form to this endpoint with report (JRXML), query (JSON, incl. recordSetId for sets, or an id-filter for single records), and parameters (as a JSON object). The response is the PDF itself, but it was designed to always be triggered by Specify alone and not another source.

You’re right that there is no persistence since the PDF is rendered on the fly each time, so it isn’t really stored anywhere long-term. There’s also not a unique URL really, since the endpoint’s body is the PDF.

It’s really not designed to be used since there’s no API auth on this endpoint. To use it, you’d need to replicate the whole stack (session, auth, CSRF token) and send the expected request.

jason_m · August 17, 2026, 8:38pm

If anyone is planning on using Specify’s endpoint for this (/report_runner/run/), here’s some additional information that should be helpful.

The /report_runner/run/ endpoint in Specify 7 is undocumented and largely considered “internal” by the Specify team.
You are free to use it in your own projects, but it might be subject to change in the future.
Use it at your own risk

The following is the location within the Specify7 code where the request is handled.
If you’re able to read and parse Python code, this is the best place to learn how it works:

github.com/specify/specify7

specifyweb/backend/report_runner/views.py

383e28cf9


      
          @require_POST
          @login_maybe_required
          def run(request):
              """Executes the named 'report' using the given 'query' and 'parameters' as POST parameters.
              Returns the result as a PDF.
              """
              check_permission_targets(request.specify_collection.id, request.specify_user.id, [ReportsPT.execute])
          
              if settings.REPORT_RUNNER_HOST == '':
                  raise ReportException(_("Report service is not configured."))
          
              port = settings.REPORT_RUNNER_PORT
              if port == '': port = 80
          
              report_data = run_query(request.specify_collection, request.specify_user, request.POST['query'])
              if len(report_data['rows']) < 1:
                  return HttpResponse(_("The report query returned no results."), content_type="text/plain")
          
              r = requests.post("http://%s:%s/report" %
                                (settings.REPORT_RUNNER_HOST, port),

This file has been truncated. show original

If you plan on using the Report Runner directly, below is the relevant code that handles the request (written in Java)

github.com/specify/report-runner-service

src/main/java/edu/ku/brc/specify/reports/ReportServlet.java

b69ee43ad


      
          public class ReportServlet extends HttpServlet {
          
              @Override
              protected void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
                  String reportStr = request.getParameter("report");
                  String data = request.getParameter("data");
                  String parameters = request.getParameter("parameters");
                  ByteArrayInputStream reportIS = new ByteArrayInputStream(reportStr.getBytes(StandardCharsets.UTF_8));
                  JRDataSource dataSource = new DataSource(data);
                  JsonParser parser = new JsonParser();
                  Map<String, Object> params = new HashMap<>();
                  JsonObject parametersParsed = parser.parse(parameters).getAsJsonObject();
                  for (Map.Entry<String, JsonElement> entry : parametersParsed.entrySet()) {
                      params.put(entry.getKey(), entry.getValue().getAsString());
                  }
          
                  byte[] pdf;
                  try {
                      JasperReport report = JasperCompileManager.compileReport(reportIS);
                      JasperPrint filledReport = JasperFillManager.fillReport(report, params, dataSource);

This file has been truncated. show original

The Report Runner is completely stateless, meaning it has no persistence and no concept of which Queries map to which Reports. The physical report and associated results which act as the report’s “data source” have to be handed to the Report Runner for each request.

For the Specify 7 /report_runner/run/ POST endpoint, the request body should be in x-www-form-urlencoded format and have the three key+value pairs aforementioned by Grant:

query
- A serialized/stringified JSON representation of the Query that will be run by Specify to retrieve the result to be passed to the Report Runner
report
- A serialized/stringified XML representation of the report (i.e., the JRXML of the report you want to run, as a string)
parameters
- The report parameters (if any) in a serialized JSON format
- A report parameter is a non-QueryBuilder field value mapped to a name that is entered by the user before a report is ran
- These would be on your reports with something like parameter[isForPrompting="true"]
- Most reports probably won’t have parameters, but this key+value pair is still required

The Specify 7 endpoint does make sure the executing user has the correct permissions to execute reports and read the tables present in the serialized Query.

The Specify 7 backend can respond in three different ways:

With a 200 status code, a text/plain Content Type, and the text The report query returned no results. if the serialized Query did not return any results
With a 200 status code, an application/pdf Content Type, and the resulting PDF as conent
With a 500 status code and an exception message if the Report Runner was not able to correctly process the report

Topic		Replies	Views
Printing Reports or Labels Labels & Reports Specify-7 , Members-only	0	243	May 12, 2025
SpiReport Specify 6 Documentation Specify-6	0	747	March 17, 2022
Generate a Report Labels & Reports Specify-7	0	586	March 18, 2022
Export a Report or Label Labels & Reports Specify-7 , Members-only	0	229	August 27, 2024
Create a Report or Label (Jaspersoft Studio) Labels & Reports Specify-7 , Members-only	1	2425	May 23, 2024

Printing a report via the API?

Related topics