** Unofficial but really useful Devonthink API and Zapier Integration

DEVONthink Automation
1

I have implemented a working API for DT3 along with Zapier integration. The concepts are mine – with help from a developer to implement it. To me this solves a long-running goal to be able to access my data when away from my main computer (beyond what DT3 Server and Devonthink to Go can do) and to more easily create custom reports and otherwise integrate DT3 with other apps. It lets me keep the unique and unparalleled benefits of a desktop DT3 app and local data storage but also have the benefits of a web app.

I am glad to share this with others - with the request that this be for non-commercial use and that you share back any edits or tweaks or tricks you develop with it.

The link to the Github repository for the API is below. I have also included a link for you to request access to the installed Zapier integration; note that the Zapier integration lets you enter the URL and other credentials for your own API and Zapier does not share that with me so there is no security issue beyond what you have with any other Zapier app. If you would prefer to install the Zapier integration as your own app, just let me know and I will add you to the private Github repository where that is stored.

You can use the API by itself; if you want to use the Zapier integration then you must also have the API installed.

In simplest form, the API itself has a bulit-in web app which lets you upload or download files to/from DT3 via the Internet. But if you set up a MongoDB database (which can be done on the Mongo free tier) then the API will do a 1-way sync of your DT3 metadata to MongoDB; that then opens up the floodgates to infinite possibilities for building your own web app to access your local DT3 database.

Personally I have been using www.retool.com which is a terrific low-code front-end builder for creating a GUI front-end to access MongoDB and other databases. But you have many other options.

The Zapier integration does 3 things - you can Trigger it via a webhook using the sample Applescript provided and a SmartRule (it uses tags to select which Zap you want to trigger); then you can pass data to any Zapier app. So for example you can have a DT3 smart rule which activates Zapier to copy a file to Dropbox/Google Drive, add an item and its X-Devonthink Link and URL to a Google Spreadsheet, or whatever else you can imagine with Zapier integration.

As an Action, the Zapier integration can either upload or download files and/or nested groups to/from DT3.

One helpful benefit of the API is that Shortcuts on iOS can access an API. So there is a sample Shortcut for iOS which takes as its input an X-Devonthink link and then downloads it from DT3 and sends it to the Share Sheet location of your choice.

I have been using this for a few weeks and have found it to be really useful in my work with DT3 but clearly there are infinite ways to integrate it with Zapier, with Retool low-code apps, or with any other web app framework you prefer.

I can answer some questions on getting it working and the big-picture capabilities of the software. @8isnothing developed the software and can provide more specifics if there are bugs or technical / coding issues.

https://zapier.com/developer/public-invite/147248/30469eead92cd75448cbacf3d1cc531c/

A few screenshots to give you a flavor of what it does and looks like:

image
image1287×1177 98.3 KB

image
image1022×680 27.3 KB

image
image833×514 32.8 KB

image
image1352×587 74.9 KB

15 Likes
2

This is fascinating. An API seems to be the most significant feature missing from DT :+1:

Presumably, ngrok needs to be run to expose the API for Zapier to pick up?

3

You can use ngrok but there are other possibilities as well.

The API uses FastAPI. FastAPI includes a Python app which runs as a Terminal app to provide access to the API via a specified port. You could then use port forwarding on your router to send that port to the computer which hosts the API. Or in my case, I have a Synology NAS which has a reverse proxy feature which accomplishes that and makes the https certificate administration a bit easier.

2 Likes
4

I’m not great at networking, but looks like port forwarding’s not particularly secure.

boringproxy looks interesting.

5

That may work

The key for security is to use https - port forwarding is fine as long as you use that

1 Like
6

Why? Or rather: Why would port forwarding be less secure than using a port directly? In my opinion, the important thing is that you use HTTPS and make sure your site can only be accessed by authorized people. To guarantee that, you could use certificates (which are a PITA to generate, administer and install) or probably some kind of two factor authentication.

Alternatively, if your router allows, setup a VPN on the router and connect to that. Than you do not need port forwarding since your DT server and your computer are in the same network already. OTOH, VPN requires authentication, too, which means either certificates or perhaps 2FA. There are also NAS available that allow establishing a VPN, but I’m not sure if one would have to forward a port to them, too.

If the product you mentioned is for you, is not for me to judge. I just noted that macOS support is “untested” (which, given Apples notoriously problematic network implementation, might be a warning sign).

1 Like
7

Like I said, networking’s not one of my strengths. Was reading this :man_shrugging:

Yeah, MacOS support looks sketchy. The whole project’s pretty green.

Reading through this atm.

8

FastAPI also lets you establish a password requirement - so it is not a public API (unless you want it to be).

I would think https plus password protection is sufficient for most uses

And if you happen to have a Synology NAS, the process of setting up the reverse proxy and maintaining https certificates is pretty easy.

9

Depending on the quality of the passwords… I tend to think that passwords are on their way out (and should be), but 2FA or biometrics is still too difficult to set up for individuals.

10

Since you mentioned it - FastAPI is open source so lots of things are possible.

I have not tried this but apparently 2FA is a possibility for those so inclined.

11

Any chance of providing the Apple Script/JAX script files as text rather than binaries please?

12

Did you try to open the files in script editor? That might work.

1 Like
13

Correct - they open fine in Script Editor with the source code editable.

14

Yes but its generally better to have them as text on Public GitHub and binaries on releases.

15

The problem here is that Script Editor does neither save these files as text nor does it open then if they’re text. So while you’re right in general (well, I wouldn’t save a JPEG as text either, not even on GitHub), it’s simply not practical in the given context.

16

iirc Script Editor can. Save as text with .applescript should make them text based.
Then use osacompile in a build script to make them into standalone executables or run as is. I only suggested it because it makes it easier to read on GitHub and you can make small pull requests online and use vscode online workspaces…

I wouldn’t save a JPEG as text either

Yeah but you cannot work with them in any text editor like AppleScript and GitHub displays JPEGs. :wink:

Anyway I think it’s a really good project

17

Very interesting, but can you elaborate use cases?

I’ve been using DTTG and honestly apart from sync issues I haven’t met any major roadblock yet.

Thanks, this is a terrific achievement!

18

My main use case has been to extend access for my small group of employees beyond that which DT3 server offers. I have also use it to facilitate gathering of data from web apps into DT3.

I suspect the API is likely mostly of interest to those who similarly use DT3 in a team or small business setting.

2 Likes
19

This project is indeed really interesting! It’s a contributing factor to me getting on the DT bandwagon (just having a vague idea that it may be possible to interact with DT via an API). Thanks for making this publicly available!

My primary use case is to get mail that’s being scanned and OCRed for me by an external service where my mail is being redirected to POST that mail directly into DT. Before moving to DT I would have the mail automatically added to my Evernote account via webhook. That’s the benefit of a web based service, of course.

I assume it’s a requirement to have a Mac with DT always running and online to get this to work?

PS: Lack of a native and publicly accessible API isn’t just a DT issue, but seems to be an overall iCloud issue as well. Short of having an iOS developer account with an active app, I don’t think there’s an easy way for a regular user to access a REST API to interact with your own iCloud storage. It’s one of the biggest downsides I experience coming from Google Drive and similar ecosystems. If I’m missing something here, I’d love to be corrected!

20

DT can be scripted with AppleScript and JavaScript. With the usual dis/advantages.

Do you mean POST in the sense of HTTP, or do you intend to mean something else? In the first case: There’s no ready-made solution. You could, of course, write your own server listening on whatever port you fancy and react to post messages.

There’s no direct relation between iCloud and DT. You run DT on your desktop (or DTTG on your iOS device), and you can use iCloud to sync different DT/TG instances. To put it differently: There is no iCloud storage associated with DT per se. So there’s of course no REST API for it.

You’re mixing up cloud services and desktop programs.

How else would a REST API be able to operate (if there were one) if not by having a server running and being online all the time?