Send an event

An event from a site's own backend, counted like one from the script. `Idempotency-Key` makes a retry safe: the same key counts once.

# Send an event

> tidekeeper's API reference: https://tidekeeper.eu/docs/api/post-sites-site-events

`POST /api/v1/sites/{site}/events`

An event from a site's own backend, counted like one from the script. `Idempotency-Key` makes a retry safe: the same key counts once.

## What to send

`EventIn`: An event sent from a backend (IN-09), counted on the same model as one the script sends.

- `currency` (string or null)
- `name` (string or null): The event's name. Leave it out to count a view.
- `props` (object)
- `referrer` (string or null)
- `url` (string, needed): The page it happened on: a full address on one of the site's hostnames.
- `value` (number or null): An amount with its currency: `{ "amount": 29.0, "currency": "EUR" }`.
- `visitor` (EventVisitor or null)

## The answer

202, `EventTaken`

- `outcome` (string, needed): `counted`, `left_out` with why, or `repeated` for a key seen before.
- `why` (string or null)

## Asking

```sh
curl -X POST https://tidekeeper.eu/api/v1/sites/example.org/events \
    -H "Authorization: Bearer $TIDEKEEPER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "Order", "url": "https://example.org/checkout", "props": {"plan": "Tide"}}'
```

What to send

EventIn An event sent from a backend (IN-09), counted on the same model as one the script sends.

currency

string or null

name

string or nullThe event's name. Leave it out to count a view.

props

object

referrer

string or null

url

stringneededThe page it happened on: a full address on one of the site's hostnames.

value

number or nullAn amount with its currency: `{ "amount": 29.0, "currency": "EUR" }`.

visitor

EventVisitor or null

The answer

Status 202

EventTaken

outcome

stringneeded`counted`, `left_out` with why, or `repeated` for a key seen before.

why

string or null

Asking

curl -X POST https://tidekeeper.eu/api/v1/sites/example.org/events \
    -H "Authorization: Bearer $TIDEKEEPER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "Order", "url": "https://example.org/checkout", "props": {"plan": "Tide"}}'

const answer = await fetch("https://tidekeeper.eu/api/v1/sites/example.org/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TIDEKEEPER_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name": "Order", "url": "https://example.org/checkout", "props": {"plan": "Tide"}}),
}).then((r) => r.json());