Build a request
A request is a method, a URL, and optional params, headers, body and auth. This page covers the editor from top to bottom, and how to save, rename and duplicate what you build.
New to the app? Do Send your first request first.
Choose a method
Click the method box left of the URL and pick one.
| Method | What it does |
|---|---|
| GET | Reads data without changing anything. |
| POST | Sends data to create something or trigger an action. |
| PUT | Replaces a resource with the data you send. |
| PATCH | Changes part of a resource, leaving the rest as it is. |
| DELETE | Removes a resource. |
| QUERY | A safe, read-only method like GET that can carry a body, for complex searches. |
| HEAD | Like GET, but only the headers come back, no body. |
| OPTIONS | Asks which methods and headers are allowed. Browsers send it before cross-origin requests. |
The list is fixed: you cannot type a method of your own.
About QUERY
QUERY is a newer HTTP method for searches that are too large or too structured for a URL. The search goes in the body, and the request is still safe to repeat. Use it only with servers that support it.
Any method except HEAD sends the body you set on the Body tab, GET included. HEAD never sends a body.
Enter the URL
Type the address in the URL field.
https://api.example.com/v1/users- No scheme. If you leave out
https://, ApiWorkbench useshttps. Typehttp://yourself for plain HTTP, for examplehttp://localhost:8080/health. - Variables.
{{name}}inserts a variable, for example{{baseUrl}}/users. See Variables and environments. - Dynamic variables.
{{$guid}},{{$timestamp}}and others make a fresh value on every send. See Dynamic variables. - Path variables. A segment such as
:idin/users/:idgets a row on the Params tab where you set its value. See Query params and path variables. - Query string. You can type
?page=2straight into the URL, or add rows on the Params tab. Rows are added after anything already in the URL.
Send and cancel
Select Send, press Enter in the URL field, or press Ctrl + Enter anywhere in the window.
While the request runs, Send becomes a Cancel button. Select it to stop waiting and cancel the request.
If the request cannot be built, the response area shows the reason instead of a status, for example Request URL is empty. or Invalid URL.
The editor tabs
| Tab | Use it for | Guide |
|---|---|---|
| Params | Query parameters and path variables | Query params and path variables |
| Headers | Request headers | Headers |
| Body | JSON, text, XML, forms, files, GraphQL | Request bodies |
| Auth | Tokens, passwords, keys and signatures | Authorization |
| Scripts | JavaScript before and after the request | Scripts |
| Tests | Checks on every response | Tests |
| Captures | Saving response values into variables | Captures |
| Settings | Redirects, certificates, URL encoding, cookies, timeout | Request settings |
| Docs | A description kept with the request | Collection docs |
The tab labels show what a request contains at a glance:
| Label | Meaning |
|---|---|
| Params (2), Headers (1) | The number of rows that are switched on |
| Body • JSON | The body type |
| Auth • Bearer Token | The auth type |
| Tests (3), Captures (1) | How many are defined |
| Scripts •, Settings •, Docs • | The tab is not empty, or a setting differs from the default |
ApiWorkbench remembers which editor tab you had open for each request tab.
Describe the request
Open the Docs tab and write in Description: what the request does and what it needs. The text is saved with the request and included in exports and generated docs.
The More menu
The three dots right of Send open a menu.
| Item | What it does |
|---|---|
| Save to collection… | Opens the save dialog, also for a request that is already saved, so you can rename it or move it to another collection |
| Run repeatedly / on interval… | Opens the runner with this request |
| Load test (parallel calls)… | Opens the load tester with this request |
| Code snippet… | Shows the request as code |
| Copy as cURL | Copies the request as a curl command, with {{variables}} kept as written |
| Import cURL… | Opens a pasted curl command as a new tab. See Import cURL. |
Save a request
A new request is a draft. It is not kept until you save it in a collection.
Select Save… above the URL, on the right.
Type a Request name.
Choose a Collection, or type a name in Or create a new collection to make one.
If you have no collections yet, the dialog shows only New collection name.
Select Save.
After the first save, the button reads Save and saves straight into the same collection. Ctrl + S does the same. Saving keeps the request's place in the collection.
A dot next to the name, and on the request tab, means the tab has changes that are not saved yet.
WARNING
Open tabs are not restored when you restart the app, and closing a tab does not ask about unsaved changes. Save a request before you close its tab or the app.
Rename a request
Click the request name above the URL.
Type the new name in the Rename request dialog and select Rename.
Save the request to keep the new name.
Duplicate a request
Duplicate works on saved requests.
Open Collections in the side panel and find the request.
Open the … menu on its row.
Select Duplicate.
A copy named with (copy) at the end appears right below the original, in the same folder. Open it and change what you need.
To copy a request that is not saved yet, save it first, or use Copy as cURL and Import cURL….
Delete a request
Open the … menu on the request's row in Collections and select Delete.
WARNING
Delete removes the request from the collection right away, without asking. To get it back, restore an earlier version of the collection from its version history.
Work in request tabs
Each open request has its own tab in the top bar, with its own response.
| Action | How |
|---|---|
| New HTTP request | + or Ctrl + T |
| New WebSocket, Socket.IO, MQTT, Server-Sent Events or gRPC tab | The arrow right of + |
| Switch tab | Click it |
| Close a tab | The × on the tab, or Ctrl + W for the active tab |
- A tab shows the method and the request name. A draft that has a URL shows the URL instead of Untitled request.
- Opening a saved request that is already open switches to its tab instead of opening a second one.
- Closing the last tab opens a fresh empty one.
- A tab is a working copy. Changes reach the collection only when you save.