> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpostchi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Before scripts

> Modify a request's method, URL, headers, or body before it is sent.

Before scripts run immediately before Postchi sends a request. You receive the request object and can mutate it freely — whatever state it's in when the script finishes is what gets sent.

## File naming

Place a file named `<request-name>.before.js` in the same folder as your request file:

```
requests/
  auth/
    login.chttp
    login.before.js   ← runs before login.chttp
```

For a script that applies to every request in a folder, create `before.js` in that folder:

```
requests/
  auth/
    before.js         ← runs before every request in auth/ and subfolders
    login.chttp
    refresh.chttp
```

<Note>
  The folder-level `before.js` runs first, then the request-level `<name>.before.js`. This means the request-level script always sees changes made by the folder-level script.
</Note>

## Available context

Postchi injects these variables into every before script:

| Variable  | Type     | Description                                                                        |
| --------- | -------- | ---------------------------------------------------------------------------------- |
| `request` | object   | The request about to be sent. **Mutating this object changes what Postchi sends.** |
| `env`     | object   | All active environment variables as string key-value pairs. Read-only.             |
| `fetch`   | function | The global `fetch` function.                                                       |

### The `request` object

| Property          | Type           | Description                                                |
| ----------------- | -------------- | ---------------------------------------------------------- |
| `request.method`  | string         | HTTP method, e.g. `"GET"`                                  |
| `request.url`     | string         | Full URL including any template variables already resolved |
| `request.headers` | object         | Headers as `{ name: value }` pairs                         |
| `request.body`    | string \| null | Request body as a string, or `null`                        |

## Examples

### Add a dynamic header

```javascript theme={null}
// Add a timestamp to every request
request.headers['X-Request-Time'] = new Date().toISOString();
```

### Build the URL from environment variables

```javascript theme={null}
// Append a version query parameter from the environment
const version = env.api_version || 'v1';
request.url = request.url + '?version=' + version;
```

### Modify a JSON body

```javascript theme={null}
// Add a nonce to the request body before sending
const body = JSON.parse(request.body);
body.nonce = Math.random().toString(36).slice(2);
request.body = JSON.stringify(body);
```

### Add a Bearer token from the environment

```javascript theme={null}
request.headers['Authorization'] = 'Bearer ' + env.api_token;
```

## Notes

<Warning>
  Before scripts cannot cancel a request — they can only transform it. If your script throws an error, Postchi surfaces the error and does not send the request.
</Warning>

<Tip>
  Put shared authentication logic in a folder-level `before.js` so you only write it once and it applies to every request in that folder automatically.
</Tip>