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

# Upgrading event ingestion

> Move POST /events from the deprecated unversioned API to version 2026-04-01 — add the Alguna-Version header and rename uniqueId and eventName to snake_case.

The unversioned API — the one that takes no `Alguna-Version` header — is deprecated and will be retired. If usage events are the only thing you send to Alguna, this is the whole migration: add one header and rename two fields. Nothing else about your ingestion pipeline changes — same host, same API key, same path, same batch size, same response.

This page covers `POST /events` only. For the rest of the API, see [Overview](/docs/api-reference/v2/overview), and for what events are and how they reach an invoice, see [Send usage events](/docs/billable-metrics/send-usage).

## What changes

|                                      | Unversioned                        | `2026-04-01`                           |
| ------------------------------------ | ---------------------------------- | -------------------------------------- |
| Host                                 | `https://api.alguna.io`            | unchanged                              |
| Path                                 | `/events`                          | unchanged                              |
| Authentication                       | `Authorization: Bearer <API-KEY>`  | unchanged                              |
| Version header                       | none                               | `Alguna-Version: 2026-04-01`, required |
| Event id field                       | `uniqueId`                         | `unique_id`                            |
| Event name field                     | `eventName`                        | `event_name`                           |
| `account`, `timestamp`, `properties` |                                    | unchanged                              |
| Events per request                   | 100                                | unchanged                              |
| Response                             | `{ "ingested": [], "failed": [] }` | unchanged                              |

Two field renames and one header. Everything else you already send is already correct.

## Before and after

Unversioned request body:

```json theme={null}
{
  "events": [
    {
      "uniqueId": "d73bcda34d42df7868a237615e4b028b",
      "account": "customerA",
      "eventName": "data_ingested",
      "timestamp": "2026-03-09T15:03:17Z",
      "properties": {
        "volume_kb": 312845,
        "dataset_id": "45jkhp"
      }
    }
  ]
}
```

`2026-04-01` request body:

```json theme={null}
{
  "events": [
    {
      "unique_id": "d73bcda34d42df7868a237615e4b028b",
      "account": "customerA",
      "event_name": "data_ingested",
      "timestamp": "2026-03-09T15:03:17Z",
      "properties": {
        "volume_kb": 312845,
        "dataset_id": "45jkhp"
      }
    }
  ]
}
```

## Making the call

```bash theme={null}
curl -X POST "https://api.alguna.io/events" \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "unique_id": "d73bcda34d42df7868a237615e4b028b",
        "account": "customerA",
        "event_name": "data_ingested",
        "timestamp": "2026-03-09T15:03:17Z",
        "properties": { "volume_kb": 312845 }
      }
    ]
  }'
```

## What the response means

Both versions return the same two arrays:

```json theme={null}
{
  "ingested": ["d73bcda34d42df7868a237615e4b028b"],
  "failed": []
}
```

`ingested` and `failed` hold `unique_id` values. A `200` does not mean every event was accepted — check `failed` on every response. An event lands in `failed` when it is well-formed JSON but cannot be processed, and the rest of the batch still goes through.

Per-event handling is unchanged from the unversioned API. An event that does not parse — a `timestamp` that is not RFC 3339, a `unique_id` that is not a string, an array element that is not an object — is reported in `failed` while the rest of the batch ingests. One bad event never costs you the batch it arrived in.

A `4xx` means the request envelope itself was wrong: no `events` array, an empty one, or more than 100 events. In that case nothing is ingested.

<Warning>
  A field the API does not recognise is ignored rather than rejected, so a **partial** rename does not fail — it succeeds with the wrong data. An event still carrying `uniqueId` is accepted with an empty `unique_id`, and one still carrying `eventName` is accepted with an empty `event_name`, which means it matches no metric. Rename both fields in the same change, and check a sandbox batch before deploying.
</Warning>

## Cutting over

Both APIs accept traffic during the move, so there is no coordinated switch to run.

1. Rename `uniqueId` to `unique_id` and `eventName` to `event_name` in the code that builds your event payloads.
2. Add the `Alguna-Version: 2026-04-01` header to the same request.
3. Send one batch to [sandbox](/docs/getting-started/testing) and confirm `ingested` lists your ids and `failed` is empty.
4. Deploy. Watch `failed` for one full billing cycle.
5. Confirm usage still lands on the expected metrics — see [Metrics reference](/docs/billable-metrics/metrics-reference).

## Checklist

* [ ] `uniqueId` renamed to `unique_id`.
* [ ] `eventName` renamed to `event_name`.
* [ ] `Alguna-Version: 2026-04-01` sent on every request, in the same deploy as the renames.
* [ ] `failed` checked on every response, not just the status code.
* [ ] Verified in sandbox before production.

If you also call endpoints other than `/events`, the version header applies to those too and their shapes change more than this one does. [Contact us](mailto:support@alguna.io) before you migrate them.