> 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/graph.md).

# Graph

## Follow a user or collection

> Follows a target user or collection on behalf of the authenticated user.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.follow":{"post":{"description":"Follows a target user or collection on behalf of the authenticated user.","summary":"Follow a user or collection","tags":["graph"],"parameters":[],"operationId":"followTarget","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string"},"targetType":{"type":"string","enum":["USER","COLLECTION"]}},"required":["targetId","targetType"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"followId":{"type":"string"}},"required":["followId"]}}}}}}}}}
```

## Unfollow a user or collection

> Removes a follow relationship between the authenticated user and a target.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.unfollow":{"post":{"description":"Removes a follow relationship between the authenticated user and a target.","summary":"Unfollow a user or collection","tags":["graph"],"parameters":[],"operationId":"unfollowTarget","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string"},"targetType":{"type":"string","enum":["USER","COLLECTION"]}},"required":["targetId","targetType"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}}}}}}}
```

## List users a user follows

> Returns users followed by the specified account, identified by handle or DID.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowing":{"get":{"description":"Returns users followed by the specified account, identified by handle or DID.","summary":"List users a user follows","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}}],"operationId":"followingUsers","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["users","pagination"]}}}}}}}}}
```

## List a user's followers

> Returns users who follow the specified account, identified by handle or DID.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowers":{"get":{"description":"Returns users who follow the specified account, identified by handle or DID.","summary":"List a user's followers","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}}],"operationId":"userFollowers","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["users","pagination"]}}}}}}}}}
```

## List collections a user follows

> Returns collections followed by the specified account, identified by handle or DID.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowingCollections":{"get":{"description":"Returns collections followed by the specified account, identified by handle or DID.","summary":"List collections a user follows","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}}],"operationId":"followingCollections","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["collections","pagination"]}}}}}}}}}
```

## Get following count

> Returns the number of users a given account follows.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowingCount":{"get":{"description":"Returns the number of users a given account follows.","summary":"Get following count","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}}],"operationId":"followingCount","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"}},"required":["count"]}}}}}}}}}
```

## Get follower count

> Returns the number of followers for a given account.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowersCount":{"get":{"description":"Returns the number of followers for a given account.","summary":"Get follower count","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}}],"operationId":"userFollowersCount","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"}},"required":["count"]}}}}}}}}}
```

## Get following collections count

> Returns the number of collections a given account follows.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getFollowingCollectionsCount":{"get":{"description":"Returns the number of collections a given account follows.","summary":"Get following collections count","tags":["graph"],"parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"string"}}],"operationId":"followingCollectionsCount","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"}},"required":["count"]}}}}}}}}}
```

## Subscribe to a user or collection

> Marks an existing follow as subscribed for the authenticated user. Requires that the user is already following the target.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.subscribe":{"post":{"description":"Marks an existing follow as subscribed for the authenticated user. Requires that the user is already following the target.","summary":"Subscribe to a user or collection","tags":["graph"],"parameters":[],"operationId":"subscribeToTarget","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string"},"targetType":{"type":"string","enum":["USER","COLLECTION"]},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}}},"required":["targetId","targetType"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"followId":{"type":"string"},"subscribedAt":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}}},"required":["followId","subscribedAt","scopes"]}}}}}}}}}
```

## Unsubscribe from a user or collection

> Clears the subscription flag on an existing follow. Idempotent.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.unsubscribe":{"post":{"description":"Clears the subscription flag on an existing follow. Idempotent.","summary":"Unsubscribe from a user or collection","tags":["graph"],"parameters":[],"operationId":"unsubscribeFromTarget","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string"},"targetType":{"type":"string","enum":["USER","COLLECTION"]}},"required":["targetId","targetType"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}}}}}}}
```

## Update the scopes of an existing subscription

> Replaces the scope set on a subscription. Requires the caller to already be subscribed to the target.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.updateSubscription":{"post":{"description":"Replaces the scope set on a subscription. Requires the caller to already be subscribed to the target.","summary":"Update the scopes of an existing subscription","tags":["graph"],"parameters":[],"operationId":"updateSubscription","requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string"},"targetType":{"type":"string","enum":["USER","COLLECTION"]},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]},"minItems":1}},"required":["targetId","targetType","scopes"]}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"followId":{"type":"string"},"subscribedAt":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}}},"required":["followId","subscribedAt","scopes"]}}}}}}}}}
```

## List my subscriptions

> Returns the authenticated user's subscribed users and collections, ordered by subscribedAt DESC.

```json
{"openapi":"3.0.2","info":{"title":"Semble API","version":"1.0.0"},"servers":[{"url":"https://api.semble.so/xrpc"}],"paths":{"/network.cosmik.graph.getSubscriptions":{"get":{"description":"Returns the authenticated user's subscribed users and collections, ordered by subscribedAt DESC.","summary":"List my subscriptions","tags":["graph"],"parameters":[{"name":"page","in":"query","schema":{"type":"number","nullable":true}},{"name":"limit","in":"query","schema":{"type":"number","nullable":true}},{"name":"targetType","in":"query","schema":{"type":"string","enum":["USER","COLLECTION"]}}],"operationId":"getMySubscriptions","responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["USER"]},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"subscribedAt":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}}},"required":["type","user","subscribedAt","scopes"]},{"type":"object","properties":{"type":{"type":"string","enum":["COLLECTION"]},"collection":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"avatarUrl":{"type":"string"},"bannerUrl":{"type":"string"},"description":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followsYou":{"type":"boolean"},"followerCount":{"type":"number"},"followingCount":{"type":"number"},"followedCollectionsCount":{"type":"number"},"urlCardCount":{"type":"number"},"collectionCount":{"type":"number"},"connectionCount":{"type":"number"},"connectionsByType":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"],"additionalProperties":{"type":"number"}},"labels":{"type":"array","items":{"type":"object","properties":{"$type":{"type":"string","enum":["com.atproto.label.defs#label"]},"ver":{"type":"number"},"src":{"type":"string"},"uri":{"type":"string"},"cid":{"type":"string"},"val":{"type":"string"},"neg":{"type":"boolean"},"cts":{"type":"string"},"exp":{"type":"string"},"sig":{"nullable":true}},"required":["src","uri","val","cts"]}}},"required":["id","name","handle"]},"description":{"type":"string"},"accessType":{"type":"string","enum":["OPEN","CLOSED"]},"cardCount":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isFollowing":{"type":"boolean"},"isSubscribed":{"type":"boolean"},"subscriptionScopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}},"followerCount":{"type":"number"}},"required":["id","name","author","cardCount","createdAt","updatedAt"]},"subscribedAt":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["CARD","CONNECTION","COLLECTION_SAVED"]}}},"required":["type","collection","subscribedAt","scopes"]}]}},"pagination":{"type":"object","properties":{"currentPage":{"type":"number"},"totalPages":{"type":"number"},"totalCount":{"type":"number"},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["currentPage","totalPages","totalCount","hasMore","limit"]}},"required":["items","pagination"]}}}}}}}}}
```


---

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