Create Event
create_eventCreate a standalone event such as Birth, Marriage, or Residence with date, place, citations, notes, and media, then attach it to people or families using update_person or update_family.
Instructions
Create a standalone event (Birth, Marriage, Residence, Census, …) with its date, place, description, citations, notes and media. Returns the new handle, Gramps ID and type, with next steps. The event is linked to nobody yet: attach it with update_person or update_family (eventRefs, linkMode add), which keeps their other events; several people can share one event, each with their own role. The role is stored on their eventRefs (HANDLE::Role, default Primary on a person and Family on a family), not on the event, and a Birth or Death becomes a person's birth or death only in the Primary role. The place must exist: find it with search or create it with create_place. A dated range such as 1890-1900 means the event happened once, some time within it; for something that lasted, such as a Residence or Occupation, write from 1890 to 1900. A register that gives both birth and baptism makes two events, Birth and Baptism. Citations, notes, media, tags and attributes passed here belong to the event and show for everyone who shares it; one participant's own details, such as their Age, go on that person's eventRefs entry (its attribute_list). Change an existing event with update_event. An unknown type or unreadable date is rejected before anything is saved. For several new records that link to each other, such as the people, events, source and citation of one register entry, use create_records instead: one transaction, all created or none. 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 | When it happened, optional. 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. | |
| eventType | Yes | Event type, e.g. Birth, Baptism, Death, Burial, Marriage, Residence, Occupation. 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 | Mark the event private (default false). | |
| attributes | No | 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. 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 | Short description, optional. | |
| noteHandles | No | Notes. 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 | Where it happened, optional; the place must exist (create_place). Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| mediaHandles | No | Media. 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. | |
| citationHandles | No | Citations supporting the event. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |