Lab Notes #009: Semble (alpha) API

Since our launch in November 2025 we've seen an explosion of cool things being built from our community. So many that we've been keeping track of as many of them as we can in a Semble Collection (with 49 cards and counting!):

This is all with hardly any proper developer tooling or an API, which speaks to the nature of the atproto ecosystem in general: we can just do things. Apps don't need an API because the protocol is the API (tools can be built directly against the user's PDS or with other services like constellation).

Even so, offering an AppView API simplifies many things for all the builders in our community: one API key, all the functionality.

Today, we are happy to announce our very first version of a fully-featured Semble (alpha*) API!

What we've built

The Semble AppView now exposes over 40 xrpc endpoints, all of which are documented here:

We also have a typescript client available on npmjs and npmx:

Which makes using the API as simple as:

import { createSembleClient } from '@semble.so/api';

const semble = createSembleClient({
  apiKey: process.env.SEMBLE_API_KEY!,
});

const result = await semble.cards.addUrlToLibrary({
  body: { url: 'https://semble.so' },
});

It includes IntelliSense support, making it easy to explore all the available methods.

How to use it

For now the only way to make authenticated requests against our xrpc endpoints is via an API key. To create one, go to your api keys settings page. Make sure to save it somewhere safe. Keys can be revoked at any time.

What's next?

Service Auth

Currently, the only way to make authenticated requests is with an API Key generated in our app view. This is a familiar and traditional access model, but we'd also like to support a service auth flow so users don't need to create an API key in order to enable Semble integrations in other atproto apps.

Published XRPC lexicons

The lexicon spec includes declaring XRPC queries and procedures. We'd like to publish ours (once they've stabilized a bit) to be fully protocol compliant. This would open the door for other Semble app views to get created, ensuring a more decentralized and resilient network.

ATURIs as entity identifiers

Currently the API uses our internal UUIDs to reference entities (Cards, Collections, etc). This is because the API is a light wrapper around our core backend endpoints, but API consumers shouldn't have to handle these. Eventually we'd like to support using ATURIs interchangeably with UUIDs as entity identifiers.

Feedback welcome

This is the very first iteration of a Semble API. There will be many kinks to work out in order to make it easier and more useful for all of you. If you run into any bugs, friction points, or notice missing endpoints that would make what you're trying to do a lot easier, etc. -- let us know!

What will you build?

We're thrilled to see what you all create with this early version of the Semble API.

Whether it's a feature complete client, mobile app, Obsidian plugin, MCP server (@pouriade.com already made one since we first drafted this post 🤯) or whatever else you can dream up, the sky's the limit!

Add whatever you end up building to our API project showcase open collection:

Happy building,

Cosmik Team 🌻