Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zotero/zotero-connectors/llms.txt

Use this file to discover all available pages before exploring further.

When the Zotero desktop application is running, it exposes a local HTTP server at http://127.0.0.1:23119/connector/. Zotero Connectors use this server to save items, transfer snapshots, sync translator lists, and coordinate Google Docs citation integration. All communication is local-only — the server binds exclusively to the loopback interface and is not reachable from other machines.
The connector version of this API is 3, set in connector.js as CONNECTOR_API_VERSION = 3. All requests must include the X-Zotero-Connector-API-Version: 3 header. If the connector and desktop versions are incompatible, the server returns HTTP 412.

​
Base URL

http://127.0.0.1:23119/connector/
The connector URL can be overridden via the connector.url preference (primarily for testing), but in normal operation is always the address above.

​
Required Request Headers

Every request to the connector HTTP server must include the following headers:
​
Content-Type
string
required
application/json for JSON bodies, multipart/form-data for SingleFile snapshot uploads.
​
X-Zotero-Version
string
required
The connector’s own version string (e.g., 5.0.100). The server echoes back the Zotero desktop version in the X-Zotero-Version response header.
​
X-Zotero-Connector-API-Version
string
required
Must be 3. A mismatch returns HTTP 412.

​
Calling from the Connector

Within the extension source, all HTTP calls to Zotero desktop go through Zotero.Connector.callMethod, which handles header injection, JSON serialization, online state tracking, and error classification automatically: 
// String form — method name only
const response = await Zotero.Connector.callMethod("ping", {});

// Object form — with extra headers, query string, or custom timeout
const response = await Zotero.Connector.callMethod(
  {
    method: "saveItems",
    headers: { "X-Custom": "value" },
    timeout: 30000
  },
  data
);
callMethod issues a GET request when data is null or undefined, and a POST request otherwise. It automatically parses JSON responses when the Content-Type response header includes application/json.

​
Endpoints

​
POST /connector/ping

Checks whether Zotero is running and retrieves current preferences. The connector calls this on startup and periodically to detect when Zotero comes online or goes offline. The request body is always a JSON object (even if empty), so callMethod always issues a POST. Request body (always sent; activeURL is included only when reportActiveURL pref is true): 
{
  "activeURL": "https://www.example.com/article"
}
Response 200 OK: 
{
  "prefs": {
    "downloadAssociatedFiles": true,
    "reportActiveURL": true,
    "automaticSnapshots": true,
    "googleDocsAddAnnotationEnabled": false,
    "googleDocsCitationExplorerEnabled": false,
    "supportsAttachmentUpload": true,
    "supportsTagsAutocomplete": false,
    "canUserAddNote": true,
    "translatorsHash": "abc123...",
    "sortedTranslatorHash": "def456..."
  }
}
​
prefs.downloadAssociatedFiles
boolean
Whether Zotero is configured to download associated files (PDFs, etc.) when saving items.
​
prefs.reportActiveURL
boolean
Whether Zotero wants the connector to report the currently active browser tab URL on each ping.
​
prefs.automaticSnapshots
boolean
Whether Zotero automatically saves a snapshot when saving a web page item.
​
prefs.googleDocsAddAnnotationEnabled
boolean
Whether the Google Docs “Add Annotation” feature is enabled in Zotero.
​
prefs.googleDocsCitationExplorerEnabled
boolean
Whether the Google Docs Citation Explorer feature is enabled in Zotero.
​
prefs.supportsAttachmentUpload
boolean
Whether the running Zotero version supports the attachment upload workflow.
​
prefs.supportsTagsAutocomplete
boolean
Whether the running Zotero version supports tag autocomplete in the save dialog.
​
prefs.canUserAddNote
boolean
Whether the current Zotero user has permission to add notes.
​
prefs.translatorsHash
string
MD5/SHA hash of Zotero’s current translator set. The connector compares this to its own hash; a mismatch triggers Translators.updateFromRemote().
​
prefs.sortedTranslatorHash
string
Sorted variant of translatorsHash, used when the running Zotero version supports sorted hashing.
The X-Zotero-Version response header contains the Zotero desktop application version string, which the connector stores as Zotero.Connector.clientVersion.

​
POST /connector/saveItems

Saves one or more translated bibliographic items to the Zotero library. This is the primary save endpoint invoked after a translator extracts metadata from a webpage. Request body: 
{
  "items": [
    {
      "itemType": "journalArticle",
      "title": "Example Article",
      "creators": [{ "firstName": "Jane", "lastName": "Doe", "creatorType": "author" }],
      "DOI": "10.1234/example",
      "url": "https://example.com/article"
    }
  ],
  "uri": "https://example.com/article",
  "detailedCookies": "sessionid=abc; Domain=example.com; Path=/; secure",
  "cookie": ""
}
​
items
array
required
Array of Zotero item objects in the internal item format. Each object must include at minimum an itemType field.
​
uri
string
required
The URL of the page from which items were saved. Used by Zotero to set up the cookie sandbox for attachment downloads.
​
detailedCookies
string
Newline-separated cookie strings in the format name=value;Domain=...;Path=.... Provided by callMethodWithCookies when the connector has cookie access. If present, the cookie field is omitted.
​
cookie
string
Simple cookie string, used when detailed cookies are not available.
Response 201 Created on success (body varies by Zotero version).

​
POST /connector/saveSnapshot

Saves a snapshot of a webpage to Zotero. Used when the user manually triggers a snapshot save or when automaticSnapshots is enabled. Request body: 
{
  "url": "https://example.com/page",
  "html": "<!DOCTYPE html><html>...</html>",
  "cookie": "sessionid=abc"
}
​
url
string
required
The URL of the page being snapshotted.
​
html
string
required
The full HTML content of the page to save as a snapshot attachment.
​
cookie
string
Cookie string for the page, used when Zotero fetches related resources.
Response 201 Created on success.

​
POST /connector/saveSingleFile

Saves a full-page archive captured by the SingleFile library. This endpoint accepts multipart/form-data because the snapshot content is binary. It is invoked after SingleFile has compressed the page into a self-contained HTML file. Request: Content-Type: multipart/form-data Form fields include the serialized item data and one or more binary-* fields containing binary page content as Blob objects. In the background, Uint8Array data is converted to Blob instances before being appended to FormData.
On Chromium (both MV2 and MV3), SingleFile snapshot content may be chunked via Zotero.Messaging.sendAsChunks before the message is routed to the background. The background reassembles chunks with Zotero.Messaging.getChunkedPayload before forwarding to Zotero desktop. See the Connector.saveSingleFile message entry for details.
Response 201 Created on success.

​
POST /connector/getTranslatorCode

Returns the JavaScript source code for a specific translator. The translator ID is sent as a JSON body (not a query string), so callMethod issues a POST request. Request body: 
{
  "translatorID": "951c027d-74ac-47d4-a107-9c3069ab7b48"
}
​
translatorID
string
required
The UUID of the translator whose code should be returned (e.g., 951c027d-74ac-47d4-a107-9c3069ab7b48).
Response 200 OK: The raw JavaScript source of the translator as text/plain or application/javascript.

​
POST /connector/document/execCommand

Google Docs integration: instructs Zotero to execute a citation-related command within the document context. This is the primary command channel used by the Google Docs content script to invoke Zotero citation operations. Request body: 
{
  "command": "addEditCitation",
  "docId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
}
​
command
string
required
The citation command to execute. Common values include addEditCitation, addEditBibliography, refresh, complete.
​
docId
string
required
The Google Docs document ID from the document URL.
Response: A JSON object describing the next command Zotero needs the connector to execute (used in the back-and-forth integration protocol).

​
POST /connector/document/respond

Sends a response back to Zotero during an ongoing Google Docs integration operation. Zotero’s document integration is a synchronous request-response protocol: Zotero issues a command, the connector responds, and the cycle continues until Zotero sends complete. Request body: The response payload varies by the preceding command. It can be a JSON string, an empty string "", or an error object: 
{
  "error": "Tab Not Available Error",
  "message": "The tab was closed",
  "stack": "Error: ..."
}
Response: The next command in the integration protocol, or complete to signal the operation is finished.
If the Google Docs tab is closed or discarded while an integration operation is in progress, the connector automatically sends a Tab Not Available Error response and continues draining the command queue until Zotero signals complete, allowing Zotero to clean up gracefully.

​
Error Handling

Status 0 — Zotero Offline

The XHR returned status 0, meaning Zotero is not running or the connection was refused. The connector sets Zotero.Connector.isOnline = false and throws a CommunicationError.

Status 412 — API Version Mismatch

The connector and Zotero desktop versions are incompatible. Zotero.Connector_Browser.onIncompatibleStandaloneVersion is invoked with both version strings to display a user-facing prompt.

Status 4xx/5xx — Method Error

A method-specific failure. The response body (if JSON) is available as error.value. The method name and status are logged.

Timeout

Default timeout is 15,000 ms. Override per-call with options.timeout. Set timeout: false for operations that may take an indefinite time (e.g., document/respond during integration).

​
CommunicationError

All connector errors are instances of Zotero.Connector.CommunicationError: 
Zotero.Connector.CommunicationError = function(message, status = 0, value = '') {
  this.name = 'Connector Communication Error';
  this.message = message;
  this.status = status;   // HTTP status code, or 0 if offline
  this.value = value;     // parsed response body (if any)
};
Zotero.Connector.CommunicationError.prototype = new Error;
Example error handling: 
try {
  await Zotero.Connector.callMethod("saveItems", data);
} catch (e) {
  if (e instanceof Zotero.Connector.CommunicationError) {
    if (e.status === 0) {
      // Zotero is offline
    } else if (e.status === 412) {
      // Version mismatch — user needs to update Zotero or the connector
    } else {
      // Other HTTP error
      console.error(e.status, e.value);
    }
  }
}

​
Further Reading

Connector HTTP Server

Official Zotero documentation for the connector HTTP server protocol, including details on item formats and the full server-side implementation.

Zotero Web API v3

Reference for the Zotero cloud API used by Zotero.API methods (createItem, uploadAttachment) when Zotero desktop is not available.

Build docs developers (and LLMs) love

Get started for freeTalk to us