# Cards

## Add a URL to library

> Saves a URL as a 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 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"}},"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

> Updates the URL and URL type associations for a 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.updateUrlAssociations":{"post":{"description":"Updates the URL and URL type associations for a card.","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"}},"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 cards

> Returns a paginated list of URL cards 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.listMine":{"get":{"description":"Returns a paginated list of URL cards in the authenticated user's library.","summary":"List my library 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"}},{"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}}],"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"},"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

> Fetches title, description, and other metadata for 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.getUrlMetadata":{"get":{"description":"Fetches title, description, and other metadata for a given URL.","summary":"Get URL metadata","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"]}}}}}}}}}
```

## Get URL library status

> Returns whether a URL is already saved 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.getLibraryStatus":{"get":{"description":"Returns whether a URL is already saved in the authenticated user's library.","summary":"Get URL library status","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"},"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"},"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"},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}}}}}}}}}}}}
```

## Get libraries containing a URL

> Returns users who have saved a given URL to their 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.getLibrariesForUrl":{"get":{"description":"Returns users who have saved a given URL to their library.","summary":"Get libraries containing 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"}},{"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"},"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"},"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 note cards for a URL

> Returns all note cards that are attached 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 all note cards that are attached to a given URL.","summary":"Get note cards 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"}},{"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"},"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 card titles 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 card titles 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"}},{"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"},"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"},"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"},"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"},"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"]}}}}}}}}}
```

## Get libraries for a card

> Returns users who have saved a specific card to their 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.getLibraries":{"get":{"description":"Returns users who have saved a specific card to their library.","summary":"Get libraries for a card","tags":["cards"],"parameters":[{"name":"cardId","in":"query","required":true,"schema":{"type":"string"}}],"operationId":"cardLibraries","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"cardId":{"type":"string"},"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"},"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"]}},"totalCount":{"type":"number"}},"required":["cardId","users","totalCount"]}}}}}}}}}
```

## Update a note card

> Updates the text content of a note 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 text content of a note card.","summary":"Update a note 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 library cards

> Returns a paginated list of URL cards in a user's library, 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.card.listByUser":{"get":{"description":"Returns a paginated list of URL cards in a user's library, identified by handle or DID.","summary":"List a user's library 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"}},{"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}}],"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"},"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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.