> For the complete documentation index, see [llms.txt](https://boinc-ai.gitbook.io/hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boinc-ai.gitbook.io/hub/hub-api-endpoints.md). # Hub API Endpoints ## Hub API Endpoints We have open endpoints that you can use to retrieve information from the Hub as well as perform certain actions such as creating model, dataset or Space repos. We offer a wrapper Python library, [`huggingface_hub`](https://github.com/huggingface/huggingface_hub), that allows easy access to these endpoints. We also provide [webhooks](https://huggingface.co/docs/hub/webhooks) to receive real-time incremental info about repos. Enjoy! The base URL for those endpoints below is `https://huggingface.co`. For example, to construct the `/api/models` call below, one can call the URL ### The Hub API Playground Want to try out our API? Try it out now on our [Playground](https://huggingface.co/spaces/enzostvs/hub-api-playground)! ![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/hub-api-playground.png) ### Repo listing API The following endpoints help get information about models, datasets, Spaces, and metrics stored on the Hub. #### GET /api/models Get information from all models in the Hub. The response is paginated, use the [`Link` header](https://docs.github.com/en/rest/guides/using-pagination-in-the-rest-api?apiVersion=2022-11-28#link-header) to get the next pages. You can specify additional parameters to have more specific results. * `search`: Filter based on substrings for repos and their usernames, such as `resnet` or `microsoft` * `author`: Filter models by an author or organization, such as `huggingface` or `microsoft` * `filter`: Filter based on tags, such as `text-classification` or `spacy`. * `sort`: Property to use when sorting, such as `downloads` or `author`. * `direction`: Direction in which to sort, such as `-1` for descending, and anything else for ascending. * `limit`: Limit the number of models fetched. * `full`: Whether to fetch most model data, such as all tags, the files, etc. * `config`: Whether to also fetch the repo config. Payload: Copied ``` params = { "search":"search", "author":"author", "filter":"filter", "sort":"sort", "direction":"direction", "limit":"limit", "full":"full", "config":"config" } ``` This is equivalent to `huggingface_hub.list_models()`. #### GET /api/models/{repo\_id} or /api/models/{repo\_id}/revision/{revision} Get all information for a specific model. This is equivalent to `huggingface_hub.model_info(repo_id, revision)`. #### GET /api/models-tags-by-type Gets all the available model tags hosted in the Hub. This is equivalent to `huggingface_hub.get_model_tags()`. #### GET /api/datasets Get information from all datasets in the Hub. The response is paginated, use the [`Link` header](https://docs.github.com/en/rest/guides/using-pagination-in-the-rest-api?apiVersion=2022-11-28#link-header) to get the next pages. You can specify additional parameters to have more specific results. * `search`: Filter based on substrings for repos and their usernames, such as `pets` or `microsoft` * `author`: Filter datasets by an author or organization, such as `huggingface` or `microsoft` * `filter`: Filter based on tags, such as `task_categories:text-classification` or `languages:en`. * `sort`: Property to use when sorting, such as `downloads` or `author`. * `direction`: Direction in which to sort, such as `-1` for descending, and anything else for ascending. * `limit`: Limit the number of datasets fetched. * `full`: Whether to fetch most dataset data, such as all tags, the files, etc. Payload: Copied ``` params = { "search":"search", "author":"author", "filter":"filter", "sort":"sort", "direction":"direction", "limit":"limit", "full":"full", "config":"config" } ``` This is equivalent to `huggingface_hub.list_datasets()`. #### GET /api/datasets/{repo\_id} or /api/datasets/{repo\_id}/revision/{revision} Get all information for a specific dataset. * `full`: Whether to fetch most dataset data, such as all tags, the files, etc. Payload: Copied ``` params = {"full": "full"} ``` This is equivalent to `huggingface_hub.dataset_info(repo_id, revision)`. #### GET /api/datasets/{repo\_id}/parquet Get the list of auto-converted parquet files. #### GET /api/datasets/{repo\_id}/parquet/{config}/{split}/{n}.parquet Get the nth shard of the auto-converted parquet files. #### GET /api/datasets-tags-by-type Gets all the available dataset tags hosted in the Hub. This is equivalent to `huggingface_hub.get_dataset_tags()`. #### GET /api/spaces Get information from all Spaces in the Hub. The response is paginated, use the [`Link` header](https://docs.github.com/en/rest/guides/using-pagination-in-the-rest-api?apiVersion=2022-11-28#link-header) to get the next pages. You can specify additional parameters to have more specific results. * `search`: Filter based on substrings for repos and their usernames, such as `resnet` or `microsoft` * `author`: Filter models by an author or organization, such as `huggingface` or `microsoft` * `filter`: Filter based on tags, such as `text-classification` or `spacy`. * `sort`: Property to use when sorting, such as `downloads` or `author`. * `direction`: Direction in which to sort, such as `-1` for descending, and anything else for ascending. * `limit`: Limit the number of models fetched. * `full`: Whether to fetch most model data, such as all tags, the files, etc. Payload: Copied ``` params = { "search":"search", "author":"author", "filter":"filter", "sort":"sort", "direction":"direction", "limit":"limit", "full":"full", "config":"config" } ``` This is equivalent to `huggingface_hub.list_spaces()`. #### GET /api/spaces/{repo\_id} or /api/spaces/{repo\_id}/revision/{revision} Get all information for a specific model. This is equivalent to `huggingface_hub.space_info(repo_id, revision)`. ### Repo API The following endpoints manage repository settings like creating and deleting a repository. #### POST /api/repos/create Create a repository. It’s a model repo by default. Parameters: * `type`: Type of repo (dataset or space; model by default). * `name`: Name of repo. * `organization`: Name of organization (optional). * `private`: Whether the repo is private. Payload: Copied ``` payload = { "type":"type", "name":"name", "organization": "organization", "private":"private" } ``` This is equivalent to `huggingface_hub.create_repo()`. #### DELETE /api/repos/delete Delete a repository. It’s a model repo by default. Parameters: * `type`: Type of repo (dataset or space; model by default). * `name`: Name of repo. * `organization`: Name of organization (optional). Payload: Copied ``` payload = { "type": "type", "name": "name", "organization": "organization", } ``` This is equivalent to `huggingface_hub.delete_repo()`. #### PUT /api/repos/{repo\_type}/{repo\_id}/settings Update repo visibility. Payload: Copied ``` payload = { "private": "private", } ``` This is equivalent to `huggingface_hub.update_repo_visibility()`. #### POST /api/repos/move Move a repository (rename within the same namespace or transfer from user to organization). Payload: Copied ``` payload = { "fromRepo" : "namespace/repo_name", "toRepo" : "namespace2/repo_name2" } ``` This is equivalent to `huggingface_hub.move_repo()`. ### User API The following endpoint gets information about a user. #### GET /api/whoami-v2 Get username and organizations the user belongs to. Payload: Copied ``` headers = { "authorization" : "Bearer $token" } ``` This is equivalent to `huggingface_hub.whoami()`. ### Collections API Use Collections to group repositories from the Hub (Models, Datasets, Spaces and Papers) on a dedicated page. You can learn more about it in the Collections [guide](https://huggingface.co/docs/hub/collections.md). Collections can also be managed using the Python client (see [guide](https://huggingface.co/docs/huggingface_hub/main/en/guides/collections)). #### POST /api/collections Create a new collection on the Hub with a title, a description (optional) and a first item (optional). An item is defined by a type (`model`, `dataset`, `space` or `paper`) and an id (repo\_id or paper\_id on the Hub). Payload: Copied ``` payload = { "title": "My cool models", "namespace": "username_or_org", "description": "Here is a shortlist of models I've trained.", "item" : { "type": "model", "id": "username/cool-model", } "private": false, } ``` This is equivalent to `huggingface_hub.create_collection()`. #### GET /api/collections/{namespace}/{slug}-{id} Return information about a collection. This is equivalent to `huggingface_hub.get_collection()`. #### 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. Payload: Copied ``` payload = { "title": "My cool models", "description": "Here is a shortlist of models I've trained.", "private": false, "position": 0, // position of the collection on your profile "theme": "green", } ``` This is equivalent to `huggingface_hub.update_collection_metadata()`. #### DELETE /api/collections/{namespace}/{slug}-{id} Return a collection. This is a non-revertible operation. A deleted collection cannot be restored. This is equivalent to `huggingface_hub.delete_collection()`. #### POST /api/collections/{namespace}/{slug}-{id}/item Add an item to a collection. An item is defined by a type (`model`, `dataset`, `space` or `paper`) and an id (repo\_id or paper\_id on the Hub). A note can also be attached to the item (optional). Payload: Copied ``` payload = { "item" : { "type": "model", "id": "username/cool-model", } "note": "Here is the model I trained on ...", } ``` This is equivalent to `huggingface_hub.add_collection_item()`. #### PATCH /api/collections/{namespace}/{slug}-{id}/items/{item\_id} Update an item in a collection. You must know the item object id which is different from the repo\_id/paper\_id provided when adding the item to the collection. The `item_id` can be retrieved by fetching the collection. You can update the note attached to the item or the position of the item in the collection. Both fields are optional. Copied ``` payload = { "position": 0, "note": "Here is the model I trained on ...", } ``` This is equivalent to `huggingface_hub.update_collection_item()`. #### DELETE /api/collections/{namespace}/{slug}-{id}/items/{item\_id} Remove an item from a collection. You must know the item object id which is different from the repo\_id/paper\_id provided when adding the item to the collection. The `item_id` can be retrieved by fetching the collection. This is equivalent to `huggingface_hub.delete_collection_item()`.