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#
- Only a system administrator can use the API tester. The button is not shown to anyone else, and a request is refused for anyone else even if they reach the page some other way.
- Have the credential for the command you want to try. For the
/api/v1job commands that is the access token of a Local API key (Settings, Configuration, API). For the secret rotation API it is a rotation key (Settings, Security, Secret Rotation). The tester never fills in a stored key for you: you paste it. - The API tester is not offered on a server that runs in load balancer mode.
Open the API tester#
There are three entry points. All of them open the same screen.
- Settings, Integrations, API tester. Opens the tester with whatever you last had in it (see What stays and what is lost).
- Settings, Configuration, API, Open in API tester, next to the Local API keys. Opens the tester on the
pingcommand. If you have unsaved changes on that tab, Reportworq asks you to discard them first. - Settings, Security, Secret Rotation, Open in API tester on the discovery call, or the paper plane button on a target row. The row version opens the rotation call with that target's store, workspace, id and field already filled in.
Send a command from the list#
The fastest way to a working request is to load a command.
- 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).
- 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.
- 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. - 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:
- Timeout (seconds). How long to wait for a complete response. The default is 100 and it accepts 1 to 600. A request that takes longer is stopped and reported as timed out.
- Accept self-signed certificate. Turn this on to call a server whose certificate is not trusted, such as a test server or the Reportworq server itself on a development certificate. It applies to that one request only. Leave it off for anything else, because it also skips the check that you are talking to the server you meant to.
- Follow redirects. Off by default, so a
301,302or another redirect is shown to you, with a note saying where it points, instead of being followed silently. Turn it on to follow up to 10 redirects. As with cURL, a redirect to a different host, or fromhttpstohttp, does not carry yourAuthorization,accessToken, rotation key or cookie headers with it.
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#
- Moving to another screen and back keeps your work. The request you were building and the last response are held while you stay on the same page load. Open Settings, Integrations, API tester again and they are there. Leaving the screen does stop a request that is still running.
- Loading a command or opening the tester from another screen replaces the request and clears the last response. Choosing Open in API tester from Configuration or Security starts a new request.
- Reloading the page, or signing out, loses everything. Nothing is saved on the server or in your browser, and there is no history of past requests.
Where the request runs, and what it exposes#
- The request is sent from the Reportworq server, not from your browser. It therefore reaches what the server can reach, which can differ from what your computer can reach: an address that is only visible from the server's network works, and an address that is only visible from your desk may not. To try Reportworq's own API, the default address is the server's own address, so the call goes from the server to itself.
- Each request starts clean. There are no shared cookies, connections or certificate exceptions between requests.
- Secrets are never shown or filled in for you. A stored API key, rotation key or password is never placed into a request or shown on screen. You paste your own value over a marker.
- Each send is logged, without its contents. The server log records one line per request with the method, the host (not the path or query, and never a user name or password written into the address), the status and how long it took, and the name of the person who sent it. Header values and bodies are never logged, and the tester does not write them to any other record.
- Administrators can reach internal addresses with it. Because it sends from the server, a system administrator can use it to call hosts on your internal network. That is the point of the tool, and it is why it is limited to system administrators.
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 pageOr write to support@reportworq.com directly.