THIS WEEK'S SPONSOR:

Koskmik

For All Mindkind


MacStories Starter Pack: Reverse-Engineering the Matter API and My ‘Save to Matter’ Shortcut

My Save to Matter shortcut.

My Save to Matter shortcut.

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.

Once the Matter plugin for Obsidian is set up, it'll start syncing highlights to your vault.

Once the Matter plugin for Obsidian is set up, it’ll start syncing highlights to your 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.

The API call to save URLs to Matter.

The API call to save URLs to Matter.

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.

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.

Saving articles to Matter.

Saving articles to Matter.

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.

MatterBot (left) and MatterPod, coming tomorrow and next week to Club MacStories.

MatterBot (left) and MatterPod, coming tomorrow and next week to Club MacStories.

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.

Get the shortcut here.

You can follow the MacStories Starter Pack on our hub, or subscribe to the dedicated Starter Pack RSS feed.

Shine bright with Daylite: Supercharge your business with the best CRM app made for Mac.

Unlock More with Club MacStories

Founded in 2015, Club MacStories has delivered exclusive content every week for over six years.

In that time, members have enjoyed nearly 400 weekly and monthly newsletters packed with more of your favorite MacStories writing as well as Club-only podcasts, eBooks, discounts on apps, icons, and services. Join today, and you’ll get everything new that we publish every week, plus access to our entire archive of back issues and downloadable perks.

The Club expanded in 2021 with Club MacStories+ and Club Premier. Club MacStories+ members enjoy even more exclusive stories, a vibrant Discord community, a rotating roster of app discounts, and more. And, with Club Premier, you get everything we offer at every Club level plus an extended, ad-free version of our podcast AppStories that is delivered early each week in high-bitrate audio.

Choose the Club plan that’s right for you:

  • Club MacStories: Weekly and monthly newsletters via email and the web that are brimming with app collections, tips, automation workflows, longform writing, a Club-only podcast, periodic giveaways, and more;
  • Club MacStories+: Everything that Club MacStories offers, plus exclusive content like Federico’s Automation Academy and John’s Macintosh Desktop Experience, a powerful web app for searching and exploring over 6 years of content and creating custom RSS feeds of Club content, an active Discord community, and a rotating collection of discounts, and more;
  • Club Premier: Everything in from our other plans and AppStories+, an extended version of our flagship podcast that’s delivered early, ad-free, and in high-bitrate audio.