Update Source
update_sourceModify an existing genealogy source in Gramps Web: change title, author, publication info, abbreviation, attributes, repositories, notes, media or tags, leaving omitted fields unchanged.
Instructions
Change an existing source's title, author, publication info, abbreviation, attributes or links to repositories, notes, media and tags. For a new source use create_source; to remove one, delete_object; a page or act inside the source is a citation, changed with update_citation. repositoryHandles carry each repository's call number, so edit a call number with linkMode replace; 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 source returns a not-found message. 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 |
|---|---|---|---|
| title | No | New title. Omit to leave unchanged. | |
| abbrev | No | New abbreviation. Omit to leave unchanged. | |
| author | No | New author. Omit to leave unchanged. | |
| handle | Yes | The source to change. Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects. | |
| pubinfo | No | New publication info. Omit to leave unchanged. | |
| 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 |
| 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. Each attribute takes only type, value and private. | |
| 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":"…"}. | |
| 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":"…"}. | |
| 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. | |
| repositoryHandles | No | Repositories that hold the source. Omit to keep; applied per linkMode. Repository refs (handles, not Gramps IDs): JSON array of GrampsRepositoryRef objects, or strings "Ref : CallNumber : MediaType". JSON objects accept Gramps snake_case (call_number, media_type) or camelCase (callNumber, mediaType). Parts after Ref are optional: "Ref : CallNumber" and "Ref :: MediaType" are valid. MediaType must be a standard Gramps source media type (Book, Manuscript, Film, Photo, …) or a custom one the tree already uses. Multiple refs: JSON array or one multiline / |-separated string. |