> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Web API Destination

[Web](#)[ Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/api)[ Package](https://www.npmjs.com/package/@walkeros/web-destination-api)

The web API destination sends events from the browser to any HTTP endpoint, with customizable data transformation and transport methods.

Where this fits

Web API is a **web destination** in the walkerOS flow:

Sends events from the browser to any HTTP endpoint using fetch, XHR, or beacon transport with customizable request formatting.

## Installation[​](#installation "Direct link to Installation")

```bash
npm install @walkeros/web-destination-api
```

## Configuration[​](#configuration "Direct link to Configuration")

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see [destination configuration](/docs/destinations#configuration). Package-specific fields live under `config.settings` and are listed below.

## Settings[​](#settings "Direct link to Settings")

| Property    | Type                           | Description                                      | More |
| ----------- | ------------------------------ | ------------------------------------------------ | ---- |
| `url*`      | `string`                       | The HTTP endpoint URL to send events to          |      |
| `headers`   | `Record<string, string>`       | Additional HTTP headers to include with requests |      |
| `method`    | `string`                       | HTTP method for the request                      |      |
| `transform` | `function`                     | Function to transform event data before sending  |      |
| `transport` | `'fetch' \| 'xhr' \| 'beacon'` | Transport method for sending requests            |      |

\* Required fields

## Mapping[​](#mapping "Direct link to Mapping")

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](/docs/mapping).

## Examples

### Custom payload

An order event is reshaped via a data mapping into a custom JSON body for the API endpoint.

Event

```json
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "7a0941ea88313ec1",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000502,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```json
{
  "data": {
    "map": {
      "order_id": "data.id",
      "amount": "data.total",
      "tax": "data.taxes",
      "shipping_cost": "data.shipping",
      "currency": "data.currency",
      "event_name": "name",
      "user_id": "user.id"
    }
  }
}
```

Out

```javascript
sendWeb("https://api.example.com/events", "{\"order_id\":\"0rd3r1d\",\"amount\":555,\"tax\":73.76,\"shipping_cost\":5.22,\"currency\":\"EUR\",\"event_name\":\"order complete\",\"user_id\":\"us3r\"}", {
  "headers": {
    "traceparent": "00-0a1b2c3d4e5f60718293a4b5c6d7e8f9-7a0941ea88313ec1-01"
  },
  "transport": "fetch"
})
```

### Entity action

A generic entity action event is forwarded to the configured API endpoint with the mapped data JSON body.

Event

```json
{
  "name": "entity action",
  "data": {
    "string": "foo",
    "number": 1,
    "boolean": true,
    "array": [
      0,
      "text",
      false
    ]
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "0bb45a879c1d939d",
  "trigger": "test",
  "entity": "entity",
  "action": "action",
  "timestamp": 1700000500,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```json
{
  "data": "data"
}
```

Out

```javascript
sendWeb("https://api.example.com/events", "{\"string\":\"foo\",\"number\":1,\"boolean\":true,\"array\":[0,\"text\",false]}", {
  "headers": {
    "traceparent": "00-0a1b2c3d4e5f60718293a4b5c6d7e8f9-0bb45a879c1d939d-01"
  },
  "transport": "fetch"
})
```

### Page view

A page view is POSTed to the configured API endpoint with the event data section as the JSON body.

Event

```json
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "396ccd0ce5d970ba",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000501,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```json
{
  "data": "data"
}
```

Out

```javascript
sendWeb("https://api.example.com/events", "{\"domain\":\"www.example.com\",\"title\":\"walkerOS documentation\",\"referrer\":\"https://www.walkeros.io/\",\"search\":\"?foo=bar\",\"hash\":\"#hash\",\"id\":\"/docs/\"}", {
  "headers": {
    "traceparent": "00-0a1b2c3d4e5f60718293a4b5c6d7e8f9-396ccd0ce5d970ba-01"
  },
  "transport": "fetch"
})
```

## Modes[​](#modes "Direct link to Modes")

* Integrated
* Bundled

```typescript
import { startFlow } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { collector, elb } = await startFlow({
  destinations: {
    api: {
      code: destinationAPI,
      config: {
        settings: {
          url: 'https://api.example.com/events',
        },
      },
    },
  },
});
```

Add to your `flow.json` destinations:

```json
"destinations": {
  "api": {
    "package": "@walkeros/web-destination-api",
    "config": {
      "settings": {
        "url": "https://api.example.com/events"
      }
    }
  }
}
```

[See bundled mode setup](/preview/pr-749/docs/getting-started/modes/bundled.md) | [CLI reference](/preview/pr-749/docs/apps/cli.md)

## Usage[​](#usage "Direct link to Usage")

### Basic usage[​](#basic-usage "Direct link to Basic usage")

```typescript
import { startFlow } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { collector, elb } = await startFlow({
  destinations: {
    api: {
      code: destinationAPI,
      config: {
        settings: {
          url: 'https://api.example.com/events',
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            Authorization: 'Bearer your-token',
          },
        },
      },
    },
  },
});
```

### Advanced usage with transform[​](#advanced-usage-with-transform "Direct link to Advanced usage with transform")

```typescript
import { startFlow } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { collector, elb } = await startFlow({
  destinations: {
    api: {
      code: destinationAPI,
      config: {
        settings: {
          url: 'https://api.example.com/events',
          transport: 'fetch',
          // data is the mapped data, or the event without a mapping
          transform: (data) =>
            JSON.stringify({ sent_at: Date.now(), payload: data }),
        },
      },
    },
  },
});
```

### With batching[​](#with-batching "Direct link to With batching")

Set `config.batch` to send events in one request per flush instead of one request per event. The options are in [Batch scheduling](/preview/pr-749/docs/mapping/rule.md#batch-scheduling).

Each flush is a single request whose body is a JSON array, one element per event. Mapping still applies per event, so an element is the event's mapped data when a rule produced some and the raw event otherwise. A `transform` runs per element, not once for the whole array. Batched requests carry no `traceparent` header: a batch can aggregate events from distinct traces, so there is no single identity to stamp.

Set `size` explicitly and keep it small: the `fetch` and `beacon` transports send with `keepalive`, and browsers reject a `keepalive` request once the bodies in flight exceed 64 KiB, while the default `size` is 1000 events. Such a flush fails without being reported (see [Transport methods](#transport-methods)). A full event is around 0.5 to 1 KiB.

```typescript
import { startFlow } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { collector, elb } = await startFlow({
  destinations: {
    api: {
      code: destinationAPI,
      config: {
        batch: { wait: 1000, size: 25 },
        settings: {
          url: 'https://api.example.com/events',
        },
      },
    },
  },
});
```

## Transport methods[​](#transport-methods "Direct link to Transport methods")

* **fetch** (default): `fetch` with `keepalive`, so the browser completes the request even when the page unloads first
* **xhr**: a synchronous `XMLHttpRequest`
* **beacon**: `navigator.sendBeacon()`, always a `POST` without the configured `headers`

The destination ignores the response: a failed request (an error status or a network error) is not reported, the event counts as delivered and does not reach the dead-letter queue.