Skip to main content

Scripting ›Request & Response

Auf GitHub bearbeiten

Diese Dokumentation ist auf Englisch verfügbar.

dotfetch.request & dotfetch.response

dotfetch.request (Pre-Request only)

The request that's about to be sent. Anything you change here is what goes out.

PropertyTypeReadWrite
methodstring✅✅
urlstring✅✅
paramsobject with methods✅✅
headers{ [name]: string }✅✅
bodystring✅✅

Remember: in a Pre-Request script, {{VARIABLES}} haven't been filled in yet. Every value below still contains them. Use dotfetch.env.resolve() when you need the final value.

The examples on this page use this request:

CODE
POST {{BASE_URL}}/orders?page=1&tag=new&tag=urgent
Content-Type: application/json
X-Client: web

{"item":"book","qty":2}

method

JS
dotfetch.request.method;            // 'POST'
dotfetch.request.method = 'put';    // stored as 'PUT', always upper-case

url

The URL without the query string. The query lives in params.

JS
dotfetch.request.url;   // '{{BASE_URL}}/orders'

Change it to send the request somewhere else:

JS
dotfetch.request.url = '{{BASE_URL}}/v2/orders';

If the new URL contains a ?query, those parameters are added to the existing ones:

JS
dotfetch.request.url = '{{BASE_URL}}/orders?debug=1';
// sent: …/orders?page=1&tag=new&tag=urgent&debug=1

params

Query parameters, in order, with repeated keys kept. You can use methods or plain property access.

MethodExampleResult
get(key)params.get('tag')'new', the first match, or undefined
getAll(key)params.getAll('tag')['new', 'urgent']
has(key)params.has('page')true
set(key, value)params.set('page', '2')Replaces the first page and removes any other page. Adds it if missing.
append(key, value)params.append('tag', 'vip')Adds another tag and keeps the existing ones
delete(key)params.delete('tag')Removes every tag
entries()params.entries()[['page','1'], ['tag','new'], ['tag','urgent']]

Property shortcuts do the same thing:

JS
const p = dotfetch.request.params;

p.page;            // same as p.get('page')     → '1'
p.page = 3;        // same as p.set('page', '3')
delete p.tag;      // same as p.delete('tag')
'page' in p;       // same as p.has('page')     → true

Example: add pagination and a cache-buster.

JS
const p = dotfetch.request.params;
p.set('limit', dotfetch.env.get('PAGE_SIZE') ?? '20');
p.set('_', String(Date.now()));
sent: …/orders?page=1&tag=new&tag=urgent&limit=20&_=1767225600000

Parameters you didn't touch keep their original encoding from the URL bar. Parameters you set or change are URL-encoded for you: p.q = 'a b&c' is sent as q=a%20b%26c.

headers

A plain object. Change one header by assigning to its name:

JS
const h = dotfetch.request.headers;

h['X-Timestamp'] = String(Date.now());   // add or change
delete h['X-Client'];                    // remove
h['Content-Type'];                       // 'application/json'

Assigning a whole object replaces all headers:

JS
dotfetch.request.headers = { Accept: 'application/xml' };
// Content-Type and X-Client are gone; only Accept is sent

Notes:

  • Header names are matched exactly as written here. h['content-type'] is undefined if the request has Content-Type.
  • Header values should be strings. Use String(...) for numbers.
  • Header names with spaces or symbols other than - and _ are dropped when the request is sent.
  • Authorization set here is replaced by the Auth tab unless Auth is No Auth (details).

body

The raw body text.

JS
dotfetch.request.body;   // '{"item":"book","qty":2}'

Assign a string to send it exactly:

JS
dotfetch.request.body = 'plain text';

Assign an object or array and it's converted to JSON for you:

JS
const order = JSON.parse(dotfetch.request.body);
order.qty = 5;
order.requestedAt = new Date().toISOString();
dotfetch.request.body = order;
// sent: {"item":"book","qty":5,"requestedAt":"2026-01-01T00:00:00.000Z"}

The body you set is sent byte for byte, after {{VARIABLES}} are filled in. Nothing reformats it, so a signature computed over it stays valid.


dotfetch.response (Post-Response only)

The response that came back. It's read-only.

PropertyTypeExample
statusnumber201
timenumber312 (milliseconds)
headers{ [name]: string }{ 'content-type': 'application/json; charset=utf-8', … }
bodystring'{"id":42,"name":"Ada"}'
json()any{ id: 42, name: 'Ada' }

The Post-Response script only runs when a response arrives, which includes 4xx and 5xx. It doesn't run when the server can't be reached.

status and time

JS
if (dotfetch.response.status >= 500) {
  console.warn('Server error after', dotfetch.response.time, 'ms');
}

headers

Header names are always lower-case:

JS
dotfetch.response.headers['content-type'];   // 'application/json; charset=utf-8'
dotfetch.response.headers['x-ratelimit-remaining'];   // '58'
dotfetch.response.headers['Content-Type'];   // undefined  ← wrong case

body and json()

body is always a string. For JSON responses it holds the JSON text (spacing may differ from what the server sent).

json() parses the body for you:

JS
const user = dotfetch.response.json();
user.id;          // 42
user.roles[0];    // 'admin'

If the body isn't valid JSON, json() throws Response body is not valid JSON. Guard it when an endpoint can return HTML or plain text, for example on errors:

JS
const type = dotfetch.response.headers['content-type'] ?? '';
if (type.includes('application/json')) {
  dotfetch.env.set('ORDER_ID', String(dotfetch.response.json().id));
}

Very large responses

Scripts always get the full body, even when the viewer only shows the first part of a response over 1 MB. Responses over 10 MB fail before any script runs.

Request & Response · DotFetch Docs | dotsuite