> 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":[{"$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}$"}}}}}
```


---

# 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.