What's new ⬇ Download Reportworq
⬇ Guide PDF

Try the API in Reportworq#

The API tester is a one-page HTTP client built into Reportworq. Use it to try a Reportworq automation API command, such as ping or pause/status, and see exactly what the server answers, before you write a script or a Turbo Integrator process around it. You can also use it to call any other HTTP address the Reportworq server can reach.

Before you begin#

Open the API tester#

There are three entry points. All of them open the same screen.

Send a command from the list#

The fastest way to a working request is to load a command.

  1. Choose Load command at the top right. The list is grouped: Run jobs (api/v1), Pause job execution (api/v1), Server (api/v1) and Secret rotation (api/v6).
  2. Pick a command, for example GET ping. Reportworq fills in the method, the address (built on your server's own address), the headers, any query parameters and a sample body. If you set an External URL under Settings, Configuration, Web Server, the address is built on that; otherwise it uses the address your browser is on.
  3. Fill in the markers. Wherever you must supply a value, the request holds a marker such as <<enter API access token here>>, shown in an orange box. A yellow Fill in before sending callout lists every marker still in place. Paste your own token over the marker, and replace the others (a job name, a job id, a history id) with real values.
  4. Choose Send (or press Ctrl+Enter).

A request with a marker still in it is never sent. The tester shows Not sent and names the marker, so a placeholder can never reach your server by mistake. Markers in a disabled header, a disabled query row, or a body you are not sending do not count.

Each loaded command also shows a one-line description and a Documentation link to the guide page for that command, which opens in a new tab.

The list covers every command Reportworq exposes: ping, list, run, status, cancel, output (and a HEAD form that only checks the file exists), webhook (a contribution campaign trigger), pause, pause/status, resume, cancelall, version, license, and the two secret rotation calls. The two retired commands, info and history, are listed too, marked deprecated, so you can see that they answer 404 on purpose. version and license need a signed-in bearer token rather than an API access token, and their marker says so.

Build or change a request#

You can edit anything that a command loaded, or start from nothing and type an address.

Method and address. Choose GET, POST, PUT, PATCH, DELETE or HEAD, and type a full http:// or https:// address in the address box. A relative address is refused.

Query. The Query tab lists the query parameters as rows, each with a checkbox, a name and a value. The list and the address stay in step: change one and the other follows. Clear a checkbox to leave a parameter out of the address without losing the row. Parameters are encoded for you.

Headers. The Headers tab works the same way. A command that needs a token loads with the right header already present, for example accessToken. Add any other header you need. If you add a Content-Type header, it replaces the one the tester would have chosen.

Body. The Body tab offers four types:

Body type What is sent
None No body.
Text The text you type, as text/plain unless you set a Content-Type header.
JSON The JSON you type in a JSON editor, as application/json unless you set a Content-Type header.
Form A url-encoded form built from name and value rows.

A HEAD request never sends a body.

Options. The Options tab has three settings:

While a request is running the Send button becomes Cancel, which stops waiting for it.

Read the response#

When the server answers, the status line shows the status code and reason (colored by class: success, redirect, client error, server error), how long it took, and the size of the body. If redirects were followed, it also says how many and where the last one led.

Four views show the same response:

View Shows
Raw The response as it came back: the status line, every header, a blank line, then the body. This is the default after a send.
Text The body as plain text.
JSON The body formatted and indented. If the body is not valid JSON, the tester says Not JSON and shows the text instead.
Headers The response headers in a table, with a count on the tab.

Copy body copies the whole body. A body that does not look like text (it contains binary data) is not displayed; the tester shows its size instead.

Limits. The tester reads at most 5 MB of a response body and says Body cut off when there was more. A view shows at most 1 MB of text, with a note at the end, though Copy body still copies everything that was read. To download a large output file, use a script or a browser and the output command.

When there is no response. If the server could not be reached, the tester says why in plain words instead of a stack trace: the host name was not found, the connection was refused on that port, there is no route, the connection timed out, or a secure connection could not be set up (with a pointer to Accept self-signed certificate). A canceled request is shown as Canceled. When the server could not make the connection at all (it timed out, was refused, or the name was not found), No response. names the host, the port and the reason. If the address is the Reportworq server's own public address, the tester also offers Use http://localhost:NNNN, which swaps in the address the server listens on and keeps the rest of the URL. A server in a container or behind a reverse proxy often cannot reach itself through its public name, so choose it and send again.

Copy as cURL#

Copy as cURL turns the request on screen into a command for a bash-style shell (bash, zsh, Git Bash or WSL) and puts it on your clipboard. It carries the method, the quoted address, one -H per enabled header, the body, -L when redirects are followed, -k when a self-signed certificate is accepted, and --max-time for the timeout. The content type the tester chooses for a Text or JSON body is written out, so the command sends the same request. If the browser does not allow copying, the command is shown in a window to copy by hand.

Use it to take a request you proved here into a script, a scheduler or a ticket. The command contains whatever you pasted into the request, including your token, so treat it as a secret.

What stays and what is lost#

Where the request runs, and what it exposes#

Common problems#

You see What it means and what to do
Not sent, naming a marker A marker such as <<enter API access token here>> is still in the address, an enabled header, an enabled query row or the body. Replace it, or clear the checkbox of a row you do not need.
No response: could not establish a secure connection The server's certificate is not trusted. If you trust that server, turn on Accept self-signed certificate on the Options tab.
No response: could not connect to the Reportworq server's own address, with a Use http://localhost:NNNN button The request is sent from the server, which may not be able to reach itself through its public name (containers, reverse proxies). Choose the button and send again.
No response: refused the connection Wrong port, or the service is not running. Check the port in the address.
401 from an /api/v1 command The token is wrong, missing or disabled. See Run a job by API.
404 from info or history Expected. Both commands were retired.
A 3xx status, with Redirect, not followed The server wants you at another address. Turn on Follow redirects, or send to the new address.

Going deeper. For the two ways the API is delivered and their key models, read The automation API. For each command's parameters, see Run a job by API and Pause and resume by API.

Feedback on this page

Comments, questions, requests, or something missing or unclear? Email us - the page you are on is filled in for you.

Email feedback on this page

Or write to support@reportworq.com directly.