Hugging Face 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 repos. We offer a wrapper Python library, huggingface_hub, that allows easy access to these endpoints. We also provide a webhook to receive real-time incremental info about models. Enjoy!

Endpoints table

Endpoint Description huggingface_hub root methods Payload
/api/models
GET
Get information from all models in the Hub. You can specify additional parameters to have more specific results.
- filter: Filter based on tags, such as text-classification or spacy.
- sort: Property to use when sorting.
- direction: Direction in which to sort.
- 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.
list_models() params= { "filter":"filter", "full":"full", "sort": "sort", "direction": "direction", "limit": "limit", "config": "config" }
/api/models/{repo_id}
/api/models/{repo_id}/revision/{revision}
GET
Get all information for a specific model. model_info(repo_id, revision) headers = { "authorization" : "Bearer $token" }
/api/datasets
GET
Get information from all datasets in the Hub. You can specify additional parameters to have more specific results.
- filter: Filter based on tags, such as task_categories:text-classification or languages:en.
- sort: Property to use when sorting.
- direction: Direction in which to sort.
- limit: Limit the number of datasets fetched.
- full: Whether to fetch most dataset data, such as all tags, the files, etc.
list_datasets() params= { "filter":"filter", "full":"full", "sort": "sort", "direction": "direction", "limit": "limit" }
/api/datasets/{repo_id}
/api/datasets/{repo_id}/revision/{revision}
GET
Get all information for a specific dataset.
- full: Whether to fetch most dataset data, such as all tags, the files, etc.
dataset_info(repo_id, revision) headers = { "authorization" : "Bearer $token", "full" : "full" }
/api/repos/ls
GET
Get list of all stored files for user or organization. list_repos_objs(token, organization) headers = { "authorization" : "Bearer $token" }
params= { "organization":"organization"}
/api/repos/create
POST
Create a repository. It's a model repo by default.
- type: Type of repo (datasets or spaces; model by default).
- name: Name of repo.
- organization: Name of organization. -
- private: Whether the repo is private.
create_repo() headers = { authorization : "Bearer $token" }
json= {"type":"type", "name":"name", "organization":"organization", "private":"private"}
/api/repos/delete
DELETE
Delete a repository. It's a model repo by default.
- type: Type of repo (datasets or spaces; model by default).
- name: Name of repo.
- organization: Name of organization.
delete_repo() headers = { "authorization" : "Bearer $token" }
json= {"type":"type", "name":"name", "organization":"organization"}
/api/repos/{type}/{repo_id}/settings
PUT
Update repo visibility. update_repo_visibility() headers = { "authorization" : "Bearer $token" }
json= {"private":"private"}
/api/{type}/{repo_id}/
upload/{revision}/{path_in_repo}
POST
Upload a file to a specific repository. upload_file() headers = { "authorization" : "Bearer $token" }
"data"="bytestream"
/api/login
POST
Login user and obtain authentication token. login(username, password) json = { "username" : "username", "password": "password" }
/api/whoami
GET
Get username and organizations the user belongs to. whoami(token) headers = { "authorization" : "Bearer $token" }
/api/logout
POST
Log out user. logout(token) headers = { "authorization" : "Bearer $token" }

Webhook

If you ever need to programmatically get notified about all the changes/additions to model repositories on the Hugging Face Hub, you can subscribe to the Hugging Face Hub webhook.

When you're subscribed – meaning you sent us a URL on your side that you want us to ping – we will call it over HTTP with the following payload:

{ "add": "user/model_id" }
# or
{ "update": "organization/model_id" }
# or
{ "remove": "user/model_id" }

✉️ Contact us at website at huggingface.co if you would like to subscribe to the webhook.