Update Source
update_sourceChange an existing source: title, author, publication info, abbreviation, repositories, notes, media, tags, attributes or the private flag. Pass only what changes; omitted arguments stay as they are.
Instructions
Change an existing source: title, author, publication info, abbreviation, repositories, notes, media, tags, attributes or the private flag. 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. Returns the handle and Gramps ID; a missing source returns a not-found message. 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. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| 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. |