Update Event
update_eventModify an existing event's type, date, place, description, attributes, or links to citations, notes, media, and tags. Changes are visible to everyone sharing the event.
Instructions
Change an existing event's type, date, place, description, attributes or links to citations, notes, media and tags; everyone who shares the event sees the change. Who takes part is not set here: add or remove the event in a person's or family's eventRefs with update_person or update_family, which also hold each participant's role. For a new event use create_event; to remove one, delete_object. An empty string clears date, and attributes replace the whole list whatever linkMode says. Pass only what changes; omitted arguments stay as they are. Link lists (…Handles, …Refs) follow linkMode: replace (default) sets the whole list, add appends, remove drops the given handles; in replace mode [] REMOVES every link of that kind, though the linked records themselves stay in the tree. Returns the handle and Gramps ID; a missing event returns a not-found message, and an unknown type or unreadable date is rejected before anything is saved. Writes run one at a time and need a Gramps Web account allowed to edit the tree; a locked or rate-limited write fails with the delay to wait before retrying it. Formats of every argument: get_reference(topic: "input-guide").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | New date. Omit to keep the current date; pass an empty string to remove it. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected. | |
| handle | Yes | The event to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| linkMode | No | How to apply all supplied link lists: replace (default) replaces each full list, and a link it keeps keeps its stored privacy, citations, notes and crop unless the call sends new values; add appends missing handles and preserves existing link metadata; remove removes all links matching supplied handles (reference metadata is ignored). Omitted lists stay unchanged; empty lists clear only in replace mode. Does not affect attributes, names, addresses or URLs. Use separate calls to add and remove, or replace to edit existing link metadata. | replace |
| eventType | No | New event type. Omit to leave unchanged. Must be a standard Gramps type or a custom one the tree already uses; anything else is rejected with suggestions. List: get_reference(topic: "types"). | |
| isPrivate | No | true makes the record private, false public. Omit to leave unchanged. | |
| attributes | No | Attributes. Omit to keep; a value replaces the whole list and [] clears it, whatever linkMode says. Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. | |
| tagHandles | No | Tags. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| description | No | New description. Omit to leave unchanged. | |
| noteHandles | No | Notes. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| placeHandle | No | New place. Omit to leave unchanged. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| mediaHandles | No | Media. Omit to keep; applied per linkMode. Media handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string. To show only part of an image, such as one record on a page scan, give an object {"ref":"…","region":[left, top, right, bottom]} in place of the handle. A region is [left, top, right, bottom]: its edges in percent of the image width and height, 0 to 100, measured from the top-left corner; [10, 20, 60, 45] runs from 10% to 60% across and from 20% to 45% down. [0, 0, 100, 100] shows the whole image again; read_media with the same region shows what it covers. A plain handle keeps the region its link has. In add mode a media already shown keeps its link and takes the region given; to show two regions of one image, list it twice, each with its region. | |
| citationHandles | No | Citations. Omit to keep; applied per linkMode. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |