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 using 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

3. Copy:

   • API Key

   • Server Token

Your authentication token format is API_KEY.SERVER_TOKEN

---

Authentication

You can authenticate requests using one of the following methods.

1. Query parameter:

POST /v1/event-mutation?token=API_KEY.SERVER_TOKEN

2. Authorization header

Authorization: Bearer API_KEY.SERVER_TOKEN

3. Request body field

{ "api_key": "API_KEY.SERVER_TOKEN" }

Authentication priority

If authentication is provided in multiple places, Usermaven uses the following priority order:

1. Query parameter

2. Authorization header

3. Request body field

---

Mutate event attributes

Use this endpoint to update the event_attributes of an existing event.

Endpoint: POST https://api.usermaven.com/v1/event-mutation

Request fields

Field	Type	Required	Description
event_id	UUID string	Yes	Unique identifier of the event
timestamp	ISO 8601 datetime	Yes	Timestamp near the original event time. Does not need to be exact, but must be 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

Minimal 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"
}

Full example

{
  "api_key": "um_prod_abc.550e8400-e29b-41d4-a716-446655440001",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-10T14:30:00.000Z",
  "event_attributes": {
    "final_price": "149.99",
    "discount_code": "SPRING20"
  },
  "merge_mode": "merge",
  "idempotency_key": "order-price-fix-ORD-123"
}

Success response

{
  "status": 1,
  "mutation_id": "7f3c9a00-1234-5678-abcd-000000000001",
  "event_id": "550e8400-e29b-41d4-a716-446655440000"
}

---

Look up events by attribute

Use this endpoint to find events using a custom attribute value.

This is useful when you know a business identifier such as an order ID, but do not know the internal event_id.

Endpoint: POST https://api.usermaven.com/v1/event-mutation/lookup

Request fields

Field	Type	Required	Description
event_type	String	Yes	Event type to search
attribute_key	String	Yes	Attribute name. Pass an empty string "" together with an empty attribute_value to skip attribute filtering
attribute_value	String	Yes	Attribute value. Pass an empty string "" together with an empty attribute_key to skip attribute filtering
from_timestamp	ISO 8601 datetime	Yes	Search start time
to_timestamp	ISO 8601 datetime	Yes	Search end time
api_key	String	No	Authentication token

Example request

{
  "event_type": "order_completed",
  "attribute_key": "order_id",
  "attribute_value": "ORD-123",
  "from_timestamp": "2026-03-01T00:00:00.000Z",
  "to_timestamp": "2026-03-31T23:59:59.999Z"
}

Success response

{
  "data": [{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "order_completed",
  "event_attributes": {
  "order_id": "ORD-123",
  "price": "99.99"
  },
  "_timestamp": "2026-03-10 14:30:00",
  "_is_deleted": 0
  }]
}

Note: Lookup requests return a maximum of 10 matching events ordered by newest first.

---

Merge modes

The merge_mode field controls how new attributes are applied to the event.

Mode	Behaviour	Recommended use
merge	Adds or updates provided keys while preserving existing keys	Adding additional information. This is the default mode
replace	Replaces the entire event attributes object	Replacing the full attribute set

Merge example

Existing attributes

{ "price": "99.99", "currency": "USD" }

Payload

{ "price": "149.99" }

Result

{ "price": "149.99", "currency": "USD" }

Replace example

Existing attributes

{ "price": "99.99", "currency": "USD" }

Payload

{ "price": "149.99" }

Result

{ "price": "149.99" }

---

Idempotency

The idempotency_key field makes mutation requests safe to retry.

If a request times out or fails temporarily:

• Retry the request using the same idempotency_key

• Usermaven will return the original response

• The mutation will not be applied twice

If the same key is reused with a different event_id, the API returns 409 Conflict

---

Restrictions and limits

Constraint	Value
Maximum event_attributes size	10 KB
Lookup result limit	10 events
System event mutations	Not supported

---

System events cannot be mutated

The following event types are reserved and cannot be updated:

• Any event starting with $, for example $autocapture

• pageview, user_identify, group, lead

Attempting to mutate these events returns 422 Unprocessable Entity

---

Error reference

HTTP Status	Description
401 Unauthorized	Invalid or missing token
404 Not Found	Event not found
409 Conflict	Idempotency key reused with another event
422 Unprocessable Entity	Invalid payload or unsupported event
500 Internal Server Error	Internal mutation failure

---

End-to-end example

This example demonstrates the complete workflow for correcting an order price.

Step 1 — Find the event

curl -X POST "https://api.usermaven.com/v1/event-mutation/lookup?token=API_KEY.SERVER_TOKEN"
-H "Content-Type: application/json"
-d '{
  "event_type": "order_completed",
  "attribute_key": "order_id",
  "attribute_value": "ORD-123",
  "from_timestamp": "2026-03-01T00:00:00.000Z",
  "to_timestamp": "2026-03-31T23:59:59.999Z"
}'

Step 2 — Apply the mutation

curl -X POST "https://api.usermaven.com/v1/event-mutation?token=API_KEY.SERVER_TOKEN"
-H "Content-Type: application/json"
-d '{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-10T14:30:00.000Z",
  "event_attributes": {
    "price": "149.99"
  },
  "merge_mode": "merge",
  "idempotency_key": "order-price-fix-ORD-123"
}'

---

Best practices

• Keep idempotency_key values descriptive and unique.

• Prefer merge mode unless you intend to fully replace attributes.

• Use an accurate timestamp to improve query performance.

• Avoid using this API for high-frequency real-time updates.

• Store the returned mutation_id for audit and support purposes.

---

Important notes

• This is a server-side API only.

• Never expose the server token in the browser or frontend code.

• Mutations are processed asynchronously and typically propagate within seconds.

• ClickHouse lightweight mutations are optimized for occasional corrections, not streaming updates.

• System events cannot be modified.

---

Additional resources

• Event API — Send new events to Usermaven from your server

• Developer Resources → API Reference