Cards

Add a URL to library

post

Saves a URL as a URL card in the authenticated user's library.

Body

application/json

urlstringRequired

notestringOptional

collectionIdsstring[]Optional

viaCardIdstringOptional

The ID of the card that led to saving this URL. If included, the author of the viaCard will be notified.

Responses

200

200

application/json

urlCardIdstringRequired

noteCardIdstringOptional

post/network.cosmik.card.addUrl

HTTPcURLJavaScriptPython

POST /xrpc/network.cosmik.card.addUrl HTTP/1.1
Host: api.semble.so
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "url": "text",
  "note": "text",
  "collectionIds": [
    "text"
  ],
  "viaCardId": "text"
}

200

200

{
  "urlCardId": "text",
  "noteCardId": "text"
}

Update URL card associations

post

Add or remove the card to/from collections. Add a note to the URL card or update the existing note.

Body

application/json

cardIdstringRequired

notestringOptional

addToCollectionsstring[]Optional

removeFromCollectionsstring[]Optional

viaCardIdstringOptional

The ID of the card that led to saving this URL. If included, the author of the viaCard will be notified.

Responses

200

200

application/json

urlCardIdstringRequired

noteCardIdstringOptional

addedToCollectionsstring[]Required

removedFromCollectionsstring[]Required

post/network.cosmik.card.updateUrlAssociations

HTTPcURLJavaScriptPython

POST /xrpc/network.cosmik.card.updateUrlAssociations HTTP/1.1
Host: api.semble.so
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "cardId": "text",
  "note": "text",
  "addToCollections": [
    "text"
  ],
  "removeFromCollections": [
    "text"
  ],
  "viaCardId": "text"
}

200

200

{
  "urlCardId": "text",
  "noteCardId": "text",
  "addedToCollections": [
    "text"
  ],
  "removedFromCollections": [
    "text"
  ]
}

List my library URL cards

get

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

Query parameters

pagenumber · nullableOptional

limitnumber · nullableOptional

sortBystring · enumOptionalPossible values:

sortOrderstring · enumOptionalPossible values:

urlTypestring · enumOptionalPossible values:

uncollectedboolean · nullableOptional

searchTextstringOptional

Responses

200

200

application/json

get/network.cosmik.card.listMine

HTTPcURLJavaScriptPython

GET /xrpc/network.cosmik.card.listMine HTTP/1.1
Host: api.semble.so
Accept: */*

200

200

{
  "cards": [
    {
      "id": "text",
      "type": "URL",
      "url": "text",
      "uri": "text",
      "cardContent": {
        "url": "text",
        "title": "text",
        "description": "text",
        "author": "text",
        "publishedDate": "text",
        "siteName": "text",
        "imageUrl": "text",
        "type": "text",
        "retrievedAt": "text",
        "doi": "text",
        "isbn": "text"
      },
      "libraryCount": 1,
      "urlLibraryCount": 1,
      "urlInLibrary": true,
      "urlConnectionCount": 1,
      "urlIsConnected": true,
      "createdAt": "text",
      "updatedAt": "text",
      "author": {
        "id": "text",
        "name": "text",
        "handle": "text",
        "avatarUrl": "text",
        "bannerUrl": "text",
        "description": "text",
        "isFollowing": true,
        "isSubscribed": true,
        "subscriptionScopes": [
          "CARD"
        ],
        "followsYou": true,
        "followerCount": 1,
        "followingCount": 1,
        "followedCollectionsCount": 1,
        "urlCardCount": 1,
        "collectionCount": 1,
        "connectionCount": 1,
        "connectionsByType": {
          "total": 1,
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "labels": [
          {
            "$type": "com.atproto.label.defs#label",
            "ver": 1,
            "src": "text",
            "uri": "text",
            "cid": "text",
            "val": "text",
            "neg": true,
            "cts": "text",
            "exp": "text",
            "sig": null
          }
        ]
      },
      "note": {
        "id": "text",
        "text": "text"
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalCount": 1,
    "hasMore": true,
    "limit": 1
  },
  "sorting": {
    "sortOrder": "asc",
    "sortBy": "createdAt"
  }
}

Get URL metadata and optional Semble stats

get

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.

Query parameters

urlstringRequired

includeStatsboolean · nullableOptional

Responses

200

200

application/json

get/network.cosmik.card.getUrlMetadata

HTTPcURLJavaScriptPython

GET /xrpc/network.cosmik.card.getUrlMetadata?url=text HTTP/1.1
Host: api.semble.so
Accept: */*

200

200

{
  "metadata": {
    "url": "text",
    "title": "text",
    "description": "text",
    "author": "text",
    "publishedDate": "text",
    "siteName": "text",
    "imageUrl": "text",
    "type": "text",
    "retrievedAt": "text",
    "doi": "text",
    "isbn": "text"
  },
  "stats": {
    "libraryCount": 1,
    "noteCount": 1,
    "collectionCount": 1,
    "connections": {
      "all": {
        "total": 1,
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "incoming": {
        "total": 1,
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "outgoing": {
        "total": 1,
        "ANY_ADDITIONAL_PROPERTY": 1
      }
    }
  }
}

Check if a given URL has been saved to your library

get

Returns whether a URL is already saved in the authenticated user's library, along with all collections the user added it to.

Query parameters

urlstringRequired

Responses

200

200

application/json

get/network.cosmik.card.getLibraryStatus

HTTPcURLJavaScriptPython

GET /xrpc/network.cosmik.card.getLibraryStatus?url=text HTTP/1.1
Host: api.semble.so
Accept: */*

200

200

{
  "card": {
    "id": "text",
    "type": "URL",
    "url": "text",
    "uri": "text",
    "cardContent": {
      "url": "text",
      "title": "text",
      "description": "text",
      "author": "text",
      "publishedDate": "text",
      "siteName": "text",
      "imageUrl": "text",
      "type": "text",
      "retrievedAt": "text",
      "doi": "text",
      "isbn": "text"
    },
    "libraryCount": 1,
    "urlLibraryCount": 1,
    "urlInLibrary": true,
    "urlConnectionCount": 1,
    "urlIsConnected": true,
    "createdAt": "text",
    "updatedAt": "text",
    "author": {
      "id": "text",
      "name": "text",
      "handle": "text",
      "avatarUrl": "text",
      "bannerUrl": "text",
      "description": "text",
      "isFollowing": true,
      "isSubscribed": true,
      "subscriptionScopes": [
        "CARD"
      ],
      "followsYou": true,
      "followerCount": 1,
      "followingCount": 1,
      "followedCollectionsCount": 1,
      "urlCardCount": 1,
      "collectionCount": 1,
      "connectionCount": 1,
      "connectionsByType": {
        "total": 1,
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "labels": [
        {
          "$type": "com.atproto.label.defs#label",
          "ver": 1,
          "src": "text",
          "uri": "text",
          "cid": "text",
          "val": "text",
          "neg": true,
          "cts": "text",
          "exp": "text",
          "sig": null
        }
      ]
    },
    "note": {
      "id": "text",
      "text": "text"
    }
  },
  "collections": [
    {
      "id": "text",
      "uri": "text",
      "name": "text",
      "author": {
        "id": "text",
        "name": "text",
        "handle": "text",
        "avatarUrl": "text",
        "bannerUrl": "text",
        "description": "text",
        "isFollowing": true,
        "isSubscribed": true,
        "subscriptionScopes": [
          "CARD"
        ],
        "followsYou": true,
        "followerCount": 1,
        "followingCount": 1,
        "followedCollectionsCount": 1,
        "urlCardCount": 1,
        "collectionCount": 1,
        "connectionCount": 1,
        "connectionsByType": {
          "total": 1,
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "labels": [
          {
            "$type": "com.atproto.label.defs#label",
            "ver": 1,
            "src": "text",
            "uri": "text",
            "cid": "text",
            "val": "text",
            "neg": true,
            "cts": "text",
            "exp": "text",
            "sig": null
          }
        ]
      },
      "description": "text",
      "accessType": "OPEN",
      "cardCount": 1,
      "createdAt": "text",
      "updatedAt": "text",
      "isFollowing": true,
      "isSubscribed": true,
      "subscriptionScopes": [
        "CARD"
      ],
      "followerCount": 1
    }
  ]
}

Get users who have saved a URL to their library

get

Returns a paginated list of users who have saved a given URL to their library, including the URL Card of each user.

Query parameters

pagenumber · nullableOptional

limitnumber · nullableOptional

sortBystring · enumOptionalPossible values:

sortOrderstring · enumOptionalPossible values:

urlstringRequired

Responses

200

200

application/json

get/network.cosmik.card.getLibrariesForUrl

HTTPcURLJavaScriptPython

GET /xrpc/network.cosmik.card.getLibrariesForUrl?url=text HTTP/1.1
Host: api.semble.so
Accept: */*

200

200

{
  "libraries": [
    {
      "user": {
        "id": "text",
        "name": "text",
        "handle": "text",
        "avatarUrl": "text",
        "bannerUrl": "text",
        "description": "text",
        "isFollowing": true,
        "isSubscribed": true,
        "subscriptionScopes": [
          "CARD"
        ],
        "followsYou": true,
        "followerCount": 1,
        "followingCount": 1,
        "followedCollectionsCount": 1,
        "urlCardCount": 1,
        "collectionCount": 1,
        "connectionCount": 1,
        "connectionsByType": {
          "total": 1,
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "labels": [
          {
            "$type": "com.atproto.label.defs#label",
            "ver": 1,
            "src": "text",
            "uri": "text",
            "cid": "text",
            "val": "text",
            "neg": true,
            "cts": "text",
            "exp": "text",
            "sig": null
          }
        ]
      },
      "card": {
        "id": "text",
        "type": "URL",
        "url": "text",
        "uri": "text",
        "cardContent": {
          "url": "text",
          "title": "text",
          "description": "text",
          "author": "text",
          "publishedDate": "text",
          "siteName": "text",
          "imageUrl": "text",
          "type": "text",
          "retrievedAt": "text",
          "doi": "text",
          "isbn": "text"
        },
        "libraryCount": 1,
        "urlLibraryCount": 1,
        "urlInLibrary": true,
        "urlConnectionCount": 1,
        "urlIsConnected": true,
        "createdAt": "text",
        "updatedAt": "text",
        "author": {
          "id": "text",
          "name": "text",
          "handle": "text",
          "avatarUrl": "text",
          "bannerUrl": "text",
          "description": "text",
          "isFollowing": true,
          "isSubscribed": true,
          "subscriptionScopes": [
            "CARD"
          ],
          "followsYou": true,
          "followerCount": 1,
          "followingCount": 1,
          "followedCollectionsCount": 1,
          "urlCardCount": 1,
          "collectionCount": 1,
          "connectionCount": 1,
          "connectionsByType": {
            "total": 1,
            "ANY_ADDITIONAL_PROPERTY": 1
          },
          "labels": [
            {
              "$type": "com.atproto.label.defs#label",
              "ver": 1,
              "src": "text",
              "uri": "text",
              "cid": "text",
              "val": "text",
              "neg": true,
              "cts": "text",
              "exp": "text",
              "sig": null
            }
          ]
        },
        "note": {
          "id": "text",
          "text": "text"
        }
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalCount": 1,
    "hasMore": true,
    "limit": 1
  },
  "sorting": {
    "sortOrder": "asc",
    "sortBy": "createdAt"
  }
}

Get notes for a URL

get

Returns a paginated list of all notes that are added to a given URL.

Query parameters

pagenumber · nullableOptional

limitnumber · nullableOptional

sortBystring · enumOptionalPossible values:

sortOrderstring · enumOptionalPossible values:

urlstringRequired

Responses

200

200

application/json

get/network.cosmik.card.getNoteCardsForUrl

HTTPcURLJavaScriptPython

GET /xrpc/network.cosmik.card.getNoteCardsForUrl?url=text HTTP/1.1
Host: api.semble.so
Accept: */*

200

200

{
  "notes": [
    {
      "id": "text",
      "note": "text",
      "author": {
        "id": "text",
        "name": "text",
        "handle": "text",
        "avatarUrl": "text",
        "bannerUrl": "text",
        "description": "text",
        "isFollowing": true,
        "isSubscribed": true,
        "subscriptionScopes": [
          "CARD"
        ],
        "followsYou": true,
        "followerCount": 1,
        "followingCount": 1,
        "followedCollectionsCount": 1,
        "urlCardCount": 1,
        "collectionCount": 1,
        "connectionCount": 1,
        "connectionsByType": {
          "total": 1,
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "labels": [
          {
            "$type": "com.atproto.label.defs#label",
            "ver": 1,
            "src": "text",
            "uri": "text",
            "cid": "text",
            "val": "text",
            "neg": true,
            "cts": "text",
            "exp": "text",
            "sig": null
          }
        ]
      },
      "createdAt": "text",
      "updatedAt": "text"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalCount": 1,
    "hasMore": true,
    "limit": 1
  },
  "sorting": {
    "sortOrder": "asc",
    "sortBy": "createdAt"
  }
}

Search cards

get

Full-text search across URL Cards titles, descriptions and URLs.

Query parameters

pagenumber · nullableOptional

limitnumber · nullableOptional

sortBystring · enumOptionalPossible values:

sortOrderstring · enumOptionalPossible values:

searchQuerystringRequired

urlTypestring · enumOptionalPossible values:

Responses

200

200

application/json

get/network.cosmik.card.search

HTTPcURLJavaScriptPython

GET /xrpc/network.cosmik.card.search?searchQuery=text HTTP/1.1
Host: api.semble.so
Accept: */*

200

200

{
  "urls": [
    {
      "url": "text",
      "metadata": {
        "url": "text",
        "title": "text",
        "description": "text",
        "author": "text",
        "publishedDate": "text",
        "siteName": "text",
        "imageUrl": "text",
        "type": "text",
        "retrievedAt": "text",
        "doi": "text",
        "isbn": "text"
      },
      "urlLibraryCount": 1,
      "urlInLibrary": true,
      "urlConnectionCount": 1,
      "urlIsConnected": true
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalCount": 1,
    "hasMore": true,
    "limit": 1
  },
  "sorting": {
    "sortOrder": "asc",
    "sortBy": "createdAt"
  }
}

Get a card by ID

get

Returns a card and its associated metadata by card ID.

Query parameters

cardIdstringRequired

Responses

200

200

application/json

idstringRequired

typestring · enumRequiredPossible values:

urlstringRequired

uristringOptional

libraryCountnumberRequired

urlLibraryCountnumberRequired

urlInLibrarybooleanOptional

urlConnectionCountnumberOptional

urlIsConnectedbooleanOptional

createdAtstringRequired

updatedAtstringRequired

get/network.cosmik.card.get

HTTPcURLJavaScriptPython

GET /xrpc/network.cosmik.card.get?cardId=text HTTP/1.1
Host: api.semble.so
Accept: */*

200

200

{
  "id": "text",
  "type": "URL",
  "url": "text",
  "uri": "text",
  "cardContent": {
    "url": "text",
    "title": "text",
    "description": "text",
    "author": "text",
    "publishedDate": "text",
    "siteName": "text",
    "imageUrl": "text",
    "type": "text",
    "retrievedAt": "text",
    "doi": "text",
    "isbn": "text"
  },
  "libraryCount": 1,
  "urlLibraryCount": 1,
  "urlInLibrary": true,
  "urlConnectionCount": 1,
  "urlIsConnected": true,
  "createdAt": "text",
  "updatedAt": "text",
  "author": {
    "id": "text",
    "name": "text",
    "handle": "text",
    "avatarUrl": "text",
    "bannerUrl": "text",
    "description": "text",
    "isFollowing": true,
    "isSubscribed": true,
    "subscriptionScopes": [
      "CARD"
    ],
    "followsYou": true,
    "followerCount": 1,
    "followingCount": 1,
    "followedCollectionsCount": 1,
    "urlCardCount": 1,
    "collectionCount": 1,
    "connectionCount": 1,
    "connectionsByType": {
      "total": 1,
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "labels": [
      {
        "$type": "com.atproto.label.defs#label",
        "ver": 1,
        "src": "text",
        "uri": "text",
        "cid": "text",
        "val": "text",
        "neg": true,
        "cts": "text",
        "exp": "text",
        "sig": null
      }
    ]
  },
  "note": {
    "id": "text",
    "text": "text"
  },
  "collections": [
    {
      "id": "text",
      "uri": "text",
      "name": "text",
      "author": {
        "id": "text",
        "name": "text",
        "handle": "text",
        "avatarUrl": "text",
        "bannerUrl": "text",
        "description": "text",
        "isFollowing": true,
        "isSubscribed": true,
        "subscriptionScopes": [
          "CARD"
        ],
        "followsYou": true,
        "followerCount": 1,
        "followingCount": 1,
        "followedCollectionsCount": 1,
        "urlCardCount": 1,
        "collectionCount": 1,
        "connectionCount": 1,
        "connectionsByType": {
          "total": 1,
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "labels": [
          {
            "$type": "com.atproto.label.defs#label",
            "ver": 1,
            "src": "text",
            "uri": "text",
            "cid": "text",
            "val": "text",
            "neg": true,
            "cts": "text",
            "exp": "text",
            "sig": null
          }
        ]
      },
      "description": "text",
      "accessType": "OPEN",
      "cardCount": 1,
      "createdAt": "text",
      "updatedAt": "text",
      "isFollowing": true,
      "isSubscribed": true,
      "subscriptionScopes": [
        "CARD"
      ],
      "followerCount": 1
    }
  ],
  "libraries": [
    {
      "id": "text",
      "name": "text",
      "handle": "text",
      "avatarUrl": "text",
      "bannerUrl": "text",
      "description": "text",
      "isFollowing": true,
      "isSubscribed": true,
      "subscriptionScopes": [
        "CARD"
      ],
      "followsYou": true,
      "followerCount": 1,
      "followingCount": 1,
      "followedCollectionsCount": 1,
      "urlCardCount": 1,
      "collectionCount": 1,
      "connectionCount": 1,
      "connectionsByType": {
        "total": 1,
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "labels": [
        {
          "$type": "com.atproto.label.defs#label",
          "ver": 1,
          "src": "text",
          "uri": "text",
          "cid": "text",
          "val": "text",
          "neg": true,
          "cts": "text",
          "exp": "text",
          "sig": null
        }
      ]
    }
  ]
}

Update a note added to a URL card

post

Updates the content of a note added to a URL card.

Body

application/json

cardIdstringRequired

notestringRequired

Responses

200

200

application/json

cardIdstringRequired

post/network.cosmik.card.updateNote

HTTPcURLJavaScriptPython

POST /xrpc/network.cosmik.card.updateNote HTTP/1.1
Host: api.semble.so
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "cardId": "text",
  "note": "text"
}

200

200

{
  "cardId": "text"
}

Remove a card from library

post

Removes a card from the authenticated user's library.

Body

application/json

cardIdstringRequired

Responses

200

200

application/json

cardIdstringRequired

post/network.cosmik.card.removeFromLibrary

HTTPcURLJavaScriptPython

POST /xrpc/network.cosmik.card.removeFromLibrary HTTP/1.1
Host: api.semble.so
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "cardId": "text"
}

200

200

{
  "cardId": "text"
}

List a user's URL cards

get

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

Query parameters

pagenumber · nullableOptional

limitnumber · nullableOptional

sortBystring · enumOptionalPossible values:

sortOrderstring · enumOptionalPossible values:

identifierstringRequired

urlTypestring · enumOptionalPossible values:

uncollectedboolean · nullableOptional

searchTextstringOptional

Responses

200

200

application/json

get/network.cosmik.card.listByUser

HTTPcURLJavaScriptPython

GET /xrpc/network.cosmik.card.listByUser?identifier=text HTTP/1.1
Host: api.semble.so
Accept: */*

200

200

{
  "cards": [
    {
      "id": "text",
      "type": "URL",
      "url": "text",
      "uri": "text",
      "cardContent": {
        "url": "text",
        "title": "text",
        "description": "text",
        "author": "text",
        "publishedDate": "text",
        "siteName": "text",
        "imageUrl": "text",
        "type": "text",
        "retrievedAt": "text",
        "doi": "text",
        "isbn": "text"
      },
      "libraryCount": 1,
      "urlLibraryCount": 1,
      "urlInLibrary": true,
      "urlConnectionCount": 1,
      "urlIsConnected": true,
      "createdAt": "text",
      "updatedAt": "text",
      "author": {
        "id": "text",
        "name": "text",
        "handle": "text",
        "avatarUrl": "text",
        "bannerUrl": "text",
        "description": "text",
        "isFollowing": true,
        "isSubscribed": true,
        "subscriptionScopes": [
          "CARD"
        ],
        "followsYou": true,
        "followerCount": 1,
        "followingCount": 1,
        "followedCollectionsCount": 1,
        "urlCardCount": 1,
        "collectionCount": 1,
        "connectionCount": 1,
        "connectionsByType": {
          "total": 1,
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "labels": [
          {
            "$type": "com.atproto.label.defs#label",
            "ver": 1,
            "src": "text",
            "uri": "text",
            "cid": "text",
            "val": "text",
            "neg": true,
            "cts": "text",
            "exp": "text",
            "sig": null
          }
        ]
      },
      "note": {
        "id": "text",
        "text": "text"
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalCount": 1,
    "hasMore": true,
    "limit": 1
  },
  "sorting": {
    "sortOrder": "asc",
    "sortBy": "createdAt"
  }
}