Update an event

Replace an event's schema — tighten the shape its payload must fit, or clear it.

PATCH /v1/events/{id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The event id (evt_…) or the event name.

Body parameters

Parameter	Type	Required	Description
schema	object | null	Yes	The schema to replace the current one with — a flat map of field → type (string, number, boolean, date). Send null to clear the schema and accept any payload.

schema replaces, it does not merge — send the whole map you want, not just the fields that changed. The event's name is its identity and cannot be changed; create a new event instead.

Example

curl

curl -X PATCH "https://api.sendgrail.com/v1/events/user.created" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "schema": {
      "plan": "string",
      "seats": "number",
      "referrer": "string"
    }
  }'

Node.js

const res = await fetch('https://api.sendgrail.com/v1/events/user.created', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    schema: {
      plan: 'string',
      seats: 'number',
      referrer: 'string',
    },
  }),
});

const event = await res.json();

Response

{
  "object": "event",
  "id": "evt_3nBq7Ld2KeR9"
}

Fetch the updated object with Retrieve an event.

Replace, not merge

The schema you send becomes the whole schema. To add one field, send the existing fields plus the new one; send only the new field and the others are gone. This is the same "send the full value" rule that keeps an update predictable — what you PATCH is what the event ends up with.

Send "schema": null to remove the schema entirely. The event then accepts any payload again, exactly as an event created without one does.

Changing the shape doesn't rewrite the past

Updating the schema changes what future sends are validated against. Events already recorded keep the payloads they were sent with — a tightened schema is not applied retroactively, so nothing you've already collected is invalidated or discarded.