Document GET /api/collections endpoint (#1137)

* Document GET /api/collections endpoint * Update docs/hub/api.md Co-authored-by: Sylvestre Bouchot <[email protected]> * Apply suggestions from code review * dot * feedback --------- Co-authored-by: Sylvestre Bouchot <[email protected]>
huggingface · Nov 28, 2023 · 3ec4451 · 3ec4451
1 parent 71bbe11
commit 3ec4451
Showing 1 changed file with 27 additions and 0 deletions.
diff --git a/docs/hub/api.md b/docs/hub/api.md
@@ -288,6 +288,33 @@ Return information about a collection.
 
 This is equivalent to `huggingface_hub.get_collection()`.
 
+### GET /api/collections
+
+List collections from the Hub, based on some criteria. The supported parameters are:
+- `owner` (string): filter collections created by a specific user or organization.
+- `item` (string): filter collections containing a specific item. Value must be the item_type and item_id concatenated. Example: `"models/teknium/OpenHermes-2.5-Mistral-7B"`, `"datasets/squad"` or `"papers/2311.12983"`.
+- `sort` (string): sort the returned collections. Supported values are `"lastModified"`, `"trending"` (default) and `"upvotes"`.
+- `limit` (int): maximum number (100) of collections per page.
+- `q` (string): filter based on substrings for titles & descriptions.
+
+If no parameter is set, all collections are returned.
+
+The returned result is paginated. To get all collections, you must follow the
+The response is paginated. To get all collections, you must follow the [`Link` header](https://docs.github.com/en/rest/guides/using-pagination-in-the-rest-api?apiVersion=2022-11-28#link-header).
+
+Payload:
+
+```js
+params = {
+    "owner": "TheBloke",
+    "item": "models/teknium/OpenHermes-2.5-Mistral-7B",
+    "sort": "lastUpdated",
+    "limit" : 1,
+}
+```
+
+This is equivalent to `huggingface_hub.list_collections()`.
+
 ### PATCH /api/collections/{namespace}/{slug}-{id}
 
 Update the metadata of a collection on the Hub. You can't add or modify the items of the collection with this method. All fields of the payload are optional.