# Docs Welcome to your team’s developer platform

Welcome!

Cosmik is a mission and product-driven R&D lab working at the intersection of social networking protocols, AI and next-generation collaborative research tools. Check out our project docs pages below.

Projects

Cover image
SembleSocial knowledge network for researchers built on ATProtoOverviewsemble-screenshot.0652bb7f.webp
# Overview Semble is a social knowledge network for research built on the AT Protocol. Semble lets you curate links, organize collections, discover what your network is reading, and share insights β€” all while keeping ownership of your data. Semble is similar to apps like [Are.na](https://www.are.na/) and [Sublime](http://sublime.app/), but reimagined for the decentralized web, and with some unique research-specific features. 🌱 *Semble is currently in alpha. Features and APIs may change as we refine the app based on feedback from users like you.* {% embed url="" %} {% embed url="" %} For more resources about what Semble is and how to use it, see our Semble collection below: {% embed url="" %} # FAQ Frequently asked questions about Semble
What types of content can I share on Semble? Is it only for academic research? While we call Semble a "social knowledge network for researchers," we take an expansive view of what "research" means. Semble is designed to be a home for any kind of bookmarking - not just formal academic research, but anyone sharing, curating, organizing, and exploring knowledge! Rather than restricting content types, we're evolving the feed from purely chronological to more configurable and personalized. This means you'll be able to tailor your experience according to your interests. Our first step in this direction is the **media types filter** (rolling out soon), which will let you filter for specific content types - like formal research papers if that's your focus, or podcasts, videos, and other media types based on your preferences.
# Quickstart ### Requirements To use Semble you currently need a Bluesky account. If you don't have one, you can sign up at [bsky.app](https://bsky.app). In the future we'll provide an independent Cosmik ID. ### First steps **1. Log in.** Head to [semble.so](https://semble.so) and log in with your Bluesky account. **2. Create your first card.** Cards are the building blocks of Semble β€” they're simply links with optional notes attached. To create one: * Click the **+** button in the bottom left corner * Paste a URL you want to save * Add a note to capture your thoughts (optional) * Save it **3. Explore the network.** Click on **Explore** to see recent activity from across the network β€” new cards, collections, and what others are curating. **4. Add cards from others** See something interesting that someone else has shared? Click the **+** symbol on their card to add it to your own collection. **5. Create collections.** Collections help you organize cards around themes, projects, or research questions. Think of them like playlists for ideas. You can create a new collection and start adding cards to it whenever you're ready. Note that collections are optional. All your cards will automatically go into your default **Library** collection :grey\_exclamation:**Important**: Right now, everything you save on Semble is public. This is in line with Semble's vision of building shared knowledge networks, but we recognize the value of private data as well, and it's [on our roadmap](https://github.com/cosmik-network/semble/issues/196).
# Bookmarklet We plan on building a [browser extension](https://github.com/cosmik-network/semble/issues/112) that brings most of Semble's features to every webpage. In the meantime, the next best thing is installing our bookmarklet. You can do so by following the setup steps here: # Mobile Setup Installing Semble as a progressive web app (PWA) provides the best mobile experience (until we have a native [mobile app](https://github.com/cosmik-network/semble/issues/184)). Below are the steps ### iOS 1\. Login to [semble.so](https://semble.so/) on your phone's browser 2\. Tap the share sheet, scroll down and tap "save to home screen" 3\. Use Semble as normal!
#### iOS Shortcut Our iOS shortcut lets you more quickly save a link to semble on your iPhone. It currently works by opening the Semble page for the link you are saving, and you can then add it to your library and other collections from there (make sure you're logged in!) Follow [this link ](https://www.icloud.com/shortcuts/e75810a095d24d53bd19c1cf0cde8d03)on your iPhone to install it.
Note: make sure to to scroll to the bottom of the share sheet, click "edit actions" and drag the shortcut to the top "favorites" list for quicker access. ### Android 1\. Login to [semble.so](https://semble.so/) on your phone's browser 2\. Tap the three dots in the top right, select "add to homescreen" 3\. Use Semble as normal!
# Semble page Clicking on a card will take you to the Semble page: a page aggregating all of the activity around the link in that card, such as collections it's featured in, and comments about the link. So each link shared on the network will have a corresponding Semble page, which you can also find at `https://semble.so/url?id=/`\[1]. So for example, [`https://semble.so/url?id=https://cosmik.network`](https://semble.so/url?id=https://cosmik.network) will aggregate the activity around [`https://cosmik.network/`](https://cosmik.network/). In the future we plan for the Semble page to aggregate activity from other ATProto apps and beyond. The Semble page is one of the directions we're most excited about developing, and we envision it as a decentralized social sensemaking layer for any online content. ### Similar Cards The Similar Cards feature helps you discover related content across the Semble network by surfacing semantically similar URLs **How it works** Similar Cards uses semantic similarity to identify URLs that share thematic or contextual connections with the current page you're viewing. This creates an organic discovery layer that helps you explore related content that other users have curated. **Accessing Similar Cards** You can find Similar Cards in a dedicated tab on any Semble page⁠⁠. Simply navigate to the tab to see a list of semantically related URLs from across the network:
\[1] We also support the simpler url redirect structure `https://semble.so/url/https://cosmik.network`, inspired by the excellent [henry.ink](https://henry.ink/) # You control your data Semble runs on the [**AT Protocol**](https://atproto.com/) (ATProto), the same decentralized infrastructure powering Bluesky. ATProto separates apps from data: you use Semble's interface while your data remains independently yours. Think of it like email β€” switch clients anytime without losing your messages. Your cards, collections, and notes live in *your* personal data repository, not locked in Semble's database. This means: * **Interoperability**: Connect with other ATProto apps. For example, Semble can use your Bluesky social graph to personalize discovery. Conversely, someone could build a feed reader that subscribes to your collections, or a visualization tool that maps your collection network as a graph. * **Longevity**: Your data isn't hostage to any single platform's survival (in theory - see [honest reality below](#the-honest-reality-and-the-exciting-experiment)) To learn more about how ATProto works, check out [this excellent explainer](https://overreacted.io/open-social/). #### The honest reality (and the exciting experiment) Right now, most users rely on Bluesky's hosted infrastructure. While the protocol enables ownership and portability, the practical reality is that someone is paying for the servers. Self-hosting is possible but not yet practical for most people. **This is part of the ongoing experiment in building sustainable open social and open research infrastructure,** and at Cosmik we're excited to be working at the leading edge of it. How do we create systems that give users real ownership while remaining accessible and sustainable? How do we build knowledge infrastructure that serves researchers rather than extracting from them? These are open questions, and Semble is our contribution to the grand experiment. **By using Semble, you're part of this experiment too!** Your participation is a vote of confidence for user-controlled infrastructure that serves researchers rather than extracts from them, and your feedback helps us evolve more resilient and sustainable systems. # Connections Connections in Semble link two pieces of content with a typed semantic relationship. Each connection has a **source** (A), a **target** (B), an optional **relation type** that describes how they relate, and an optional **note** for additional context.
## Semble Connection Types | Type | Lexicon ID | Description | Example | | ----------------- | ------------- | ------------------------------------------------- | ------------------------------------------------------------------- | | Related (default) | `related` | A is related to B in some unspecified way | Paper A and paper B both deal with collective intelligence | | Supports | `supports` | A provides evidence or reasoning in favor of B | Dataset A supports the findings of paper B | | Opposes | `opposes` | A provides evidence or reasoning against B | Evidence A contradicts claim B | | Addresses | `addresses` | A responds to or answers B | Paper A addresses the open question posed in paper B | | Helpful | `helpful` | A is helpful for contextualizing/understanding B | Essay A offers a thoughtful critique of research paper B | | Explainer | `explainer` | A explains or summarizes B for a broader audience | Thread A walks through the key findings of paper B | | Leads to | `leads_to` | A led me to B β€” a trail segment worth walking | Listening to podcast A led me to find book B | | Supplements | `supplements` | A is supplemental material for B | Dataset A accompanies and supports the methods described in paper B | | References | `references` | A mentions or references B | Podcast episode A references and discusses paper B | | Same as | `same_as` | A refers to the same underlying entity as B | A and B are two URLs hosting the same paper (same DOI) | # Getting Started with the Semble PDS Client {% hint style="warning" %} We'll be shipping a more comprehensive API in the future. Meanwhile, this is a simple and lightweight PDS client working with Semble data directly on your PDS. Please share any feedback about bugs or ways to improve it (or feel free to make a PR directly to the package). **The `SemblePDSClient` node package covers all read and write operations needed for working with Semble data directly on your PDS.** Also, you don’t have to use our PDS client (i.e. if you are using a different programming language). You are free to interact with Semble data in your PDS however you like. For example, changes made directly in [pdsls.dev](http://pdsls.dev/) will still reflect in Semble. If you make your own PDS clients for Semble data, we’d love to know about it, too! {% endhint %} #### Installation ``` npm install @cosmik.network/semble-pds-client ``` You can view the npm package [here](https://www.npmjs.com/package/@cosmik.network/semble-pds-client). #### Usage ```tsx import { SemblePDSClient } from '@cosmik.network/semble-pds-client'; const client = new SemblePDSClient({ service: 'https://bsky.social', // or your PDS URL env: 'dev', // optional: appends to NSID (e.g. network.cosmik.dev.*), usually only used for testing purposes }); // Login with app password await client.login('your-handle.bsky.social', 'your-app-password'); // Create a URL card const card = await client.createCard({ url: 'https://example.com', note: 'Optional note about this URL', viaCard: someOtherCard, // Optional: reference to the card that led to this one }); // Add a note to an existing card const noteCard = await client.addNoteToCard(card, 'This is my note'); // Create a collection const collection = await client.createCollection({ name: 'My Collection', description: 'Optional description', }); // Add card to collection const collectionLink = await client.addCardToCollection(card, collection); // Add card to collection with provenance tracking const collectionLinkWithProvenance = await client.addCardToCollection( card, collection, viaCard, // Optional: reference to the card that led to this addition ); // Update a note await client.updateNote(noteCard, 'Updated note text'); // Delete a card await client.deleteCard(card); // Update collection await client.updateCollection(collection, 'New Name', 'New description'); // Delete collection await client.deleteCollection(collection); // Remove card from collection await client.removeCardFromCollection(collectionLink); // Get a specific card const cardRecord = await client.getCard(card); // Get a specific collection const collectionRecord = await client.getCollection(collection); // List your own cards with pagination const myCardsResult = await client.getMyCards({ limit: 50, cursor: 'optional-cursor', reverse: false, }); // List your own collections with pagination const myCollectionsResult = await client.getMyCollections({ limit: 20, }); // List cards for a specific user const userCardsResult = await client.getCards('did:plc:example123', { limit: 50, }); // List collections for a specific user const userCollectionsResult = await client.getCollections( 'did:plc:example123', { limit: 20, }, ); // Batch create multiple cards const cardsResult = await client.createCards({ cards: [ { url: 'https://example1.com', note: 'First card' }, { url: 'https://example2.com' }, { url: 'https://example3.com', viaCard: someCard }, ], }); // Batch create multiple collections const collectionsResult = await client.createCollections({ collections: [ { name: 'Collection 1', description: 'First collection' }, { name: 'Collection 2' }, ], }); // Batch add multiple cards to a collection const linksResult = await client.addCardsToCollection({ collection: myCollection, cards: [card1, card2, card3], viaCard: someCard, // Optional: applies to all cards being added }); ``` # Semble Lexicon Reference This document provides a complete reference for Semble’s ATProto lexicons (data schemas). {% hint style="info" %} Alpha documentation generated with Claude Code and edited by the Cosmik team. Subject to revision as the project stabilizes {% endhint %} ### Overview Semble uses three primary lexicon collections in the `network.cosmik` namespace: * **`network.cosmik.card`** - URL bookmarks and notes * **`network.cosmik.collection`** - Named collections for organizing cards * **`network.cosmik.collectionLink`** - Many-to-many links between cards and collections ### network.cosmik.card Cards are the core record type in Semble, representing bookmarked URLs and associated notes. #### Card Types Cards come in two types, distinguished by the `type` field: 1. **URL Cards** (`type: "URL"`) - Bookmark a URL with metadata 2. **NOTE Cards** (`type: "NOTE"`) - Add notes to existing URL cards #### URL Card Structure ```json { "type": "URL", "$type": "network.cosmik.card", "content": { "url": "https://example.com/article", "$type": "network.cosmik.card#urlContent", "metadata": { "type": "article", "$type": "network.cosmik.card#urlMetadata", "title": "Example Article Title", "description": "Article description or excerpt...", "author": "Author Name", "siteName": "Example Site", "imageUrl": "https://example.com/image.jpg", "publishedDate": "2025-01-15T10:30:00.000Z", "retrievedAt": "2025-01-15T12:00:00.000Z" } }, "createdAt": "2025-01-15T12:00:00.000Z", "provenance": { "via": { "uri": "at://did:plc:xxx/network.cosmik.card/zzz", "cid": "bafyrei..." }, "$type": "network.cosmik.defs#provenance" } } ``` **URL Card Fields** | Field | Type | Required | Description | | -------------------------------- | ------ | -------- | ------------------------------------------------------------------ | | `type` | string | Yes | Always `"URL"` for URL cards | | `$type` | string | Yes | Always `"network.cosmik.card"` | | `content` | object | Yes | Contains the URL and metadata | | `content.url` | string | Yes | The bookmarked URL | | `content.$type` | string | Yes | Always `"network.cosmik.card#urlContent"` | | `content.metadata` | object | No | Fetched metadata about the URL | | `content.metadata.type` | string | No | Content type: `"video"`, `"article"`, `"image"`, `"website"`, etc. | | `content.metadata.title` | string | No | Page or content title | | `content.metadata.description` | string | No | Page description or excerpt | | `content.metadata.author` | string | No | Content author | | `content.metadata.siteName` | string | No | Website name | | `content.metadata.imageUrl` | string | No | Preview image URL | | `content.metadata.publishedDate` | string | No | ISO 8601 datetime of original publication | | `content.metadata.retrievedAt` | string | No | ISO 8601 datetime when metadata was fetched | | `createdAt` | string | Yes | ISO 8601 datetime when card was created | | `provenance` | object | No | Tracks how this card was discovered in the network | | `provenance.via` | object | No | Reference to the card from which this one was collected | | `provenance.via.uri` | string | No | AT-URI of the source card | | `provenance.via.cid` | string | No | Content ID of the source card | | `provenance.$type` | string | No | Always `"network.cosmik.defs#provenance"` | {% hint style="info" %} **Note:** The `provenance` field enables tracking how cards are discovered and shared across the network, supporting notifications when someone collects your card. {% endhint %} #### NOTE Card Structure NOTE cards attach textual notes to existing URL cards via a parent reference. ```json { "type": "NOTE", "$type": "network.cosmik.card", "content": { "text": "My thoughts about this article...", "$type": "network.cosmik.card#noteContent" }, "url": "https://example.com/article", "parentCard": { "uri": "at://did:plc:xxx/network.cosmik.card/yyy", "cid": "bafyrei..." }, "createdAt": "2025-01-15T12:30:00.000Z" } ``` **NOTE Card Fields** | Field | Type | Required | Description | | ---------------- | ------ | -------- | ------------------------------------------------------------------------ | | `type` | string | Yes | Always `"NOTE"` for note cards | | `$type` | string | Yes | Always `"network.cosmik.card"` | | `content` | object | Yes | Contains the note text | | `content.text` | string | Yes | The note content | | `content.$type` | string | Yes | Always `"network.cosmik.card#noteContent"` | | `url` | string | No | May contain the parent card's URL | | `parentCard` | object | Yes | Reference to the parent URL card | | `parentCard.uri` | string | Yes | AT-URI of parent card (e.g., `at://did:plc:xxx/network.cosmik.card/yyy`) | | `parentCard.cid` | string | Yes | Content ID (CID) of parent card | | `createdAt` | string | Yes | ISO 8601 datetime when note was created | #### Design Notes * **URL cards** store the primary bookmark and fetched metadata * **NOTE cards** attach to URL cards via `parentCard` reference * A URL card currently can only have a single NOTE card attached * When displaying cards, NOTE cards should be shown attached to their parent URL card, not as separate items *** ### network.cosmik.collection Collections are named groups for organizing cards. #### Collection Structure ```json { "$type": "network.cosmik.collection", "name": "AI Research", "description": "Articles and papers about artificial intelligence", "createdAt": "2025-01-15T12:00:00.000Z" } ``` **Collection Fields** | Field | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------ | | `$type` | string | Yes | Always `"network.cosmik.collection"` | | `name` | string | Yes | Collection name | | `description` | string | No | Optional description | | `createdAt` | string | Yes | ISO 8601 datetime when created | *** ### network.cosmik.collectionLink CollectionLinks establish many-to-many relationships between cards and collections. #### CollectionLink Structure ```json { "$type": "network.cosmik.collectionLink", "card": { "uri": "at://did:plc:xxx/network.cosmik.card/abc", "cid": "bafyrei..." }, "collection": { "uri": "at://did:plc:xxx/network.cosmik.collection/def", "cid": "bafyrei..." }, "createdAt": "2025-01-15T12:00:00.000Z" } ``` **CollectionLink Fields** | Field | Type | Required | Description | | ---------------- | ------ | -------- | ---------------------------------------- | | `$type` | string | Yes | Always `"network.cosmik.collectionLink"` | | `card` | object | Yes | Reference to a card | | `card.uri` | string | Yes | AT-URI of the card | | `card.cid` | string | Yes | Content ID of the card | | `collection` | object | Yes | Reference to a collection | | `collection.uri` | string | Yes | AT-URI of the collection | | `collection.cid` | string | Yes | Content ID of the collection | | `createdAt` | string | Yes | ISO 8601 datetime when link was created | #### Design Notes * **One card** can belong to **multiple collections** (many-to-many) * **One collection** can contain **multiple cards** * Links are stored as separate records, not embedded in cards or collections * To find all cards in a collection, query for collectionLinks with matching `collection.uri` * To find all collections for a card, query for collectionLinks with matching `card.uri` *** ### Working with References ATProto uses **strong references** containing both URI and CID: ```javascript { "uri": "at://did:plc:xxx/network.cosmik.card/yyy", "cid": "bafyreib4dj272r4cfzwp4hw47jote5ovy5b6j63ejm7wz44txp4pyobhkm" } ``` * **URI**: Unique identifier in the format `at://[DID]/[collection]/[rkey]` * **CID**: Content-addressed identifier ensuring data integrity When building relationships (like collectionLinks or parentCard), you'll need to extract the URI from records and construct these reference objects. *** ### Exmple: Complete Card with Collection Here's a complete example showing all record types working together: **URL Card:** ```json { "uri": "at://did:plc:user123/network.cosmik.card/card1", "cid": "bafyreiabc...", "value": { "type": "URL", "$type": "network.cosmik.card", "content": { "url": "https://example.com/ai-research", "$type": "network.cosmik.card#urlContent", "metadata": { "type": "article", "title": "The Future of AI", "description": "An exploration of AI trends...", "author": "Jane Doe" } }, "createdAt": "2025-01-15T12:00:00.000Z" } } ``` **NOTE Card (attached to above):** ```json { "uri": "at://did:plc:user123/network.cosmik.card/note1", "cid": "bafyreidef...", "value": { "type": "NOTE", "$type": "network.cosmik.card", "content": { "text": "Interesting perspective on AGI timelines", "$type": "network.cosmik.card#noteContent" }, "parentCard": { "uri": "at://did:plc:user123/network.cosmik.card/card1", "cid": "bafyreiabc..." }, "createdAt": "2025-01-15T12:30:00.000Z" } } ``` **Collection:** ```json { "uri": "at://did:plc:user123/network.cosmik.collection/col1", "cid": "bafyreighi...", "value": { "$type": "network.cosmik.collection", "name": "AI Research", "description": "My AI reading list", "createdAt": "2025-01-10T10:00:00.000Z" } } ``` **CollectionLink (linking card to collection):** ```json { "uri": "at://did:plc:user123/network.cosmik.collectionLink/link1", "cid": "bafyreijkl...", "value": { "$type": "network.cosmik.collectionLink", "card": { "uri": "at://did:plc:user123/network.cosmik.card/card1", "cid": "bafyreiabc..." }, "collection": { "uri": "at://did:plc:user123/network.cosmik.collection/col1", "cid": "bafyreighi..." }, "createdAt": "2025-01-15T12:00:00.000Z" } } ``` # Semble API Fully featured xrpc endpoints for interacting with Semble. Typescript client available on [npm](https://www.npmjs.com/package/@semble.so/api) & [npmx](https://npmx.dev/package/@semble.so/api). ## Creating an API key go to and click `Create key`.
Enter a name and copy the generated API key. Save it somewhere safe, you won't be able to view it again.
# Cards ## Add a URL to library > Saves a URL as a URL card in the authenticated user's library. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.addUrl":{"post":{"description":"Saves a URL as a URL card in the authenticated user's library.","summary":"Add a URL to library","tags":["cards"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"addUrlToLibrary","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"note":{"type":"string"},"collectionIds":{"type":"array","items":{"type":"string"}},"viaCardId":{"type":"string","description":"The ID of the card that led to saving this URL. If included, the author of the viaCard will be notified."}},"required":["url"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"urlCardId":{"type":"string"},"noteCardId":{"type":"string"}},"required":["urlCardId"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Update URL card associations > Add or remove the card to/from collections. Add a note to the URL card or update the existing note. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.updateUrlAssociations":{"post":{"description":"Add or remove the card to/from collections. Add a note to the URL card or update the existing note.","summary":"Update URL card associations","tags":["cards"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"urlCardAssociations","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"cardId":{"type":"string"},"note":{"type":"string"},"addToCollections":{"type":"array","items":{"type":"string"}},"removeFromCollections":{"type":"array","items":{"type":"string"}},"viaCardId":{"type":"string","description":"The ID of the card that led to saving this URL. If included, the author of the viaCard will be notified."}},"required":["cardId"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"urlCardId":{"type":"string"},"noteCardId":{"type":"string"},"addedToCollections":{"type":"array","items":{"type":"string"}},"removedFromCollections":{"type":"array","items":{"type":"string"}}},"required":["urlCardId","addedToCollections","removedFromCollections"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## List my library URL cards > Returns a paginated list of URL cards in the authenticated user's library. When \`searchText\` is provided, results are filtered to cards whose title, description, or URL match all whitespace-separated tokens (case-insensitive). ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.listMine":{"get":{"description":"Returns a paginated list of URL cards in the authenticated user's library. When `searchText` is provided, results are filtered to cards whose title, description, or URL match all whitespace-separated tokens (case-insensitive).","summary":"List my library URL cards","tags":["cards"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"urlType","in":"query","schema":{"type":"string","enum":["article","link","book","research","audio","video","social","event","software"]}},{"name":"uncollected","in":"query","schema":{"type":"boolean","nullable":true}},{"name":"searchText","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"myUrlCards","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"cards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},"required":["sortOrder","sortBy"]}},"required":["cards","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get URL metadata and optional Semble stats > Fetches title, description, and other metadata for a given URL. Can optionally include aggregated Semble stats for the URL, such as total saves and collection counts. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.getUrlMetadata":{"get":{"description":"Fetches title, description, and other metadata for a given URL. Can optionally include aggregated Semble stats for the URL, such as total saves and collection counts.","summary":"Get URL metadata and optional Semble stats","tags":["cards"],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"name":"includeStats","in":"query","schema":{"type":"boolean","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"urlMetadata","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"stats":{"type":"object","properties":{"libraryCount":{"type":"number"},"noteCount":{"type":"number"},"collectionCount":{"type":"number"},"connections":{"type":"object","properties":{"all":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"incoming":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"outgoing":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}}},"required":["all","incoming","outgoing"]}},"required":["libraryCount","noteCount","collectionCount","connections"]},"urlInLibrary":{"type":"boolean"},"urlIsConnected":{"type":"boolean"}},"required":["metadata"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Check if a given URL has been saved to your library > Returns whether a URL is already saved in the authenticated user's library, along with all collections the user added it to. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.getLibraryStatus":{"get":{"description":"Returns whether a URL is already saved in the authenticated user's library, along with all collections the user added it to.","summary":"Check if a given URL has been saved to your library","tags":["cards"],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"urlLibraryStatus","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"card":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}}}}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get users who have saved a URL to their library > Returns a paginated list of users who have saved a given URL to their library, including the URL Card of each user. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.getLibrariesForUrl":{"get":{"description":"Returns a paginated list of users who have saved a given URL to their library, including the URL Card of each user.","summary":"Get users who have saved a URL to their library","tags":["cards"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"librariesForUrl","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"libraries":{"type":"array","items":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"card":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]}},"required":["user","card"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},"required":["sortOrder","sortBy"]}},"required":["libraries","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get notes for a URL > Returns a paginated list of all notes that are added to a given URL. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.getNoteCardsForUrl":{"get":{"description":"Returns a paginated list of all notes that are added to a given URL.","summary":"Get notes for a URL","tags":["cards"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"noteCardsForUrl","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"note":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","note","author","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},"required":["sortOrder","sortBy"]}},"required":["notes","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Search cards > Full-text search across URL Cards titles, descriptions and URLs. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.search":{"get":{"description":"Full-text search across URL Cards titles, descriptions and URLs.","summary":"Search cards","tags":["cards"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"searchQuery","in":"query","required":true,"schema":{"type":"string"}},{"name":"urlType","in":"query","schema":{"type":"string","enum":["article","link","book","research","audio","video","social","event","software"]}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"searchCards","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},"required":["sortOrder","sortBy"]}},"required":["urls","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get a card by ID > Returns a card and its associated metadata by card ID. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.get":{"get":{"description":"Returns a card and its associated metadata by card ID.","summary":"Get a card by ID","tags":["cards"],"parameters":[{"name":"cardId","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"cardById","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"libraries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author","collections","libraries"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Update a note added to a URL card > Updates the content of a note added to a URL card. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.updateNote":{"post":{"description":"Updates the content of a note added to a URL card.","summary":"Update a note added to a URL card","tags":["cards"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"cardNote","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"cardId":{"type":"string"},"note":{"type":"string"}},"required":["cardId","note"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"cardId":{"type":"string"}},"required":["cardId"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Remove a card from library > Removes a card from the authenticated user's library. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.removeFromLibrary":{"post":{"description":"Removes a card from the authenticated user's library.","summary":"Remove a card from library","tags":["cards"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"removeFromLibrary","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"cardId":{"type":"string"}},"required":["cardId"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"cardId":{"type":"string"}},"required":["cardId"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## List a user's URL cards > Returns a paginated list of URL cards in a user's library, identified by handle or DID. When \`searchText\` is provided, results are filtered to cards whose title, description, or URL match all whitespace-separated tokens (case-insensitive). ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.card.listByUser":{"get":{"description":"Returns a paginated list of URL cards in a user's library, identified by handle or DID. When `searchText` is provided, results are filtered to cards whose title, description, or URL match all whitespace-separated tokens (case-insensitive).","summary":"List a user's URL cards","tags":["cards"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"name":"urlType","in":"query","schema":{"type":"string","enum":["article","link","book","research","audio","video","social","event","software"]}},{"name":"uncollected","in":"query","schema":{"type":"boolean","nullable":true}},{"name":"searchText","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"cardsByUser","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"cards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},"required":["sortOrder","sortBy"]}},"required":["cards","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` # Collections ## List my collections > Returns a paginated list of the authenticated user's collections. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.listMine":{"get":{"description":"Returns a paginated list of the authenticated user's collections.","summary":"List my collections","tags":["collections"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["name","createdAt","updatedAt","cardCount","addedAt"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"searchText","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"myCollections","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["name","createdAt","updatedAt","cardCount","addedAt"]}},"required":["sortOrder","sortBy"]}},"required":["collections","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Create a collection > Creates a new collection for the authenticated user. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.create":{"post":{"description":"Creates a new collection for the authenticated user.","summary":"Create a collection","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"createCollection","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]}},"required":["name"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string"}},"required":["collectionId"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get collections containing a URL > Returns collections that contain a specific URL. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.getForUrl":{"get":{"description":"Returns collections that contain a specific URL.","summary":"Get collections containing a URL","tags":["collections"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["name","createdAt","updatedAt","cardCount","addedAt"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"collectionsForUrl","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["name","createdAt","updatedAt","cardCount","addedAt"]}},"required":["sortOrder","sortBy"]}},"required":["collections","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Search collections > Full-text search across collection names and descriptions, optionally filtered by user or access type. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.search":{"get":{"description":"Full-text search across collection names and descriptions, optionally filtered by user or access type.","summary":"Search collections","tags":["collections"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["name","createdAt","updatedAt","cardCount","addedAt"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"searchText","in":"query","schema":{"type":"string"}},{"name":"identifier","in":"query","schema":{"type":"string"}},{"name":"accessType","in":"query","schema":{"type":"string","enum":["OPEN","CLOSED"]}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"searchCollections","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["name","createdAt","updatedAt","cardCount","addedAt"]}},"required":["sortOrder","sortBy"]}},"required":["collections","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get a collection by ID > Returns a collection and its cards, paginated, by collection ID. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.get":{"get":{"description":"Returns a collection and its cards, paginated, by collection ID.","summary":"Get a collection by ID","tags":["collections"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"collectionId","in":"query","required":true,"schema":{"type":"string"}},{"name":"urlType","in":"query","schema":{"type":"string","enum":["article","link","book","research","audio","video","social","event","software"]}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"collectionById","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"},"urlCards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},"required":["sortOrder","sortBy"]}},"required":["id","name","author","cardCount","createdAt","updatedAt","urlCards","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Update a collection > Updates the name, description, or access type of a collection. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.update":{"post":{"description":"Updates the name, description, or access type of a collection.","summary":"Update a collection","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"updateCollection","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]}},"required":["collectionId","name"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string"}},"required":["collectionId"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Delete a collection > Permanently deletes a collection owned by the authenticated user. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.delete":{"post":{"description":"Permanently deletes a collection owned by the authenticated user.","summary":"Delete a collection","tags":["collections"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"deleteCollection","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string"}},"required":["collectionId"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string"}},"required":["collectionId"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## List a user's collections > Returns a paginated list of collections owned by a user, identified by handle or DID. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.listByUser":{"get":{"description":"Returns a paginated list of collections owned by a user, identified by handle or DID.","summary":"List a user's collections","tags":["collections"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["name","createdAt","updatedAt","cardCount","addedAt"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"name":"searchText","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"collectionsByUser","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["name","createdAt","updatedAt","cardCount","addedAt"]}},"required":["sortOrder","sortBy"]}},"required":["collections","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get a collection by AT URI > Returns a collection and its cards, looked up by AT Protocol handle and record key. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.getByAtUri":{"get":{"description":"Returns a collection and its cards, looked up by AT Protocol handle and record key.","summary":"Get a collection by AT URI","tags":["collections"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"handle","in":"query","required":true,"schema":{"type":"string"}},{"name":"recordKey","in":"query","required":true,"schema":{"type":"string"}},{"name":"urlType","in":"query","schema":{"type":"string","enum":["article","link","book","research","audio","video","social","event","software"]}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"collectionByAtUri","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"},"urlCards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["createdAt","updatedAt","libraryCount"]}},"required":["sortOrder","sortBy"]}},"required":["id","name","author","cardCount","createdAt","updatedAt","urlCards","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## List open collections with a contributor > Returns open collections that a given user has contributed cards to. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.listContributed":{"get":{"description":"Returns open collections that a given user has contributed cards to.","summary":"List open collections with a contributor","tags":["collections"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["name","createdAt","updatedAt","cardCount","addedAt"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"openWithContributor","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortOrder":{"type":"string","enum":["asc","desc"]},"sortBy":{"type":"string","enum":["name","createdAt","updatedAt","cardCount","addedAt"]}},"required":["sortOrder","sortBy"]}},"required":["collections","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get collection followers > Returns users who follow a given collection. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.getFollowers":{"get":{"description":"Returns users who follow a given collection.","summary":"Get collection followers","tags":["collections"],"parameters":[{"name":"collectionId","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"collectionFollowers","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["users","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get collection follower count > Returns the total number of followers for a collection. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.getFollowerCount":{"get":{"description":"Returns the total number of followers for a collection.","summary":"Get collection follower count","tags":["collections"],"parameters":[{"name":"collectionId","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"collectionFollowersCount","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"}},"required":["count"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Recommended collections to save a URL to > Returns collections that contain URLs semantically similar to the given URL, ranked by how many similar URLs each contains. Split into the authenticated user's own collections and open collections from across the network (excluding the caller's own). The limit applies to each set independently. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.getRecommendedForUrl":{"get":{"description":"Returns collections that contain URLs semantically similar to the given URL, ranked by how many similar URLs each contains. Split into the authenticated user's own collections and open collections from across the network (excluding the caller's own). The limit applies to each set independently.","summary":"Recommended collections to save a URL to","tags":["collections"],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"recommendedCollectionsForUrl","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"myCollections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"openCollections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}}},"required":["myCollections","openCollections"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get collection contributors > Returns users who have added cards to a given collection. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.collection.getContributors":{"get":{"description":"Returns users who have added cards to a given collection.","summary":"Get collection contributors","tags":["collections"],"parameters":[{"name":"collectionId","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"collectionContributors","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}},"contributionCount":{"type":"number"}},"required":["id","name","handle","contributionCount"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["users","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` # Users ## Get my profile > Returns the profile of the authenticated user. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.actor.getMyProfile":{"get":{"description":"Returns the profile of the authenticated user.","summary":"Get my profile","tags":["users"],"parameters":[{"name":"includeStats","in":"query","schema":{"type":"boolean","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"myProfile","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get a user profile > Returns the public profile of a user, identified by handle or DID. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.actor.getProfile":{"get":{"description":"Returns the public profile of a user, identified by handle or DID.","summary":"Get a user profile","tags":["users"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"name":"includeStats","in":"query","schema":{"type":"boolean","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"userProfile","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}},"atprotoSessionValid":{"type":"boolean"}},"required":["id","name","handle"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` # Feeds ## Get global feed > Returns a paginated activity feed across all users, ordered by recency, with optional filters. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.feed.getGlobal":{"get":{"description":"Returns a paginated activity feed across all users, ordered by recency, with optional filters.","summary":"Get global feed","tags":["feeds"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"urlType","in":"query","schema":{"type":"string","enum":["article","link","book","research","audio","video","social","event","software"]}},{"name":"source","in":"query","schema":{"type":"string","enum":["margin","semble"]}},{"name":"activityTypes","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"actorIds","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"includeKnownBots","in":"query","schema":{"type":"boolean","nullable":true}},{"name":"beforeActivityId","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"globalFeed","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string","format":"date-time"},"activityType":{"type":"string","enum":["CARD_COLLECTED"]},"card":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}}},"required":["id","user","createdAt","activityType","card","collections"]},{"type":"object","properties":{"id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string","format":"date-time"},"activityType":{"type":"string","enum":["CONNECTION_CREATED"]},"connection":{"type":"object","properties":{"connection":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"note":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"curator":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"required":["id","createdAt","updatedAt","curator"]},"source":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]},"target":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"required":["connection","source","target"]}},"required":["id","user","createdAt","activityType","connection"]}]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"},"nextCursor":{"type":"string"}},"required":["currentPage","hasMore","limit"]}},"required":["activities","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get following feed > Returns an activity feed of users and collections the authenticated user follows. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.feed.getFollowing":{"get":{"description":"Returns an activity feed of users and collections the authenticated user follows.","summary":"Get following feed","tags":["feeds"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"urlType","in":"query","schema":{"type":"string","enum":["article","link","book","research","audio","video","social","event","software"]}},{"name":"source","in":"query","schema":{"type":"string","enum":["margin","semble"]}},{"name":"activityTypes","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"actorIds","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"includeKnownBots","in":"query","schema":{"type":"boolean","nullable":true}},{"name":"beforeActivityId","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"followingFeed","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string","format":"date-time"},"activityType":{"type":"string","enum":["CARD_COLLECTED"]},"card":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}}},"required":["id","user","createdAt","activityType","card","collections"]},{"type":"object","properties":{"id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string","format":"date-time"},"activityType":{"type":"string","enum":["CONNECTION_CREATED"]},"connection":{"type":"object","properties":{"connection":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"note":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"curator":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"required":["id","createdAt","updatedAt","curator"]},"source":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]},"target":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"required":["connection","source","target"]}},"required":["id","user","createdAt","activityType","connection"]}]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"},"nextCursor":{"type":"string"}},"required":["currentPage","hasMore","limit"]}},"required":["activities","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get Bluesky following feed > Returns an activity feed of the Semble users a given account follows on Bluesky. Defaults to the authenticated user; pass \`identifier\` (DID or handle) to view another account’s feed. Requires either authentication or \`identifier\`. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.feed.getBskyFollowing":{"get":{"description":"Returns an activity feed of the Semble users a given account follows on Bluesky. Defaults to the authenticated user; pass `identifier` (DID or handle) to view another account’s feed. Requires either authentication or `identifier`.","summary":"Get Bluesky following feed","tags":["feeds"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"urlType","in":"query","schema":{"type":"string","enum":["article","link","book","research","audio","video","social","event","software"]}},{"name":"source","in":"query","schema":{"type":"string","enum":["margin","semble"]}},{"name":"activityTypes","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"includeKnownBots","in":"query","schema":{"type":"boolean","nullable":true}},{"name":"beforeActivityId","in":"query","schema":{"type":"string"}},{"name":"identifier","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"bskyFollowingFeed","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string","format":"date-time"},"activityType":{"type":"string","enum":["CARD_COLLECTED"]},"card":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}}},"required":["id","user","createdAt","activityType","card","collections"]},{"type":"object","properties":{"id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string","format":"date-time"},"activityType":{"type":"string","enum":["CONNECTION_CREATED"]},"connection":{"type":"object","properties":{"connection":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"note":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"curator":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"required":["id","createdAt","updatedAt","curator"]},"source":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]},"target":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"required":["connection","source","target"]}},"required":["id","user","createdAt","activityType","connection"]}]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"},"nextCursor":{"type":"string"}},"required":["currentPage","hasMore","limit"]}},"required":["activities","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` # Notifications ## List my notifications > Returns the authenticated user's notifications. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.notification.list":{"get":{"description":"Returns the authenticated user's notifications.","summary":"List my notifications","tags":["notifications"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string"}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"unreadOnly","in":"query","schema":{"type":"boolean","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"myNotifications","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"notifications":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string"},"type":{"type":"string","enum":["USER_ADDED_YOUR_CARD","USER_ADDED_YOUR_BSKY_POST","USER_ADDED_YOUR_COLLECTION","USER_ADDED_TO_YOUR_COLLECTION","SUBSCRIBED_USER_ADDED_CARD","USER_ADDED_CARD_TO_SUBSCRIBED_COLLECTION","USER_ADDED_SUBSCRIBED_COLLECTION"]},"read":{"type":"boolean"},"card":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}}},"required":["id","user","createdAt","type","read","card"]},{"type":"object","properties":{"id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string"},"type":{"type":"string","enum":["USER_FOLLOWED_YOU","USER_FOLLOWED_YOUR_COLLECTION"]},"read":{"type":"boolean"},"followTargetType":{"type":"string","enum":["USER","COLLECTION"]},"followTargetId":{"type":"string"},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}}},"required":["id","user","createdAt","type","read","followTargetType"]},{"type":"object","properties":{"id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string"},"type":{"type":"string","enum":["USER_CONNECTED_YOUR_URL","USER_CONNECTED_YOUR_POST","USER_CONNECTED_YOUR_COLLECTION","SUBSCRIBED_USER_MADE_CONNECTION","USER_CONNECTED_SUBSCRIBED_COLLECTION"]},"read":{"type":"boolean"},"connection":{"type":"object","properties":{"connection":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"note":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"curator":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"required":["id","createdAt","updatedAt","curator"]},"source":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]},"target":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"required":["connection","source","target"]}},"required":["id","user","createdAt","type","read","connection"]},{"type":"object","properties":{"id":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"createdAt":{"type":"string"},"type":{"type":"string","enum":["USER_MENTIONED_YOU"]},"read":{"type":"boolean"},"mentionSource":{"type":"string","enum":["NOTE","CONNECTION","COLLECTION"]},"card":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]},"connection":{"type":"object","properties":{"connection":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"note":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"curator":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"required":["id","createdAt","updatedAt","curator"]},"source":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]},"target":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"required":["connection","source","target"]},"mentionCollection":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"required":["id","user","createdAt","type","read","mentionSource"]}]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"unreadCount":{"type":"number"}},"required":["notifications","pagination","unreadCount"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get unread notification count > Returns the number of unread notifications for the authenticated user. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.notification.getUnreadCount":{"get":{"description":"Returns the number of unread notifications for the authenticated user.","summary":"Get unread notification count","tags":["notifications"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"unreadCount","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"unreadCount":{"type":"number"}},"required":["unreadCount"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Mark notifications as read > Marks one or more notifications as read by ID. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.notification.markRead":{"post":{"description":"Marks one or more notifications as read by ID.","summary":"Mark notifications as read","tags":["notifications"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"markRead","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"notificationIds":{"type":"array","items":{"type":"string"}}},"required":["notificationIds"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"markedCount":{"type":"number"}},"required":["markedCount"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Mark all notifications as read > Marks all of the authenticated user's notifications as read. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.notification.markAllRead":{"post":{"description":"Marks all of the authenticated user's notifications as read.","summary":"Mark all notifications as read","tags":["notifications"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"markAllRead","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"markedCount":{"type":"number"}},"required":["markedCount"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` # Connections ## Get connections for a URL > Returns connections where the given URL is the source or target, optionally filtered by direction and type. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.connection.getForUrl":{"get":{"description":"Returns connections where the given URL is the source or target, optionally filtered by direction and type.","summary":"Get connections for a URL","tags":["connections"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","updatedAt"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["forward","backward","both"]}},{"name":"connectionTypes","in":"query","schema":{"type":"array","items":{"type":"string","enum":["SUPPORTS","OPPOSES","ADDRESSES","HELPFUL","LEADS_TO","RELATED","SUPPLEMENT","EXPLAINER","SAME_AS","REFERENCES"]}}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"connectionsForUrl","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"type":"object","properties":{"connection":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"note":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"curator":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"required":["id","createdAt","updatedAt","curator"]},"source":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]},"target":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"required":["connection","source","target"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortBy":{"type":"string","enum":["createdAt","updatedAt"]},"sortOrder":{"type":"string","enum":["asc","desc"]}},"required":["sortBy","sortOrder"]}},"required":["connections","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Create a connection > Creates a typed link between two URLs with an optional note. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.connection.create":{"post":{"description":"Creates a typed link between two URLs with an optional note.","summary":"Create a connection","tags":["connections"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"createConnection","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"sourceType":{"type":"string","enum":["URL","CARD"]},"sourceValue":{"type":"string"},"targetType":{"type":"string","enum":["URL","CARD"]},"targetValue":{"type":"string"},"connectionType":{"type":"string","enum":["SUPPORTS","OPPOSES","ADDRESSES","HELPFUL","LEADS_TO","RELATED","SUPPLEMENT","EXPLAINER","SAME_AS","REFERENCES"]},"note":{"type":"string"}},"required":["sourceType","sourceValue","targetType","targetValue"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string"}},"required":["connectionId"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## List a user's connections > Returns a paginated list of connections created by a user, identified by handle or DID. Filterable by connection type. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.connection.listByUser":{"get":{"description":"Returns a paginated list of connections created by a user, identified by handle or DID. Filterable by connection type.","summary":"List a user's connections","tags":["connections"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","updatedAt"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"name":"connectionTypes","in":"query","schema":{"type":"array","items":{"type":"string","enum":["SUPPORTS","OPPOSES","ADDRESSES","HELPFUL","LEADS_TO","RELATED","SUPPLEMENT","EXPLAINER","SAME_AS","REFERENCES"]}}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"connectionsByUser","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"type":"object","properties":{"connection":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"note":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"curator":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"required":["id","createdAt","updatedAt","curator"]},"source":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]},"target":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"required":["connection","source","target"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]},"sorting":{"type":"object","properties":{"sortBy":{"type":"string","enum":["createdAt","updatedAt"]},"sortOrder":{"type":"string","enum":["asc","desc"]}},"required":["sortBy","sortOrder"]}},"required":["connections","pagination","sorting"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Update a connection > Updates the type, note, or direction of an existing connection. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.connection.update":{"post":{"description":"Updates the type, note, or direction of an existing connection.","summary":"Update a connection","tags":["connections"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"updateConnection","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string"},"connectionType":{"type":"string","enum":["SUPPORTS","OPPOSES","ADDRESSES","HELPFUL","LEADS_TO","RELATED","SUPPLEMENT","EXPLAINER","SAME_AS","REFERENCES"]},"note":{"type":"string"},"removeNote":{"type":"boolean"},"swap":{"type":"boolean"}},"required":["connectionId"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string"}},"required":["connectionId"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Delete a connection > Permanently deletes a connection owned by the authenticated user. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.connection.delete":{"post":{"description":"Permanently deletes a connection owned by the authenticated user.","summary":"Delete a connection","tags":["connections"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"deleteConnection","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string"}},"required":["connectionId"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string"}},"required":["connectionId"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` # Search ## Find similar URLs > Returns URLs semantically similar to a given URL using vector similarity search. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.search.getSimilarUrls":{"get":{"description":"Returns URLs semantically similar to a given URL using vector similarity search.","summary":"Find similar URLs","tags":["search"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string"}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"name":"threshold","in":"query","schema":{"type":"number","nullable":true}},{"name":"urlType","in":"query","schema":{"type":"string","enum":["article","link","book","research","audio","video","social","event","software"]}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"similarUrls","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["urls","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Semantic search > Returns URLs matching a natural-language query using vector search, optionally scoped to a user and filtered by type. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.search.semantic":{"get":{"description":"Returns URLs matching a natural-language query using vector search, optionally scoped to a user and filtered by type.","summary":"Semantic search","tags":["search"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"sortBy","in":"query","schema":{"type":"string"}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"query","in":"query","required":true,"schema":{"type":"string"}},{"name":"threshold","in":"query","schema":{"type":"number","nullable":true}},{"name":"urlType","in":"query","schema":{"type":"string","enum":["article","link","book","research","audio","video","social","event","software"]}},{"name":"identifier","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"semantic","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["urls","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Search AT Protocol accounts > Searches for AT Protocol user accounts by handle or display name. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.search.getAccounts":{"get":{"description":"Searches for AT Protocol user accounts by handle or display name.","summary":"Search AT Protocol accounts","tags":["search"],"parameters":[{"name":"term","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"atProtoAccounts","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"cursor":{"type":"string"},"actors":{"type":"array","items":{"type":"object","properties":{"did":{"type":"string"},"handle":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"avatar":{"type":"string"},"associated":{"type":"object","properties":{"chat":{"type":"object","properties":{"allowIncoming":{"type":"string","enum":["all","none","following"]}},"required":["allowIncoming"]}}},"indexedAt":{"type":"string"},"createdAt":{"type":"string"},"viewer":{"type":"object","properties":{"muted":{"type":"boolean"},"blockedBy":{"type":"boolean"},"blocking":{"type":"string"},"following":{"type":"string"},"followedBy":{"type":"string"}}},"labels":{"type":"array","items":{"nullable":true}},"verification":{"nullable":true},"status":{"nullable":true}},"required":["did","handle"]}}},"required":["actors"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` # Tags ## List recent tags > Returns recently used #tags for autocomplete. When authenticated, returns the user's recent tags, falling back to recent tags across Semble. Pass \`q\` to prefix-filter. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.tag.list":{"get":{"description":"Returns recently used #tags for autocomplete. When authenticated, returns the user's recent tags, falling back to recent tags across Semble. Pass `q` to prefix-filter.","summary":"List recent tags","tags":["tags"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"getTags","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string"},"lastUsed":{"type":"string"}},"required":["tag","lastUsed"]}}},"required":["tags"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get items with a tag > Returns a paginated, reverse-chronological list of cards, connections, or collections whose note or description contains the given #tag. Filter by \`itemType\` (default card) and optionally by \`user\` (handle or DID). ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.tag.getItems":{"get":{"description":"Returns a paginated, reverse-chronological list of cards, connections, or collections whose note or description contains the given #tag. Filter by `itemType` (default card) and optionally by `user` (handle or DID).","summary":"Get items with a tag","tags":["tags"],"parameters":[{"name":"tag","in":"query","required":true,"schema":{"type":"string"}},{"name":"itemType","in":"query","schema":{"type":"string","enum":["card","connection","collection"]}},{"name":"user","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"taggedItems","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"string"},"itemType":{"type":"string","enum":["card","connection","collection"]},"items":{"type":"array","items":{"discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["card"]},"card":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]}},"required":["type","card"]},{"type":"object","properties":{"type":{"type":"string","enum":["connection"]},"connection":{"type":"object","properties":{"connection":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"note":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"curator":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"required":["id","createdAt","updatedAt","curator"]},"source":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]},"target":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"required":["connection","source","target"]}},"required":["type","connection"]},{"type":"object","properties":{"type":{"type":"string","enum":["collection"]},"collection":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"required":["type","collection"]}]}},"cards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["URL"]},"url":{"type":"string"},"uri":{"type":"string"},"cardContent":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"libraryCount":{"type":"number"},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"note":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}},"required":["id","text"]}},"required":["id","type","url","cardContent","libraryCount","urlLibraryCount","createdAt","updatedAt","author"]}},"connections":{"type":"array","items":{"type":"object","properties":{"connection":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"note":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"curator":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"required":["id","createdAt","updatedAt","curator"]},"source":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]},"target":{"type":"object","properties":{"url":{"type":"string"},"metadata":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"publishedDate":{"type":"string"},"siteName":{"type":"string"},"imageUrl":{"type":"string"},"type":{"type":"string"},"retrievedAt":{"type":"string"},"doi":{"type":"string"},"isbn":{"type":"string"}},"required":["url"]},"urlLibraryCount":{"type":"number"},"urlInLibrary":{"type":"boolean"},"urlConnectionCount":{"type":"number"},"urlIsConnected":{"type":"boolean"}},"required":["url","metadata","urlLibraryCount"]}},"required":["connection","source","target"]}},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["tag","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` # Graph ## Follow a user or collection > Follows a target user or collection on behalf of the authenticated user. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.follow":{"post":{"description":"Follows a target user or collection on behalf of the authenticated user.","summary":"Follow a user or collection","tags":["graph"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"followTarget","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string"},"targetType":{"type":"string","enum":["USER","COLLECTION"]}},"required":["targetId","targetType"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"followId":{"type":"string"}},"required":["followId"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Unfollow a user or collection > Removes a follow relationship between the authenticated user and a target. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.unfollow":{"post":{"description":"Removes a follow relationship between the authenticated user and a target.","summary":"Unfollow a user or collection","tags":["graph"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"unfollowTarget","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string"},"targetType":{"type":"string","enum":["USER","COLLECTION"]}},"required":["targetId","targetType"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## List users a user follows > Returns users followed by the specified account, identified by handle or DID. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowing":{"get":{"description":"Returns users followed by the specified account, identified by handle or DID.","summary":"List users a user follows","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"followingUsers","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["users","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## List a user's followers > Returns users who follow the specified account, identified by handle or DID. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowers":{"get":{"description":"Returns users who follow the specified account, identified by handle or DID.","summary":"List a user's followers","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"userFollowers","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["users","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## List collections a user follows > Returns collections followed by the specified account, identified by handle or DID. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowingCollections":{"get":{"description":"Returns collections followed by the specified account, identified by handle or DID.","summary":"List collections a user follows","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"followingCollections","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["collections","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get following count > Returns the number of users a given account follows. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowingCount":{"get":{"description":"Returns the number of users a given account follows.","summary":"Get following count","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"followingCount","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"}},"required":["count"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get follower count > Returns the number of followers for a given account. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowersCount":{"get":{"description":"Returns the number of followers for a given account.","summary":"Get follower count","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"userFollowersCount","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"}},"required":["count"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Get following collections count > Returns the number of collections a given account follows. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowingCollectionsCount":{"get":{"description":"Returns the number of collections a given account follows.","summary":"Get following collections count","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"followingCollectionsCount","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"}},"required":["count"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Subscribe to a user or collection > Marks an existing follow as subscribed for the authenticated user. Requires that the user is already following the target. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.subscribe":{"post":{"description":"Marks an existing follow as subscribed for the authenticated user. Requires that the user is already following the target.","summary":"Subscribe to a user or collection","tags":["graph"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"subscribeToTarget","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string"},"targetType":{"type":"string","enum":["USER","COLLECTION"]},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}}},"required":["targetId","targetType"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"followId":{"type":"string"},"subscribedAt":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}}},"required":["followId","subscribedAt","scopes"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Unsubscribe from a user or collection > Clears the subscription flag on an existing follow. Idempotent. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.unsubscribe":{"post":{"description":"Clears the subscription flag on an existing follow. Idempotent.","summary":"Unsubscribe from a user or collection","tags":["graph"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"unsubscribeFromTarget","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string"},"targetType":{"type":"string","enum":["USER","COLLECTION"]}},"required":["targetId","targetType"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## Update the scopes of an existing subscription > Replaces the scope set on a subscription. Requires the caller to already be subscribed to the target. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.updateSubscription":{"post":{"description":"Replaces the scope set on a subscription. Requires the caller to already be subscribed to the target.","summary":"Update the scopes of an existing subscription","tags":["graph"],"parameters":[{"$ref":"#/components/parameters/SembleClient"}],"operationId":"updateSubscription","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string"},"targetType":{"type":"string","enum":["USER","COLLECTION"]},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]},"minItems":1}},"required":["targetId","targetType","scopes"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"followId":{"type":"string"},"subscribedAt":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}}},"required":["followId","subscribedAt","scopes"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` ## List my subscriptions > Returns the authenticated user's subscribed users and collections, ordered by subscribedAt DESC. ```json {"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getSubscriptions":{"get":{"description":"Returns the authenticated user's subscribed users and collections, ordered by subscribedAt DESC.","summary":"List my subscriptions","tags":["graph"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"targetType","in":"query","schema":{"type":"string","enum":["USER","COLLECTION"]}},{"$ref":"#/components/parameters/SembleClient"}],"operationId":"getMySubscriptions","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["USER"]},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"subscribedAt":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}}},"required":["type","user","subscribedAt","scopes"]},{"type":"object","properties":{"type":{"type":"string","enum":["COLLECTION"]},"collection":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]},"subscribedAt":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}}},"required":["type","collection","subscribedAt","scopes"]}]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["items","pagination"]}}}}}}}},"components":{"parameters":{"SembleClient":{"name":"X-Semble-Client","in":"header","required":false,"description":"A short identifier for your integration (e.g. `my-plugin`, `mcp`). Please set this if you are building an integration β€” it helps Semble understand which tools people use. Values are lowercased before being recorded, so `MyPlugin` and `myplugin` are the same client. After lowercasing the value must match `^[a-z0-9][a-z0-9_-]{0,31}$`; values that do not are ignored, and the client is inferred from the auth method instead.","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"}}}}} ``` # Models # Semble MCP Connect your agent to Semble's MCP server. ## What Can You Do? The Semble MCP server lets you interact with Semble through you AI agent in a conversational way. You can ask things like:\ \- "What's been happening in my network recently?"\ \- "Go through all my uncollected cards and suggest collections to add them to."\ \- "who are the top curators on the future of open social? Are there any collections I should subscribe to?"\ \ If anything interesting comes up, you can take actions directly in the chat, save cards, follow collections, build connections, and anything else you can do in the app. ## Connecting Your Agent to Semble MCP Every Semble MCP connection uses the same three pieces of info: | Setting | Value | | --------------- | --------------------------- | | **Server URL** | `https://api.semble.so/mcp` | | **Transport** | Streamable HTTP (stateless) | | **Auth header** | `X-API-Key: sk_...` | Get your API key at [semble.so/settings/api-keys](https://semble.so/settings/api-keys). > **OAuth-only clients** (Claude Desktop, ChatGPT) cannot use API-key auth directly. See their specific sections below β€” they require either a bridge or an OAuth layer. *** ### Claude Code (Plugin) The Semble Claude Code plugin handles API key storage in your OS keychain and includes skills for deep research and activity digests. **Via marketplace:** ``` /plugin marketplace add https://raw.githubusercontent.com/cosmik-network/semble-claude-plugin/main/marketplace/marketplace.json /plugin install semble ``` You'll be prompted for your Semble API key on enable. It's stored in your OS keychain and sent as the `X-API-Key` header β€” never written to disk in plaintext. **Manual config** (`.mcp.json`, if you prefer not to use the plugin): ```json { "mcpServers": { "semble": { "type": "streamableHttp", "url": "https://api.semble.so/mcp", "headers": { "X-API-Key": "sk_your_key_here" } } } } ``` > **Skills** (semble-getting-started, semble-deep-research, semble-activity-digest) are only available through the plugin install, not the manual config. *** ### Claude Desktop (Desktop Extension) Claude Desktop's Custom Connectors only support OAuth β€” it cannot send API-key headers to a remote server directly. The Semble desktop extension works around this by running a thin local bridge (`mcp-remote`) that injects your key. 1. Download `semble.mcpb` from the [latest release](https://github.com/cosmik-network/semble-claude-plugin/releases). 2. Double-click it β€” Claude Desktop opens an install dialog. 3. Enter your Semble API key when prompted (stored in your OS keychain). The extension forwards requests to `https://api.semble.so/mcp` with your key injected as the `X-API-Key` header. > Skills are a Claude Code feature and are not available in Claude Desktop. *** ### Cursor **Config file:** `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project) Add via UI: **Settings β†’ Tools & MCP β†’ New MCP Server**, or create the file manually. ```json { "mcpServers": { "semble": { "url": "https://api.semble.so/mcp", "headers": { "X-API-Key": "sk_your_key_here" } } } } ``` Restart Cursor after editing the config. *** ### Windsurf (Codeium) **Config file:** `~/.codeium/windsurf/mcp_config.json` (global only β€” no per-project support) ```json { "mcpServers": { "semble": { "serverUrl": "https://api.semble.so/mcp", "headers": { "X-API-Key": "sk_your_key_here" } } } } ``` Windsurf supports environment variable interpolation, so you can write `"X-API-Key": "${SEMBLE_API_KEY}"` instead of hardcoding the key. > **Gotcha:** Windsurf uses `serverUrl` (not `url`) for remote Streamable HTTP servers. *** ### Gemini CLI **Config file:** `~/.gemini/settings.json` (global) or `.gemini/settings.json` (per-project) ```json { "mcpServers": { "semble": { "type": "http", "url": "https://api.semble.so/mcp", "headers": { "X-API-Key": "sk_your_key_here" } } } } ``` **Via CLI command** (alternative to editing JSON): ```bash gemini mcp add -t http semble https://api.semble.so/mcp --header "X-API-Key: sk_your_key_here" ``` Restart Gemini CLI after adding the config. *** ### Zed **Config file:** `~/.config/zed/settings.json` Add via UI: **Settings β†’ AI β†’ MCP Servers β†’ Add Server β†’ Add Remote Server**. ```json { "context_servers": { "semble": { "url": "https://api.semble.so/mcp", "headers": { "X-API-Key": "sk_your_key_here" } } } } ``` > **Note:** Zed uses `context_servers` as the top-level key, not `mcpServers`. *** ### VS Code (GitHub Copilot) **Config file:** `.vscode/mcp.json` (workspace) or user profile `mcp.json` ```json { "inputs": [ { "type": "promptString", "id": "semble-api-key", "description": "Semble API Key", "password": true } ], "servers": { "semble": { "type": "http", "url": "https://api.semble.so/mcp", "headers": { "X-API-Key": "${input:semble-api-key}" } } } } ``` VS Code uses an `inputs` section to reference secrets without hardcoding them β€” it prompts for the value on first use and stores it securely. > **Note:** VS Code uses `"servers"` (not `"mcpServers"`) as the top-level key. *** ### ChatGPT (OpenAI) ChatGPT requires **OAuth** for remote MCP servers β€” it does not support API-key auth via headers. To connect directly, you'd need to implement the MCP OAuth authorization spec on your server. Then users would: 1. Enable Developer Mode: **Settings β†’ Connected Data β†’ Developer mode β†’ Create custom MCP connectors**. 2. Go to **Settings β†’ Connectors β†’ Create**. 3. Enter `https://api.semble.so/mcp` as the server URL. 4. ChatGPT follows the OAuth flow. Until OAuth is implemented, ChatGPT users cannot connect directly. This is the same limitation your Claude Desktop `.mcpb` bridge solves for that client. *** ### Any Other stdio-Only Client (mcp-remote bridge) For any client that only supports local `stdio` servers (no remote HTTP support), use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a bridge: ```json { "mcpServers": { "semble": { "command": "npx", "args": [ "mcp-remote", "https://api.semble.so/mcp", "--header", "X-API-Key: sk_your_key_here" ] } } } ``` This is the same approach the Claude Desktop extension uses internally. *** ### Quick Reference | Client | Config file | URL field | Auth method | Notes | | -------------------- | ------------------------------------- | ---------------------- | -------------------- | -------------------------------------- | | **Claude Code** | `.mcp.json` or plugin | `url` | `X-API-Key` header | Plugin recommended (keychain + skills) | | **Claude Desktop** | N/A (`.mcpb` install) | N/A | Bridge injects key | OAuth-only; use desktop extension | | **Cursor** | `~/.cursor/mcp.json` | `url` | `headers` object | Restart after editing | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | `serverUrl` | `headers` object | Use `serverUrl`, not `url` | | **Gemini CLI** | `~/.gemini/settings.json` | `url` + `type: "http"` | `headers` object | Or use `gemini mcp add` CLI | | **Zed** | `~/.config/zed/settings.json` | `url` | `headers` object | Key is `context_servers` | | **VS Code** | `.vscode/mcp.json` | `url` + `type: "http"` | `headers` + `inputs` | Key is `servers` | | **ChatGPT** | N/A (UI only) | N/A | OAuth required | Needs OAuth impl on server | | **Any stdio client** | Client-specific | N/A | `mcp-remote` bridge | `npx mcp-remote` as command | The main gotchas across clients are the different top-level key names (`mcpServers` vs `servers` vs `context_servers`) and the URL field name (`url` vs `serverUrl`). The auth pattern β€” a `headers` object with `X-API-Key: sk_...` β€” is consistent across all coding-agent clients that support remote HTTP. # Agent Skills for Semble give your agent access to various skill that help it interact with the Semble MCP server. These skill can be found [here](https://github.com/cosmik-network/semble-claude-plugin/tree/main/skills), or listed below: ## Getting Started ``` --- name: semble-getting-started description: Orientation for working with Semble β€” the core concepts (cards, collections, connections, libraries), how the MCP tools map to them, and the conventions Claude should follow. Activate at the start of any Semble task, or when the user asks what Semble is or what they can do with it. --- # Working with Semble Semble is a network for saving, connecting, and discovering URLs β€” built on the AT Protocol. Think of it as a shared, typed knowledge graph layered over the web. This skill orients you before you act; the `semble-deep-research` and `semble-activity-digest` skills cover specific workflows. ## Core concepts - **Card** β€” the atomic unit. A **URL card** represents a saved link; a **note card** is a markdown note attached to a URL. Cards have IDs. A URL can be saved by many users, each as their own card. - **Library** β€” a user's personal set of saved cards. "Saving" a URL adds a card to _your_ library. - **Collection** β€” a named, ordered group of URL cards. `OPEN` collections let others contribute; `CLOSED` ones don't. - **Connection** β€” a _typed, directional_ relationship between two things (URLs or cards): `SUPPORTS`, `OPPOSES`, `ADDRESSES`, `HELPFUL`, `LEADS_TO`, `RELATED`, `SUPPLEMENT`, `EXPLAINER`. This is the discourse-graph layer. Read `semble://connection-types` for exact semantics before asserting a specific type. - **Follow vs. Subscribe** β€” _following_ a user or collection drives your following-feed. _Subscribing_ drives notifications, at `CARD` / `CONNECTION` / `COLLECTION_SAVED` granularity. A subscription is an enhancement to a follow (must follow a user before subscribing to them). ## Identifiers - Users are addressed by **handle or DID** (the `identifier` param). - Cards, collections, and connections are addressed by **ID**. - Collections can also be addressed by **handle + record key** (their AT URI) via `get_collection_by_aturi`. - Many read tools accept either a **URL** or an ID β€” check each tool's schema. ## Tool map (what to reach for) **Read a single thing** - A URL you have in mind β†’ `get_url_metadata` (add `includeStats: true`), then `get_card_network_context` for the full picture (savers, collections, notes, connections in one call). - A specific card / collection β†’ `get_card`, `get_collection`. - A person β†’ `get_account_profile` (others) or `get_my_profile` (self). **Search / discover** - Your own library β†’ `search_library`. The whole network by keyword β†’ `search_network`. - Conceptual / natural-language β†’ `semantic_search`. "More like this URL" β†’ `find_similar_urls`. - Collections β†’ `search_collections`. People β†’ `search_accounts`. - Recent activity β†’ `get_global_feed`, `get_following_feed`. **Write (always confirm intent first β€” see below)** - Save a URL β†’ `save_card` (can attach a note + add to collections in one call). - Relate two things β†’ `connect_cards`. - Collections β†’ `create_collection`, `update_collection`, add/remove cards via `update_card_associations`. - Social β†’ `follow` / `subscribe` (and their inverses). ## Conventions to follow 1. **Confirm before writing.** Any create/update/delete (`save_card`, `connect_cards`, `create_collection`, `delete_*`, `follow`, `subscribe`, mark-read) changes the user's account. State exactly what you're about to do and get a clear go-ahead unless the user already gave an explicit, specific instruction. Treat every `delete_*` and `remove` tool as destructive and irreversible. 2. **Orient before you save.** Before saving a URL, it's usually worth a `get_library_status` (do they already have it?) and a quick `get_url_metadata`/`get_card_network_context` so you can save it into the right collections and reference existing notes/connections. 3. **Paginate deliberately.** List/search tools default to `limit: 10`, `page: 1`. Raise the limit or page through when the user wants breadth β€” don't silently stop at the first page and imply it's complete. Say when there's more. 4. **Prefer coarse tools for overviews.** When the user wants "the whole picture" of a URL, one `get_card_network_context` beats five separate calls. 5. **Attribute discovery with `viaCardId`.** When you save a URL you found _through_ another card, pass `viaCardId` β€” it credits the source and drives their notifications. 6. **Suggesting actions is your job, not a tool's.** After gathering data, reason over it and propose concrete next steps (follow this curator, connect these two papers as `SUPPORTS`, add this to that collection). There is no "suggest" tool β€” the suggestions come from you, and every proposed write still needs confirmation. ``` ## Activity Digest ``` --- name: semble-activity-digest description: Summarize what's happening on Semble β€” synthesize the global and following feeds, notifications, and recent collection activity into a digest, then suggest concrete follow-up actions (connections to make, people to follow, cards to save). Activate when the user asks "what's happening on Semble", "catch me up", "any updates", "what did I miss", or wants a digest of their feeds and notifications. --- # Semble Activity Digest Turn raw feed and notification data into a concise, useful digest plus suggested actions. Read `semble-getting-started` first if you haven't. Decide scope from the user's ask β€” a quick "anything new?" is lighter than a "catch me up on the week". ## Gather Pull from the relevant sources in parallel where you can: 1. **Notifications** β€” `get_unread_notification_count` first (cheap; tells you if there's anything). Then `get_notifications` (use `unreadOnly: true` for "what's new"). Types include `USER_ADDED_YOUR_CARD`, `SUBSCRIBED_USER_ADDED_CARD`, `USER_FOLLOWED_YOU`. These are the most personal and usually lead the digest. 2. **Following feed** β€” `get_following_feed`: activity from people the user follows. Activities are `CARD_COLLECTED` or `CONNECTION_CREATED`. This is the signal-rich feed. 3. **Global feed** β€” `get_global_feed`: broader network activity, for discovery beyond their circle. Include a modest slice; don't let it drown the personal items. Filter by `urlType` or `source` if the user has a focus. 4. **Optional deeper context** β€” if a collection or URL keeps recurring in the feeds, pull `get_collection` or `get_card_network_context` to explain _why_ it's active. Page back far enough to cover the window the user asked about (use `beforeActivityId` as a cursor for feeds). If you cap the window, say so β€” don't imply completeness you didn't check. ## Synthesize Don't replay the raw list. Cluster and interpret: - **Lead with the personal** β€” notifications that need or reward a response (someone saved your card, followed you, a subscribed user posted). - **Group by theme, not by timestamp** β€” "three people in your network engaged with AI-safety papers", "your collection _X_ got two new contributions" reads better than a reverse-chronological dump. - **Surface convergence** β€” the same URL, collection, or person recurring across feeds is the story. Call it out. - **Note who's active** β€” curators (in-network or not) who are producing good material right now. - **Keep it scannable** β€” short sections, concrete names and IDs, no filler. Length should match how much actually happened. ## Suggested actions Close with specific, grouped, ready-on-confirmation suggestions drawn from the digest: - **Respond** β€” reciprocate a follow, thank/subscribe to someone who added your card, mark notifications read (`mark_notifications_read` / `mark_all_notifications_read`). - **Connect** β€” the highest-value move: when the feed shows two related items (e.g. a new card that `SUPPORTS` or `OPPOSES` something the user already has), propose the typed connection with direction and type stated. - **Save** β€” feed URLs worth adding to the user's library; suggest the collection, check `get_library_status` first, and pass `viaCardId` for attribution to where you saw it. - **Follow / Subscribe** β€” recurring active curators or lively collections worth tracking; make the follow-vs-subscribe call for them. State each action concretely enough to execute, but don't execute β€” confirm first. The digest is the read; the actions are the offer. ``` ## Deep Research ``` --- name: semble-deep-research description: Multi-step research over the Semble network β€” run several complementary searches, crawl mutual collections and typed connections, evaluate results, track curators and collections worth following, and end with concrete suggested actions. Activate when the user asks to research, deeply explore, or map a topic in Semble, or wants to know "what's on Semble about X" beyond a single lookup. --- # Deep Research on Semble A single search rarely answers a real research question. This skill is a strategy for iterative, judgment-driven exploration of the Semble graph β€” _you_ decide the depth and branching per query; the steps below are a default, not a script to run blindly. Read `semble-getting-started` first if you haven't. ## The loop Work in rounds. After each round, decide whether you have enough or should branch further. ### 1. Cast a wide first net Run **complementary** searches, not one β€” they surface different things: - `search_network` (keyword) β€” exact-term matches across everyone's cards. - `semantic_search` (natural language) β€” conceptually related content the keywords miss. Start with a low/no `threshold`; tighten only if results are noisy. - `search_collections` β€” someone may have already curated this topic. A strong collection is often the best single find. - `search_accounts` β€” is there a person who _is_ the topic? Their library and connections become seeds. Dedupe across these by URL/card ID. Note the overlap β€” a URL surfaced by several searches is a strong signal. ### 2. Deepen on the strongest hits For the most promising URLs, get the full picture with `get_card_network_context` (metadata + stats + savers + collections + notes + connections in one call). From each, extract branch points: - **Connections** β†’ follow typed edges with `get_url_connections`. An `EXPLAINER` or `SUPPORTS` edge points to the next thing worth reading. Respect direction (`forward`/`backward`/`both`). - **Collections** β†’ open promising ones with `get_collection`; a good collection yields a whole cluster of vetted cards at once. - **Savers & note-writers** β†’ the people repeatedly appearing around good content are curators worth tracking. - **Similarity** β†’ `find_similar_urls` on a keystone URL to pull in semantically adjacent material the graph doesn't yet link. ### 3. Crawl mutuals and clusters Look for **convergence**, the highest-value signal in a graph: - URLs that appear across multiple good collections. - Users who both saved the keystone URLs _and_ curate relevant collections (`list_user_collections`, `list_contributed_collections`). - Dense connection neighborhoods β€” a URL with many typed edges is a hub. Expand a round or two along these, then stop. Don't crawl exhaustively; crawl toward convergence. ### 4. Evaluate, don't just collect As you go, judge results rather than dumping them: - **Relevance** β€” does it actually address the question, or just share keywords? - **Authority** β€” how many libraries saved it? Is it in curated collections? Do notes engage substantively? - **Role in the graph** β€” is it a hub, a leaf, a contrarian (`OPPOSES` edges)? Contrarian nodes are often the most useful. Drop weak hits early so later rounds don't inherit noise. ## Track as you go Keep a running tally across rounds (in your reasoning, surfaced in the final report): - **Key findings** β€” the URLs/cards that actually answer the question, with why each matters and its evidence (save count, collections, notes). - **Curators to follow/subscribe** β€” people who repeatedly surface good material. Note _why_ and whether follow (feed) or subscribe (notifications) fits. - **Collections to follow** β€” curated clusters worth ongoing attention. - **Open threads** β€” promising branches you didn't fully chase, so the user can direct a next round. ## Deliver: findings + suggested actions End every research session with two parts. **1. Synthesis.** A structured summary of what the network holds on the topic β€” the key findings, how they relate (agree/oppose/build-on), where the clusters and gaps are. Cite cards/collections/users by name and ID so the user (and you) can act on them. **2. Suggested actions.** Concrete, specific, and grouped β€” each ready to execute _on confirmation_: - **Save** β€” URLs found that aren't in the user's library yet (check with `get_library_status`); suggest which collection each belongs in, and pass `viaCardId` for attribution. - **Connect** β€” typed connections the research revealed but that don't exist yet ("paper A `SUPPORTS` paper B", "this post `OPPOSES` that one"). Propose the type and direction explicitly. - **Collect** β€” a new collection to hold the cluster you found, or existing cards to add to one. - **Contribute** if any open collections were discovered along the way, suggest to the user that they contribute relevant URLs to them (this is the same as adding a card to a collection, just that the collection is someone else's). - **Follow / Subscribe** β€” the curators and collections from your tally, with the follow-vs-subscribe choice made for them (does the user want to be notified about activity or just have it show up in a following feed?). Never execute writes as part of research. Gather, synthesize, propose β€” then let the user pick. This division is deliberate: the traversal and the judgment are yours; the commitment is theirs. ```