Requests & Responses
The Request Builder has a URL bar at the top, tabs for each part of the request, and the response viewer at the bottom. This page covers each part.
Method and URL
Choose a method from the dropdown: GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS. Then type the URL.
The URL must start with http:// or https:// after variables are filled in. Otherwise DotFetch stops with Invalid URL format and nothing is sent.
https://api.example.com/v1/users
{{BASE_URL}}/v1/users ← fine, if BASE_URL = https://api.example.com
api.example.com/v1/users ← Invalid URL format (no http/https)Query parameters
You can add query parameters in two places, and DotFetch sends both.
1. Directly in the URL bar
Whatever you type after ? is sent exactly as written. DotFetch doesn't re-encode it, so commas, +, and pre-encoded values arrive the way the API expects:
https://httpbin.org/get?ids=1,2,3&q=a+b&ts=2026-01-01T00:00:00%2B02:00
The server receives ids=1,2,3 (not ids=1%2C2%2C3), q=a+b, and the %2B untouched.
2. In the Params tab
Click + Add Parameter and fill in a key and value. Values typed here are encoded for you, so you can write them plainly:
| Key | Value | Sent as |
|---|---|---|
search | hello world | search=hello%20world |
filter | a&b | filter=a%26b |
ids | 1,2,3 | ids=1%2C2%2C3 |
Params-tab rows are added after the URL-bar parameters. Use the checkbox on a row to switch it off without deleting it. Disabled rows and rows with an empty key are not sent.
Tip: If an API needs a value sent unencoded (a literal comma, say), put it in the URL bar instead of the Params tab.
Repeated keys are kept in order:
https://api.example.com/items?tag=red&tag=blue
sends both tag=red and tag=blue.
Headers
Open the Headers tab and add rows. Each row has a checkbox, so you can switch a header off without losing it.
Accept: application/json
X-Request-Source: dotfetch
X-Tenant: {{TENANT_ID}}Header names may only contain letters, digits, -, and _. A row whose name has spaces or other characters (X Tenant, X.Tenant) is skipped.
Values can use {{VARIABLES}}. To add an Authorization header, use the Auth tab rather than typing it here. The Auth tab always wins over a manual Authorization row.
Body
The Body tab takes raw text. DotFetch sends it byte for byte, with {{VARIABLES}} filled in. It doesn't reformat JSON, add or remove spaces, or trim whitespace. That matters when a server checks a signature computed over the exact body (see HMAC signing).
JSON
{
"email": "{{TEST_EMAIL}}",
"plan": "pro"
}If the body is valid JSON and you haven't set a Content-Type header, DotFetch adds Content-Type: application/json automatically.
Form data or plain text
For anything that isn't JSON, set the Content-Type header yourself:
Content-Type: application/x-www-form-urlencoded
grant_type=password&username={{USER}}&password={{PASS}}
Request settings (⚙️)
The ⚙️ tab holds settings for this request. They are saved with it in a collection.
A new request starts with your defaults from VS Code Settings (dotfetch.timeout, dotfetch.retryCount, dotfetch.sslVerify). Change them here for one request without affecting the others. For example, set the default timeout to 30000 for a slow staging server and raise just one long report request to 120000.
| Setting | Range | What it does |
|---|---|---|
| Retry count | 0–5 | Retries when the server can't be reached (ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ECONNABORTED). It waits 1s, then 2s, 4s, and so on, never more than 10s between attempts. A 500 response is not retried, because the server did answer. |
| Timeout | 1000–300000 ms | How long to wait for a response before giving up. The default is 10000 (10 seconds). |
| SSL Verification | on / off | Turn off for https://localhost or self-signed certificates. While it's off, a ⚠️ SSL Ignored badge appears next to the URL. A saved request keeps the choice it was saved with. |
Sending and cancelling
Press Send or Ctrl+Enter. While the request runs, the button turns into Cancel ✕. Click it, or press Ctrl+Enter again, to stop the request. A cancelled request is removed from History.
The response viewer
| Part | What it shows |
|---|---|
| Status badge | The status code and text, such as 200 OK or 404 Not Found |
| Time | Milliseconds from Send until the response arrived |
| Size | Size of the response body |
| Body tab | The response body. Pretty formats and colours JSON; Raw shows the exact text. Copy copies it. |
| Headers tab | Every response header as a key-value table. The number on the tab is the header count. |
| Tests tab | Results of test() calls in your Post-Response script. It shows ✓ 3 / ✕ 1 counts and any failure messages. |
Large responses
| Response size | What happens |
|---|---|
| Up to 1 MB | Shown in full |
| 1 MB – 10 MB | The request succeeds, but only the first 1000 characters are shown, to keep VS Code responsive. Scripts still get the full body. |
| Over 10 MB | The request fails with an error, which protects VS Code's memory |
Notes
The Notes tab is free text saved with the request: what the endpoint does, which test account to use, a link to the API docs. A dot on the tab tells you a request has notes.