Adding support for Tropy URL Scheme

I’d like to have a tropy:// URL scheme so I can easily integrate this with other apps in my system. As an initial option, the URL would be really useful to open a specific photo. An example URL scheme could look like tropy://open?id=<uniqueid>

As an example, in Zotero it would be possible to use the attachment menu. From their docs:


You can also “Attach Link to URI…” to add a link to a web page ( http:// or https:// ) or to another program on your computer (e.g., OneNote onenote:// or Evernote evernote:// ).

I talked a little about how I would use links from other apps in Tropy here:

Having a Tropy URL Scheme would allow links to flow both ways!

Examples of other apps with URL Schemes:

Related posts:

Thanks for this! We’ve actually been laying the foundation for this already; none of this is documented yet, partly because we’re still exploring the possibilities and limitations of an API – and we also lack usage scenarios, so the more details you tell us about workflows you’d like to see supported the better.

Currently you should already be able to use to the tropy:// URL to open Tropy, but not much beyond that. You can also enable a full HTTP API which is more powerful (let’s you query the current project, download images or import new images etc). Our main issue with designing a good API is that in Tropy you can have multiple projects (I think this is different than in all the examples above), so I think we have these choices:

  • Make the full path to your project file an integral part of the URL. This is terrible, because it will produce long URLs and the URLs won’t be stable as they always depend on the current location of the project file – if you move the file, old URLs become stale.
  • Make the project id part of the URL. This is slightly better, because URLs would be shorter than when using full paths, however the biggest issue is that there is no guarantee that Tropy can find the project for a given id: Tropy could remember projects it has already seen, but even then you could move the files and there would be no sensible way for Tropy to find the files.
  • Always use the currently active (or most recent in case Tropy is woken up by the API call) project. This is what we do at the moment until we’ve settled on a better solution.
  • Allow you to register projects for API use explicitly. This solves some of the issues of the first two approaches, but not completely.

In any case, how would you like to use the Tropy URL scheme in other apps: open Tropy to a specific item or photo; import a given file; add a tag to an existing item – anything else?

By the way, reading you post just now it occurred to me that you should already be able to add arbitrary links to notes – so that’s something you could do as a workaround, if you want to link a photo in Tropy to other files or apps.

1 Like

Thanks! Sorry in advance for the long reply! Hope the minor headers make sense.

Re: Troubleshooting tropy:// in Linux

Just a heads up, there might be some additional trickiness to get it to work in Linux (this might be related). At the moment, it doesn’t work for me in Ubuntu 18.04 with v1.8.0.

Some additional things Linux users might need to do:

xdg-mime default tropy.desktop x-scheme-handler/tropy
sudo update-desktop-database

To verify that the tropy:// URL works, the following commands should output tropy.desktop:

xdg-mime query default x-scheme-handler/tropy
xdg-settings get default-url-scheme-handler tropy

In addition, tropy should appear under Default applications in ~/.config/mimeapps.list :

[Default Applications]

Given that I followed all the steps above, I’m not sure what else could be missing.

Re: tropy:// API

I believe you could look into Todoist’s projects for that. I’m pretty new to Tropy, but I believe you could do something similar:


Obsidian has a similar scheme with vaults, which just refer to two different folders in your laptop (but from what I understand would be equivalent to the projects here).

For Tropy, it really depends on how you want to perform the search to the specific item you want to open, but I could see something like

tropy://open?project=<id> # Opens a specific project
tropy://open?project=<id>&item=<itemid> # Opens a specific item in a project
tropy://open?project=<id>&list=<listid> # Opens Tropy on the specified list
tropy://open?project=<id>&list=<listid>&tag=<tag> # Opens a specific list filtered by the given tag(s)

In my opinion, using the project ID with this precondition is a reasonable assumption. If a link containing an id that has not been seen or remembered by Tropy is clicked, you could just default back to opening en empty Tropy instance.

Another alternative would be to support two variations of the URI… one with actions like open where the IDs are used, and a simpler “project” URL that could open the destination path as a Tropy library, but without the option to perform actions, e.g. tropy://tropy-project/path/to/my/photos. This would let the users have an “absolute” link to the vault (so tropy can remember it), and some action-based links once Tropy is aware of the project.

Re: Use cases

For me the main use case right now would be “linking” between applications, so opening to a specific item and/or photo would already serve 90% of what I’d like to do. My main goal is not so much to automate stuff through the URL scheme, but to easily switch between contexts. Adding tags or links (e.g. an obsidian link) to an item from other apps would be a second great step for me!

Keep in mind that I’m only starting with Tropy, and that I’m mostly using it for my genealogy hobby. Other academic users might have other more complex use cases that I haven’t thought about.

Last but not least, could you point me to where I could do this?

And thanks again for the thorough responses and the help!

URL scheme support and a “copy link” option in menus would be a very useful feature for two-way linking.

For linking to and from external note programs, like Evernote, and reference managers like Zotero.

It would also enable easy use of images in markdown.

1 Like