Skip to content

How to Use the API

To use the SRS API, you need to have a valid token. See authentication and execute the following GET/POST requests.

Definition

This API returns the SRS definition.

HTTP
1
2
GET {{host}}/api/srs/{{srs_id}}
Authorization: Token {{token}}

Execute

This API executes the SRS and returns the result in the specified format.

HTTP
1
2
GET {{host}}/api/srs/{{srs_id}}/{{renderer}}
Authorization: Token {{token}}

Note

  • An error in any command returns HTTP status 200 with success = false and the error text in message
  • An error in the srssetup command returns an error message and stops the SRS (this can be used to execute business logic before the SRS runs)

Parameters

When executing a request, parameters can be passed via query string, JSON body, or both.

Note

  • If a name is duplicated in the query string and JSON body, the query string takes precedence.
HTTP
1
2
3
4
5
6
7
8
POST {{host}}/api/srs/{{srs_id}}/{{renderer}}
Authorization: Token {{token}}
Content-Type: application/json

{
    "param1": "value1",
    "param2": "value2"
}

Renderers

The renderer is the format in which the SRS result is returned. The following renderers are supported:

  • /api/srs/{SRSID} - SRS definition only; no command is executed
  • /api/srs/{SRSID}/run - any name without an extension returns the full SRS JSON (tables, def, data); used by the UI
  • /api/srs/{SRSID}/{name}.json - JSON object, simplified format: one property per command in data
  • /api/srs/{SRSID}/{name}.lower.json - same as .json with lowercase property names
  • /api/srs/{SRSID}/{name}.html - HTML tables
  • /api/srs/{SRSID}/{name}.xlsx - Excel workbook, one worksheet per command plus an Export Summary sheet with parameters
  • /api/srs/{SRSID}/{name}.txt - all cell values written one after another, without separators; useful when a command returns ready text
  • /api/srs/{SRSID}/{name}.epp - same as .txt
  • /api/srs/{SRSID}/{name}.md - Markdown tables
  • /api/srs/{SRSID}/{name}.xml - XML document without a template: root element = SRS label, one element per row named after the command, one child element per column; see XML export
  • /api/srs/{SRSID}/{template}.hbs[.html|.pdf|.csv|.txt|.xml|.epp|.svg|.json|.md|.css|.js] - Handlebars template templates/{template}.hbs; see Handlebars
  • /api/srs/{SRSID}/{template}.frx[.html|.pdf] - FastReport template templates/{template}.frx; see FastReport

Other extensions (for example .csv, .svg, .pdf) have no built-in renderer. They require a .hbs or .frx template; without one the request returns a Missing renderer error.

The file renderers (.html, .xlsx, .md, .txt, .xml) skip:

  • columns and commands with ex="false"
  • commands with opts="server"
  • commands that return no rows (.html, .xlsx, .xml)

Extra query parameters

  • ptoken - authorization token; see authentication
  • pscope - comma-separated list of command names to limit execution to those commands
  • popts - comma-separated renderer options
    • links - .html renders tlink and tlink_frame columns as <a> links
    • -nav - .html hides the title, the parameter table and the view toggles
    • --aioptimized - JSON renderers return a compact projection for AI/MCP clients: only name, label, title, type of columns, links resolved to {name, url}, no debugger
  • pcolumns - comma-separated list of columns to hide in every renderer, each name prefixed with -, for example pcolumns=-col1,-col2
  • file_name - downloads the result as a file with this name; see File name and encoding

File name and encoding

  • The default encoding for all files is UTF-8.
  • To use Windows-1250 encoding, add ,1250 after the file name: /api/srs/123/test.hbs.txt?file_name=test.txt,1250
  • Custom file name: /api/srs/123/test.hbs.txt?file_name=test.txt