On Our API

by Charles Broskoski

We recently made a major version update to our API (v3), the first major update in over ten years. 

A few weeks ago, we celebrated this with an API / Developer meetup at Index Space in New York. The idea was to showcase the new structure and discuss some brand new functionality (more on this in a bit). We also wanted to give space for people to demo their own projects using Are.na’s API, which we’ve noticed a significant uptick in recently.

Before the meetup, Damon and I talked for a while to figure out what we were going to say in our presentation. I suggested that to prepare we could just talk about the API in general and record it. I wanted to see if we could unearth anything useful by examining our thoughts on why it’s important to have an API and what is particularly special about ours.

One realization we came to is that we’ve always considered our API to be an elemental aspect of Are.na, in part because it’s a concrete way to articulate an important philosophical aspect of Are.na: that it should preserve space for latent potentiality. 

In other words, it’s important for Are.na to have an API because it’s important for Are.na to be open. We don’t want to be prescriptive about what Are.na should be used for, so over time we’ve tried to make all of the core operations as smooth, ergonomic, and performant as possible. All the work we do on Are.na itself has to do with improving, refining, and (in rare cases) adding on to this core set of functionality, in service of maintaining the beautiful dynamic on Are.na that we’ve all been privileged to participate in.

As a result of this, the people who use Are.na also have more of a hand in defining it and our API is a surface that allows the people who use Are.na to actively re-interpret it. Now (like our web client and iOS app), it’s finally getting the update it deserves.

Some background

For anyone unfamiliar with the term API, it’s essentially just a set of rules for one piece of software to talk to another. For example, instead of interacting with Are.na through a website or a mobile app, one could make their own little program that uses Are.na data in a different way. You could use the Are.na API to display a channel as a screensaver, or use it to make a portfolio website, or use it to show blocks in a chat-like interface. The possibilities are literally endless. 

When we started Are.na nearly 15 years ago, it was pretty standard for popular services to have an API (just like nearly every service at the time had an RSS feed). There was a lot of talk about the idea that web services could be interoperable, that the web consisted of building blocks that people could arrange in whatever ways they saw fit. That software, ideally, should be open source. That people should (lol) learn how to code. This was the ethos of the time that we grew up in, as engineers.

At the time, we took inspiration from some of these ideas and focused on the notion that what we were building was, at its core, just a system of primitives: Blocks are content, Channels are containers, and Connections are what link the two together. 

In the beginning, Are.na was a single monolithic Rails application — meaning the data, the business logic for storing the data, and the logic for the display of the data all lived in the same place. This was also standard for the time. Eventually, we realized that we could separate the front-end from the back-end and gain a new surface in the process: an API that other people besides us could use.

It was only after building it that we realized what an interesting dynamic we were uncovering. Because blocks and channels map very cleanly to something like “content” and “containers,” there was a whole set of things you could use our API for that were much more useful than a typical social network’s API. It was something like a social version of a CMS. 

We were already used to the idea that content on Are.na has a life of its own. At any given point, a block you added could be connected to a different channel, giving it additional context, and allowing it to be seen in a different way. Through our API, content on Are.na is given the additional potential to live outside the platform itself. Damon called this “publishing as side effect.”

Projects Using Our API

If you ever used our old API, you’ll have noticed that it had “v2” in the URL. Damon and I recently (re)discovered that our original v1 API was in production for less than a year, and probably was only used by a single external client. Nevertheless, in the early days of the API we experimented with it in projects with friends, such as the websites for Cambridge Book with Carson and Sandeep Salter; Paperweight with Eric Hu, Jesse Hlebo, and Justin Sloane; JTT gallery; and Cleopatra’s.

We went on to use our own API to build an early prediction market with Troy Conrad Thierren for the Guggenheim, a documentation engine for a NADA pool party, a music player called mac.are.na, a time-based archive for artist Rita McBride and Dia museum, and all of our community portions of the Are.na Annual (a garden, a book of signatures, madlibs, etc.).

Meanwhile, people on Are.na built even more amazing things with the API. There are too many to enumerate but here are just a few: Sam Hart’s World Maps, Elliott Cost’s Scoby, 56.digital’s Figma plugin, Spencer Cheng’s Gather, Max Bittker’s River, Michael Guidetti’s Are.na Multiplexer, James Hicks’ m00d, and Yihui’s first unofficial iOS app. 

Our “Powered by Are.na” channel has more than 100 entries and still doesn’t come close to covering all the projects that people have made over the years.

Why now?

We’ve long known that Are.na’s old API needed updating. As we worked on the performance of our backend over the last few years, the v2 API was regularly the slowest of all of our responses, which slowed down all other response times across the board. Apart from that, the old API was half-undocumented and inconsistent in terms of response structures. To put it plainly, it was embarrassing to us, as a core surface of the product. But since our small size requires that we prioritize (more or less) one large problem at a time, it went on the backburner.

Meanwhile, most of the big services (especially social ones, like Instagram, Twitter, etc.) have moved away from their APIs being freely accessible and usable. This is not that surprising, as these services have business models that rely on the fact that the data produced within these services is tightly controlled. For most of them, an open API is a multi-dimensional cost, an appendage that almost directly undercuts the way they typically make money.

For us, because you are our direct customer, the incentives run in the opposite direction. The ethos surrounding having an open and accessible API has remained, mostly because that ethos also underlies the philosophy of Are.na itself — the idea that Are.na should be open-ended, that being open-ended preserves the latent possibility that allows people on Are.na to determine the shape and direction of a particular exploration, and that having a robust API ultimately serves its open-endedness. Our business model encourages us to have an API because Are.na is more valuable to people the more useful it is.

But what does “open and accessible” actually mean in 2026? As we’ve come to learn, when a service is “free and open” there’s usually some other cost involved. For us, it’s important that when we make these kinds of decisions, we consider the long-term sustainability of them.

What finally pushed us over the edge to cut a new version of the API was seeing a steady increase in the old version’s usage. Not only were we seeing the number of scrapers increase, we were also witnessing a growing number of API projects, due to LLM-assisted coding (the “learn to code” people got their wish, but in a way they might not have expected). In any case, both of these forces put a strain on our infrastructure and the question became: what is the best way to keep an open API with this increase in infrastructural pressure?

The solution we landed on is tiered rate limiting, based on your membership plan. Similar to everywhere else on Are.na: a free account is for trying it out, the Premium tier is for everyday usage, and the Supporter tier is for power users. The free tier is meant to be generous enough to build a real-world, working project on, and most of the projects that people have made over the years are well within those limits. The paid tiers ask the people using the API most heavily to support the infrastructure that keeps it open for everyone else.

The aforementioned platforms were incentivized to close their APIs by their own business models. For us, since the API felt fundamental to Are.na, the question was never whether or not to keep it but rather how we could make it sustainable.

The details

OpenAPI spec

The foundation of v3 is that it’s built with an OpenAPI spec. This means that most of the time when we’re adding an endpoint, we’re writing to the spec first, describing the shape of it, and then implementing the logic and testing against the spec. This also means that our documentation is always up to date, and, maybe more interesting for the current development paradigm, you can consume the entire API specification from a single endpoint. So if, for example, you’re using something like Claude Code, you can just point it directly to https://api.are.na/v3/openapi and it will understand all the possibilities of what it can do.

All new documentation, in situ

Our documentation is now directly inside of Are.na at https://www.are.na/developers/explore, which makes it possible for you to explore an API response for a channel, block, group, or person, directly. 

If you’re ever curious what an object looks like in the API, just click the “More” dropdown on it, then “API” and the documentation will populate with that object as the parameter.

Typescript SDK and Examples

The API also comes with a brand new Typescript SDK that makes building advanced applications with Are.na much more seamless and straightforward. Alongside this, we’ve published a repo of example applications, which includes a nearly feature-complete Are.na client, a portfolio website, and a swimlanes style application which turns Are.na channels into stateful to-do lists.

MCP

We've also published an MCP server, which is a way of connecting Are.na to LLM clients (like Claude or ChatGPT). Once it’s connected, you can ask the assistant to add things to a channel, pull blocks out of one, or look up what’s already there, and it will know how. If you’re doing research in a chat and you come across something worth keeping, you can just ask for it to be saved to the relevant channel without leaving what you were doing.

CLI

Alongside the SDK, we’ve also released a command-line interface. It’s a thin tool sitting on top of the same OpenAPI spec, useful for poking at endpoints directly, scripting small jobs, or piping results into whatever else you're doing in a terminal. 

It's also a natural fit for the agentic-coding workflows that are becoming more common, where the person writing the code is partly directing an assistant. 

Lastly, mostly just for fun, it has an interactive mode, which will even display image blocks as ANSI.

Search

While not technically a new capability of the API, it’s worth mentioning that the v3 API uses our new search infrastructure, which allows you to use all the same filters and sorts that our advanced search uses. You can use it to search images, search through channels, profiles, etc. Anything you can use Are.na to search for, you can do with the API.

A quick note here on limits: our v2 search endpoints were by far the most abused by scrapers.  Their v3 counterparts are authenticated and available for premium tiers only. 

Custom metadata

Saving what we're most excited about for last: a new ability to attach custom key/value metadata to blocks, channels, and connections. Until now, if you wanted to attach structured information to a block — color, price, size, rating, status, anything taxonomical — it had to live as raw text in the description, which required hacky implementations that could break easily. Custom metadata is the surface where that kind of information becomes officially structured.

A good way to see what potential this opens up is by viewing our Swimlanes demo, which is a fully working task management app built entirely out of blocks, channels, and connections. The state of each task — priority, epic, target date, etc — lives as metadata on the connection between the block and the channel it's in. It's a demo, not a product we're shipping, but the point of building it was to show that Are.na's primitives, with this addition, are now general enough to assemble into a much wider range of applications than was possible before.

What’s next

What’s next will be largely determined by you, but we’re really excited about what we’ve been seeing so far. 

To name just a few: starstar.website (Elliott Cost’s full featured site builder), Are.na Hypernormalization (Kim Plowright’s Adam Curtis title card generator), Max Neely-Cohen and Jessie Char’s Baby Registry (which uses the new metadata API to mark items as claimed) and Are.na Cube (Blake Shao’s cube-based navigation for blocks and channels).

If there are capabilities you’d like to see, functionality you’d like to unlock, feel free to add to the API wishlist channel.

Charles Broskoski is one of the many co-founders of Are.na.

As always, you can read this interview on Are.na Editorial.

<3

The Are.na Team