From 3ec445171504d4d7efca94ba0f5d3b332facb804 Mon Sep 17 00:00:00 2001
From: Lucain <lucainp@gmail.com>
Date: Tue, 28 Nov 2023 09:13:17 +0100
Subject: [PATCH] Document `GET /api/collections` endpoint (#1137)

* Document GET /api/collections endpoint

* Update docs/hub/api.md

Co-authored-by: Sylvestre Bouchot <Kakulukian@users.noreply.github.com>

* Apply suggestions from code review

* dot

* feedback

---------

Co-authored-by: Sylvestre Bouchot <Kakulukian@users.noreply.github.com>
---
 docs/hub/api.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/hub/api.md b/docs/hub/api.md
index abe857bcc..d64b27b13 100644
--- 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.