JSON-RPC

You can call into BBT using JSON-RPC on the URL http://localhost:23119/better-bibtex/json-rpc . An example could look like:

curl http://localhost:23119/better-bibtex/json-rpc -X POST -H "Content-Type: application/json" -H "Accept: application/json" --data-binary '{"jsonrpc": "2.0", "method": "collection.scanAUX", "params": ["/My Library/thesis/article1", "/Users/phantom/Downloads/output.aux"] }'

The available methods are:

api.ready()

returns: { betterbibtex: string; zotero: string }

Returns the Zotero and BetterBibTeX version to show the JSON-RPC API is ready.

autoexport.add(collection: string, translator: string, path: string, displayOptions?: { [string]: boolean }, replace: boolean=false)

returns: { id: number; key: string; libraryID: number }

  • collection: The forward-slash separated path to the collection. The first part of the path must be the library name, or empty (//); empty is your personal library. Intermediate collections that do not exist will be created as needed.
  • translator: The name or GUID of a BBT translator
  • path: The absolute path to which the collection will be auto-exported
  • displayOptions: Options which you would be able to select during an interactive export; exportNotes, default false, and useJournalAbbreviation, default false
  • replace: Replace the auto-export if it exists, default false

Add an auto-export for the given collection. The target collection will be created if it does not exist

collection.scanAUX(collection: string, aux: string)

returns: { key: string; libraryID: number }

  • collection: The forward-slash separated path to the collection. The first part of the path must be the library name, or empty (//); empty is your personal library. Intermediate collections that do not exist will be created as needed.
  • aux: The absolute path to the AUX file on disk

Scan an AUX file for citekeys and populate a Zotero collection from them. The target collection will be cleared if it exists.

item.attachments(citekey: string, library?: string | number)

returns: any

  • citekey: The citekey to search for
  • library: The libraryID to search in (optional). Pass * to search across your library and all groups.

List attachments for an item with the given citekey

item.bibliography(citekeys: string[], format?: { contentType: ‘html’ | ’text’; id: string; locale: string; quickCopy: boolean }, library?: string | number)

returns: string

  • citekeys: An array of citekeys
  • format: A specification of how the bibliography should be formatted
  • .quickCopy: Format as specified in the Zotero quick-copy settings
  • .contentType: Output as HTML or text
  • .locale: Locale to use to generate the bibliography
  • .id: CSL style to use

Generate a bibliography for the given citekeys

item.citationkey(item_keys: string[] | ‘selected’)

returns: { [string]: string }

  • item_keys: A list of [libraryID]:[itemKey] strings. If [libraryID] is omitted, assume ‘My Library’

Fetch citationkeys given item keys

item.collections(citekeys: string[], includeParents?: boolean)

returns: { [string]: { key: string; name: string } }

  • citekeys: An array of citekeys
  • includeParents: Include all parent collections back to the library root

Fetch the collections containing a range of citekeys

item.export(citekeys: string[], translator: string, libraryID?: string | number)

returns: string

  • citekeys: Array of citekeys
  • translator: BBT translator name or GUID
  • libraryID: ID of library to select the items from. When omitted, assume ‘My Library’

Generate an export for a list of citekeys

item.notes(citekeys: string[])

returns: { [string]: { note: string }[] }

  • citekeys: An array of citekeys

Fetch the notes for a range of citekeys

item.pandoc_filter(citekeys: string[], asCSL: boolean, libraryID?: string | number | string[], style?: string, locale?: string)

returns: any

  • citekeys: Array of citekeys
  • asCSL: Return the items as CSL
  • libraryID: ID of library to select the items from. When omitted, assume ‘My Library’

Generate an export for a list of citekeys, tailored for the pandoc zotero filter

item.regenerate_key(citekeys: string[], library?: string | number)

returns: { [string]: string | null }

  • citekeys: Array of citekeys whose items should be regenerated.
  • library: The libraryID to search in (optional). Pass * to search across your library and all groups.

Regenerate citekeys from current item metadata. For each input citekey, the underlying item’s key is recomputed using the configured citekeyFormat, and any Citation Key: pin in the Extra field is refreshed to match.

Useful when items were created in two phases — initial record from partial metadata, enrichment landing later — and the key pinned during phase one no longer matches what current metadata would produce.

Returns an old → new mapping per input citekey. The value is null only when the input citekey cannot be resolved to an item. Otherwise the value is the resulting citekey — equal to the input if the recomputed key is unchanged, or the new citekey if it changed.

Read-only library handling is deferred to #3430; until that lands, scope the call to a writeable library via library to avoid touching read-only items.

Counterpart to the read-only item.citationkey lookup. Internally calls the same KeyManager.fill(..., { replace: true }) path the Regenerate BibTeX key right-click menu item invokes.

item.search(terms: string | ([ string ] | [ string, string ] | [ string, string, string | number ] | [ string, string, string | number, boolean ])[], library?: string | number)

returns: any

Search for items in Zotero.

Examples

  • search(’’) or search([]): return every entries
  • search(‘Zotero’): quick search for ‘Zotero’
  • search([[’title’, ‘contains’, ‘Zotero’]]): search for ‘Zotero’ in the Title
  • search([[’library’, ‘is’, ‘My Library’]]): search for entries in ‘My Library’ (this function try to resolve the string ‘My Library’ into is own libraryId number)
  • search([[‘ignore_feeds’]]): custom action for ignoring the feeds
  • search([[‘ignore_feeds’], [‘quicksearch-titleCreatorYear’, ‘contains’, ‘Zotero’]]): quick search for ‘Zotero’ ignoring the Feeds
  • search([[‘creator’, ‘contains’, ‘Johnny’], [’title’, ‘contains’, ‘Zotero’]]): search for entries with Creator ‘Johnny’ AND Title ‘Zotero’
  • search([[‘joinMode’, ‘any’], [‘creator’, ‘contains’, ‘Johnny’], [’title’, ‘contains’, ‘Zotero’]]): search for entries with Creator ‘Johnny’ OR Title ‘Zotero’
  • search([[‘joinMode’, ‘any’], [‘creator’, ‘contains’, ‘Johnny’], [’title’, ‘contains’, ‘Zotero’], [‘creator’, ‘contains’, ‘Smith’, true]]): search for entries with (Creator ‘Johnny’ OR Title ‘Zotero’) AND (Creator ‘Smith’)

user.groups(includeCollections?: boolean)

returns: { collections: any[]; id: number; name: string }[]

  • includeCollections: Wether or not the result should include a list of collection for each library (default is false)

List the libraries (also known as groups) the user has in Zotero

viewer.viewPDF(id: string, page: number)

Open the PDF associated with an entry with a given id. the id can be retrieve with e.g. item.search(“mypdf”) -> result[0].id

mind that the items.export method had a bug where it would double-wrap the JSON-RPC response; the extra layer has been removed in 6.7.143, but if you were expecting the previous result you will have to update your code.