Create Citation
create_citationCreate a citation for a specific page, act, or entry in an existing source, adding date, confidence, notes, and media, then attach it to the people, families, events, or places it names.
Instructions
Create a citation: one specific spot in an existing source, such as a page, act or entry number, with its date, confidence, notes and media. Returns the new handle, Gramps ID and page, with next steps. The source must already exist (search, or create_source). A transcript of the entry goes in a note (create_note, type Transcript) passed in noteHandles; the scan goes in mediaHandles, or later through create_media attachTo, which can mark the entry's region on the page. The citation supports nothing until it is attached: add it to each person, family, event or place it names (citationHandles, linkMode add, on their update tool). Does not check for duplicates; change an existing citation with update_citation. 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 | Date of the cited entry, 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. | |
| page | No | Where in the source: page, act or entry number (optional). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text. | |
| isPrivate | No | Mark the citation 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. Each attribute takes only type, value and private. | |
| confidence | No | How reliable the cited record is: Very Low, Low, Normal (default), High or Very High. | Normal |
| 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":"…"}. | |
| noteHandles | No | Notes, e.g. a transcript of the entry (create_note with type Transcript). Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| mediaHandles | No | Media such as the scan of the page. 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. | |
| sourceHandle | Yes | The source being cited (required). Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. |