Event mutations API

The Event mutations API allows you to update the custom attributes of events that have already been ingested into Usermaven.

You can use this API to:

• Correct data errors

• Update event values after ingestion

• Add additional context to historical events

• Enrich events with data that becomes available later

For example, you can update a final order price, attach a discount code, or correct missing event attributes.

Important: This is a server-side API and must only be used from a trusted backend environment.

What this feature does

The Event mutations API allows you to:

• Update event attributes for existing events

• Look up events using custom attribute values

• Merge or replace event attribute data

• Retry updates safely with idempotency keys

The API supports:

• Event attribute mutations

• Event lookup by attribute

• Merge and replace update modes

• Idempotent mutation requests

Before you start

Before using the API:

1. Make sure you have access to your Usermaven workspace.

2. Retrieve your API credentials from Settings → Workspace:

   • API Key

   • Server Token

Your authentication token format is API_KEY.SERVER_TOKEN.

Authentication

This API uses the combined API_KEY.SERVER_TOKEN authentication token. For full details, see the API Authentication guide.

Minimal request example

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-10T14:30:00.000Z",
  "event_attributes": {
    "final_price": "149.99"
  },
  "idempotency_key": "order-price-fix-ORD-123"
}

Request fields

Field	Type	Required	Notes
event_id	String	Yes	The unique event ID to update
timestamp	String	Yes	ISO-8601 timestamp; must be in the same calendar month as the event
event_attributes	Object	Yes	Attributes to update
merge_mode	String	No	merge or replace
idempotency_key	String	Yes	Unique retry-safe request key
api_key	String	No	Authentication token