Create Source
create_sourceCreate a source record for a book, register, archive unit, or website that facts come from, with title, author, publication details, and repositories holding it.
Instructions
Create a source: a book, register, archive unit or website that facts come from, with title, author, publication info and the repositories that hold it. Search for the source first: no duplicate check is made, and an existing source is changed with update_source. repositoryHandles takes existing repositories only (create_repository), each with the source's call number there. The arguments split a reference: title names the document, such as a parish register for one year; author is who made it; pubinfo is for a published work; abbrev is a short title for lists; the archive's shelf mark, such as fond, inventory and file, is the call number on repositoryHandles, with the media type (Book, Manuscript, Film, Electronic …) the archive holds it in; the page, frame or entry goes on the citation. Notes and media here describe the whole source; the scan of one entry belongs on its citation. A source alone proves nothing: cite a page or act of it with create_citation, then attach that citation to people and events. Returns the new handle, Gramps ID and title, with next steps. 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 |
|---|---|---|---|
| title | Yes | Title (required). | |
| abbrev | No | Short title for lists (optional). | |
| author | No | Author or issuing body (optional). | |
| pubinfo | No | Publication info: publisher, place, year (optional). | |
| isPrivate | No | Mark the source 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. | |
| 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. 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. 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. | |
| repositoryHandles | No | Repositories that hold the source, each with an optional call number and media type; the repositories must exist (create_repository). 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. |