---
title: Fetch reference
description: Reference documentation for Allure Fetch | HttpExchange attachment schema | RedactionMatcher type | RedactionContext type
---

# Allure Fetch reference

## Attachment schema

Each HTTP exchange is recorded as a JSON attachment with content type `application/vnd.allure.http+json` and file extension `.httpexchange`. The root object has the following shape:

| Field           | Type     | Description                                                                                   |
| --------------- | -------- | --------------------------------------------------------------------------------------------- |
| `schemaVersion` | `1`      | Schema version. Always `1`.                                                                   |
| `start`         | `number` | Unix timestamp in milliseconds when the request started.                                      |
| `stop`          | `number` | Unix timestamp in milliseconds when the response or error was received.                       |
| `request`       | object   | Captured request data. See [Request](#request).                                               |
| `response`      | object   | Captured response data. Present only when a response was received. See [Response](#response). |
| `error`         | object   | Error information. Present only when the request failed. See [Error](#error).                 |

### Request

| Field     | Type              | Description                                                                                                                 |
| --------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `method`  | `string`          | HTTP method in uppercase, e.g. `"GET"`.                                                                                     |
| `url`     | `string`          | Request URL, including query parameters in their original unredacted form.                                                  |
| `headers` | `{name, value}[]` | Request headers after redaction. Omitted when there are no headers.                                                         |
| `query`   | `{name, value}[]` | Query parameters parsed from the URL, after redaction. Omitted when there are no query parameters.                          |
| `cookies` | `Cookie[]`        | Cookies parsed from the `Cookie` request header, after redaction. Omitted when there are no cookies. See [Cookie](#cookie). |
| `body`    | object            | Request body. Present only when `captureRequestBody` is `true` and a body was sent. See [Body](#body).                      |

### Response

| Field        | Type              | Description                                                                                                                                |
| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`     | `number`          | HTTP status code.                                                                                                                          |
| `statusText` | `string`          | HTTP status text.                                                                                                                          |
| `headers`    | `{name, value}[]` | Response headers after redaction. Omitted when there are no headers.                                                                       |
| `cookies`    | `Cookie[]`        | Cookies parsed from `Set-Cookie` response headers, after redaction. Omitted when there are no `Set-Cookie` headers. See [Cookie](#cookie). |
| `body`       | object            | Response body. Present only when `captureResponseBody` is `true` and a body was received. See [Body](#body).                               |

Request and response bodies are captured from cloned `Request` and `Response` objects before they are consumed, so the `Response` returned to your test code remains fully readable.

### Body

| Field         | Type                 | Description                                                                                                                                         |
| ------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contentType` | `string`             | Value of the `Content-Type` header. Absent when no `Content-Type` header is present.                                                                |
| `encoding`    | `"utf8" \| "base64"` | Encoding used for `value`. Present for all captured bodies except multipart. See [Body encoding](#body-encoding).                                   |
| `value`       | `string`             | The captured body content, encoded per `encoding`. Present for all captured bodies except multipart.                                                |
| `size`        | `number`             | Body size in bytes. See [Body size](#body-size).                                                                                                    |
| `truncated`   | `boolean`            | `true` when the body exceeded `maxBodySize` and was cut off.                                                                                        |
| `form`        | `{name, value}[]`    | Structured fields parsed from a `application/x-www-form-urlencoded` body, after redaction. See [URL-encoded form bodies](#url-encoded-form-bodies). |
| `stream`      | object               | Present alongside `value` when the body was truncated during streaming. See [Stream bodies](#stream-bodies).                                        |
| `parts`       | object[]             | Structured parts for `multipart/form-data` bodies. See [Multipart bodies](#multipart-bodies). Present instead of `value`, `encoding`, and `stream`. |

#### Body encoding

`encoding` is determined by the `Content-Type` header:

- **Text content types** — `text/*`, `application/json`, `application/javascript`, `application/x-www-form-urlencoded`, `application/xml`, or any type ending in `+json` or `+xml` → `"utf8"`.
- **No `Content-Type` header** → `"utf8"` (treated as text).
- **All other content types** → `"base64"`.

#### URL-encoded form bodies

When the content type is `application/x-www-form-urlencoded`, the body contains two representations of the same data:

- `value`: the re-serialized URL-encoded string, with sensitive fields replaced by the redaction placeholder.
- `form`: a structured `{name, value}[]` array with the same redaction applied.

#### Stream bodies

When a body exceeds `maxBodySize`, reading stops and the `stream` field appears alongside `value` to indicate partial capture:

| Field      | Type      | Description                                                                                                                                       |
| ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `complete` | `boolean` | Always `false` when `stream` is present.                                                                                                          |
| `type`     | `string`  | Stream type derived from the content type: `text/event-stream` → `"server-sent-events"`, `application/grpc` → `"grpc"`, all others → `"chunked"`. |

When `stream` is present, `value` contains the captured bytes up to `maxBodySize` and `truncated` is `true`.

#### Multipart bodies

When the content type is `multipart/form-data`, the body is parsed via the Web API `formData()` method and stored as a `parts` array instead of `value`. Each part is one of:

- **Text field**: `{ name, encoding: "utf8", value, size, truncated: false }`. Sensitive field values are redacted.
- **File part**: `{ name, fileName?, contentType?, size, truncated: false }`. File contents are not captured; only the metadata is recorded.

#### Body size

The `size` field uses the `Content-Length` header when present. If `Content-Length` is absent and the body was fully captured within `maxBodySize`, `size` is the actual byte count. If `Content-Length` is absent and the body was truncated, `size` is omitted.

### Cookie

Request cookies are parsed from the `Cookie` header. Response cookies are parsed from `Set-Cookie` headers.

| Field      | Type      | Description                                                             |
| ---------- | --------- | ----------------------------------------------------------------------- |
| `name`     | `string`  | Cookie name.                                                            |
| `value`    | `string`  | Cookie value, after redaction.                                          |
| `path`     | `string`  | `Path` attribute. Response cookies only.                                |
| `domain`   | `string`  | `Domain` attribute. Response cookies only.                              |
| `expires`  | `string`  | `Expires` attribute. Response cookies only.                             |
| `httpOnly` | `boolean` | `true` when the `HttpOnly` attribute is present. Response cookies only. |
| `secure`   | `boolean` | `true` when the `Secure` attribute is present. Response cookies only.   |
| `sameSite` | `string`  | `SameSite` attribute value. Response cookies only.                      |

### Error

Present when the request failed. In `fetch`, this occurs for transport errors (e.g., network failure), aborts (via `AbortController`), and response body stream errors. HTTP error responses (4xx and 5xx) are not errors — they produce a normal `response` with no `error` field.

| Field     | Type     | Description                                                   |
| --------- | -------- | ------------------------------------------------------------- |
| `name`    | `string` | The error's `name` property.                                  |
| `message` | `string` | The error message.                                            |
| `stack`   | `string` | Stack trace. Present only when `includeErrorStack` is `true`. |

## Redaction types

### `RedactionMatcher`

A `RedactionMatcher` controls whether a specific field value should be redacted. It can be any of the following:

- A **string**: redacts any field whose name equals the string, case-insensitively.
- A **`RegExp`**: redacts any field whose name matches the pattern.
- A **function** `(name: string, value: string, context: RedactionContext) => boolean`: redacts based on any logic, with access to the field name, value, and surrounding context.

```ts
withAllure(fetch, {
  redactHeaders: [
    "x-api-key", // exact name, case-insensitive
    /^x-internal-/i, // regex on the header name
    (name, value) => value.startsWith("sk-"), // match on the value itself
  ],
});
```

### `RedactionContext`

The `context` argument passed to a function `RedactionMatcher`:

| Property   | Type                                        | Description                                                                                                             |
| ---------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `kind`     | `"header" \| "query" \| "cookie" \| "form"` | Which category is being evaluated.                                                                                      |
| `name`     | `string`                                    | The field name.                                                                                                         |
| `value`    | `string`                                    | The field value.                                                                                                        |
| `url`      | `string \| undefined`                       | The request URL.                                                                                                        |
| `request`  | `Request \| undefined`                      | The Web API `Request` object.                                                                                           |
| `response` | `Response \| undefined`                     | The Web API `Response` object. Present only when evaluating response-phase fields (response headers, response cookies). |