Theoryscope

Setup · the one piece every user gets wrong

Zotero API key.

Theoryscope reads your corpus straight from Zotero. It needs three things: your library ID, your library type, a private API key. This page gets each one, with the gotcha that trips every first-time user.

The only API key Theoryscope needs is a Zotero key. No OpenAI, no Anthropic, no HuggingFace token. The embedding models download once from HuggingFace and then run on your machine. Your Zotero credentials are stored in the browser only and posted directly to your local backend; they never leave your computer.

  1. Sign in to Zotero

    Visit zotero.org and sign in, or create a free account. If you want to analyse a corpus you keep elsewhere, the easiest route is to make a Zotero group library, drag the items into it, and point Theoryscope at the group. The group route is covered in step 6.

  2. Find your library ID

    Go to zotero.org/settings/keys. At the top of the page Zotero prints a line in bold:

    Your userID for use in API calls is 1234567

    Copy that number. That is your library ID for a user (personal) library. It is a plain integer; it is not your username.

    Screenshot pending · the top of zotero.org/settings/keys with the "Your userID" line highlighted.

    Common wrong turnings. The library ID is not your username (dmberry is a username, 1234567 is the library ID). It is not the alphanumeric key in a public URL (zotero.org/dmberry/items/ABCDEFG — that is an item key). For a group library, see step 6, where the ID is the group's number.

  3. Create a private key

    On the same page, click Create new private key.

    Screenshot pending · the Create new private key button.

    Fill in the form:

    • Key Description: anything. Theoryscope is fine.
    • Personal Library — Allow library access: tick this box. If it is unticked the key cannot read anything, and Theoryscope will come back with an empty corpus. This is where almost every setup error begins.
    • Allow notes access: leave unticked. Theoryscope does not use notes.
    • Allow write access: leave unticked. Theoryscope only reads.
    • Default Group Permissions: leave as No access unless you also want to use a group library through the same key (step 6).
    Screenshot pending · the permissions form with "Allow library access" ticked.

    Click Save Key.

  4. Copy the key immediately

    Zotero shows the new key once, as a 24-character alphanumeric string with no prefix:

    P9NiFoyLeZu2bZNvvuQPDWsd

    Unlike OpenAI or Anthropic keys there is no sk- prefix. If you lose the key you cannot retrieve it; delete it and create a new one.

    Screenshot pending · the newly-created key displayed once.

  5. Enter the credentials in Theoryscope

    Open the Corpus Source panel in Theoryscope and choose Zotero. Fill in:

    • Library ID: the number from step 2.
    • Library type: user for a personal library, group for a group library.
    • API key: the string from step 4.
    Screenshot pending · Theoryscope's Corpus Source panel with the three fields filled.

    Click Connect. Theoryscope fetches your collection tree. Pick a collection or a saved search to embed.

  6. Group libraries (the recommended way)

    A group library isolates a corpus from your personal reading. Setup differs on three points.

    1. Create a group at zotero.org/groups/new. A private group is fine.
    2. Drag or import the items you want to analyse into it.
    3. Open the group's page. The URL is zotero.org/groups/1234567/short-name. The number is the group's library ID. In Theoryscope, use this number, not your personal user ID, and set Library type to group.

    Then in the key form at zotero.org/settings/keys, either set Default Group Permissions to Read Only (grants read access to every group), or edit the specific group's row below and tick Read Only there.

    Screenshot pending · group URL with the group ID highlighted.

What goes wrong

Theoryscope connects but returns zero items.

The key does not have library access. Go to zotero.org/settings/keys, click Edit on the key, tick Allow library access and save. For a group library the group itself needs read permission on the key.

"Invalid library" or a 404 response.

The library ID is wrong, or the library type does not match. A personal user ID with library type = group will not resolve, and the reverse will not either. Group IDs come from the group URL, not from the top of the keys page.

I rotated the key and now nothing works.

A rotated key is a new key. Delete the old one in Zotero to avoid confusion, create a fresh one, paste the new value into Theoryscope. The credentials are kept in localStorage for localhost:3000; clearing site data for that origin resets them.

Does my key go on disk?

No. Theoryscope keeps the key in localStorage in your browser, and the backend holds it only in memory for the duration of a request. It is never written to the cache, the logs, or the provenance record.

What about other APIs?

Theoryscope does not call OpenAI, Anthropic, Cohere, Voyage, or any other commercial embedding or generative API. The embedding models (all-MiniLM-L6-v2 by default, with all-mpnet-base-v2 and BAAI/bge-small-en-v1.5 as alternatives for the Embedding Dependence Probe) are open-weight and run locally via sentence-transformers. The Corpus-vs-Model Probe uses small open-weight generative models (SmolLM2, GPT-2) from HuggingFace, also run locally. First use downloads the model (90 MB to 1.5 GB depending on choice); every subsequent run is offline. Zotero is the only external service.

Back to setup Operations guide Troubleshooting