> For the complete documentation index, see [llms.txt](https://docs.cosmik.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cosmik.network/semble-api/cards.md).

# 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":[],"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"]}}}}}}}}}
```

## 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":[],"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"]}}}}}}}}}
```

## 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"}}],"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"]}}}}}}}}}
```

## 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}}],"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"]}},"required":["metadata"]}}}}}}}}}
```

## 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"}}],"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"]}}}}}}}}}}}}
```

## 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"}}],"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"]}}}}}}}}}
```

## 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"}}],"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"]}}}}}}}}}
```

## 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"]}}],"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"]}}}}}}}}}
```

## 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"}}],"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"]}}}}}}}}}
```

## 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":[],"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"]}}}}}}}}}
```

## 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":[],"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"]}}}}}}}}}
```

## 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"}}],"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"]}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cosmik.network/semble-api/cards.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.