Skip to main content
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, and for what events are and how they reach an invoice, see Send usage events.

​
What changes

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

​
Before and after

Unversioned request body:
2026-04-01 request body:

​
Making the call

​
What the response means

Both versions return the same two arrays:
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.
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.

​
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 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.

​
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 before you migrate them.