Editor’s Note: Reverse-Engineering the Matter API and My ‘Save to Matter’ Shortcut is part of the MacStories Starter Pack, a collection of ready-to-use shortcuts, apps, workflows, and more that we’ve created to help you get the most out of your Mac, iPhone, and iPad.
For the past few months, I’ve been enjoying and keeping an eye on the development of Matter, a new read-later service that aims to combine a powerful text parser with elegant design, social discovery features, annotations, and the ability to listen to articles as audio. I’m not one to typically care about the latest VC-backed startup that promises to revolutionize reading articles with social features, but Matter struck me for a few reasons: the app’s reader mode is gorgeous; the ability to annotate articles with highlights is great; and, more importantly, it has the best, most human-sounding text-to-audio conversion engine I’ve ever tested.
Something else happened a few months ago: Matter introduced an official plugin to sync your article highlights as Markdown notes to Obsidian. Integration with PKM-style apps is a hot trend right now in the modern crop of read-later services (John covered this very topic here), so I wasn’t shocked to see that Matter joined Readwise in supporting Obsidian with a plugin. Something about it piqued my interest though:
If Matter didn’t have a public API, how could the Obsidian plugin even sync to the Matter service?
Obviously, there had to be an API involved behind the scenes, which Matter hadn’t announced yet, but which I could potentially reverse-engineer and integrate with Shortcuts. And that’s exactly what I’ve been doing for the past month.
My experiments with the still-unannounced Matter API have developed on three separate fronts, and I’m going to share the results in three different places:
- Today on MacStories, I’m going to share a one-click shortcut called Save to Matter that lets you save any article to your Matter queue directly from the share sheet or anywhere else on iOS, iPadOS, or macOS without having to use the Matter extension;
- Tomorrow on MacStories Weekly for Club MacStories members, I will share MatterBot, an advanced Matter shortcut that lets you take complete control over your Matter queue with support for exporting annotations as Markdown or even downloading articles as MP3 files;
- Next week for Club MacStories+ and Premier members only, I will share MatterPod, another advanced shortcut that lets you turn your Matter queue into a Matter podcast feed hosted on your own web server.
Before we dive in, I also want to confirm that I privately reached out to the folks at Matter weeks ago about my experiments, and they were cool with me writing about my findings and sharing shortcuts I’ve built for the Matter API.
With that being said, let’s take a look at how you can get started with the Matter API and the Save to Matter shortcut.
Getting Your Matter API Token
The most important detail you have to understand about the Matter API is that it’s only officially supported in a limited number of Matter-compatible tools for now. For instance, when you install the Matter Safari extension on a Mac, that extension authenticates you using the Matter API. Or, as I mentioned above, when you install the Obsidian plugin for Matter, that plugin communicates with the Matter API behind the scenes.
For Shortcuts to work with the Matter API, we need an authorization token that is specific to your Matter account. However, there isn’t a page on the Matter website where you can go, log in, and get a token yourself – as is often the case for web services that have a REST API. Which is where Obsidian comes in.
For my Matter shortcuts to work, you will need to have Obsidian and the free Matter plugin installed on your devices. You can find the Matter plugin in the Community Plugins section of Obsidian; once installed and enabled, open the plugin’s settings page in the Obsidian app and you’ll be prompted to authorize the plugin with a QR code. To perform this one-time authorization, open the Matter app on your iPhone or iPad, go to Profile ⇾ Settings ⇾ Connected Accounts ⇾ Obsidian and scan the QR code. The Matter app will authorize the Obsidian plugin, which will start syncing article highlights to a folder in your Obsidian vault.
At this point, while it may not look like it, we have everything we need to start communicating with the Matter API from Shortcuts.
My experiments started by assuming that the Obsidian plugin had to store an authorization token somewhere in the filesystem. My assumption was correct. Located inside the .obsidian/plugins/matter/ folder (all Obsidian vaults store plugins in that hidden directory), you’ll find a data.json file. After the Obsidian plugin has been authorized via the Matter app, the JSON file gets updated with an accessToken key. The value of the key is your private Matter token that can be used to make authenticated calls to the Matter API. But where can we find the proper endpoints to make requests to the Matter API if it hasn’t been announced yet and there’s no documentation for it?
Poking Around the Matter API
Once again, I went back to the source code of the Matter plugin for Obsidian, which is available in a GitHub repository here. In the source code for the API, I found this URL:
https://api.getmatter.app/api/v11/library_items/highlights_feed
At that point, I felt like I was getting closer to a solution. I assumed that https://api.getmatter.app/api/v11/ was the base URL for the API, with /library_items/highlights_feed/ being the endpoint to retrieve your article highlights with a GET request. This is where I had to get creative and spend some time trying different ideas until I found what I was looking for. Most modern REST APIs are similar and share a consistent endpoint structure. You make GET requests to retrieve data, and you make POST requests to upload data to an API. I wanted to start by figuring out how I could save a new URL to my Matter account using the API, so I began testing out various potential endpoints with POST requests in Shortcuts. Eventually, I discovered this API endpoint:
https://api.getmatter.app/api/v11/save/
I had my authorization token and the correct API endpoint; all that was missing was the parameter to actually send a URL for an article I wanted to save to my Matter queue. I assumed that the parameter Matter wanted was a url one, so I tested it out in Shortcuts and, sure enough, it worked.
With all the pieces in place, it was time to build a shortcut.
Save to Matter
The first Matter shortcut I’ve built is called Save to Matter, and it lets you save any link from Safari or other apps directly to Matter using Shortcuts instead of the Matter extension. This also means you can run this shortcut for multiple URLs passed as input (from the share sheet, other shortcuts, Obsidian Shortcut Launcher, or other input sources), and they will all be saved to Matter in one go – making this a nice solution to batch export multiple URLs to Matter directly via the API.
For my Matter shortcuts to work, you’ll need to have Obsidian and the Matter plugin installed. Once again, there is no other way to generate a private Matter API token right now, so Shortcuts always needs to fetch the token generated for Obsidian from the JSON file stored in the plugin sub-directory inside your Obsidian vault. The fact that the token was created for Obsidian doesn’t, well, matter; the token will authenticate any request to the Matter API and it’s specific to your Matter account, so don’t share it with anyone.
The nice thing about this approach is that Shortcuts can fetch the token automatically for you with no manual interaction necessary. Upon installing the shortcut, you’ll be asked to pick the folder of your Obsidian vault in Files/Finder, and that’s it. Using the new Files actions in iOS 15/Monterey, which I have explained in depth here, Shortcuts can retrieve the token stored in the plugin folder for you so you don’t have to do any copy and paste to grab the token yourself. For this to work, however, you will need to have iOS/iPadOS 15.3 or macOS Monterey 12.2 installed.
In iOS/iPadOS 15.3, Shortcuts can read files from hidden folders, like the one where Obsidian stores plugin data.
The rest of the shortcut is just a Repeat with Each loop that takes URLs passed as input to Shortcuts and saves them all to the Matter API. Run the shortcut in Safari’s share sheet for an article you want to save on an iPhone or iPad, and a couple of seconds later, you’ll see an alert saying that the URL was successfully saved to Matter. Open the Matter app, and the article will be there in the queue, waiting for you to read or listen to. It’s simple, secure, fast, and, best of all, doesn’t require interacting with the Matter extension in the share sheet.
As I mentioned at the outset, this is only one of the shortcuts I’ve built for the Matter API based on this technique. In tomorrow’s issue of MacStories Weekly for Club MacStories members and in a separate story for Plus and Premier members next week, I’ll share MatterBot and MatterPod, two advanced shortcuts that display your entire Matter article queue and let you create a private podcast feed for your Matter account, respectively.
Stay tuned for the additional Matter shortcuts I’ll share on Club MacStories. In the meantime, you can download Save to Matter below or in the MacStories Shortcuts Archive and get started with the Matter plugin for Obsidian here.
Save to Matter
Save URLs directly to your Matter queue using the Matter API. The shortcut supports saving multiple URLs at once. A Matter API authorization token is required for this shortcut to work.
You can follow the MacStories Starter Pack on our hub, or subscribe to the dedicated Starter Pack RSS feed.
