huggingface-api

Hugging Face Hub API

Overview

The Hugging Face Hub is the largest open-source ML ecosystem, hosting over 1 million models, 200,000+ datasets, and 400,000+ Spaces (demo apps). The Hub API at https://huggingface.co/api provides programmatic access to search, discover, and retrieve metadata for all public resources without authentication.

For academic researchers, the Hub API enables systematic model selection for benchmarking, dataset discovery for experiments, tracking community adoption metrics (downloads, likes), and building reproducible ML pipelines that reference specific model revisions by SHA.

Authentication

Read endpoints require no authentication. All search and metadata queries work without a token.

For write operations (uploading models, creating repos), set a User Access Token:

export HF_TOKEN="hf_..."
# Pass via header:
curl -H "Authorization: Bearer $HF_TOKEN" https://huggingface.co/api/...

Generate tokens at: https://huggingface.co/settings/tokens

Core Endpoints

Search Models

GET https://huggingface.co/api/models?search={query}&limit={n}&sort={field}&direction={-1|1}

Parameters: search (query string), limit (max results), sort (field: downloads, likes, lastModified, trending), direction (-1 descending, 1 ascending), filter (pipeline tag like text-classification), author (org/user filter), library (e.g. transformers, pytorch)

Example -- top 2 models for "bert" by downloads:

curl -s "https://huggingface.co/api/models?search=bert&limit=2&sort=downloads&direction=-1"

[
  {
    "id": "google-bert/bert-base-uncased",
    "likes": 2587,
    "downloads": 71053483,
    "pipeline_tag": "fill-mask",
    "library_name": "transformers",
    "tags": ["transformers","pytorch","tf","jax","bert","fill-mask","en",
             "dataset:bookcorpus","dataset:wikipedia","arxiv:1810.04805",
             "license:apache-2.0"]
  },
  {
    "id": "google-bert/bert-base-multilingual-uncased",
    "likes": 153,
    "downloads": 5017183,
    "pipeline_tag": "fill-mask",
    "library_name": "transformers"
  }
]