Custom Connector
Hugging Face Connector
Global
The Hugging Face Connector enables seamless integration with the Hugging Face Hub, providing access to machine-learning models, datasets, applications (Spaces), papers, collections, and organization/resource-group management. Public resources need no authentication; write and admin actions use a Bearer token.
Overview
Integration Overview
This document provides a detailed guide for each integration action point, its purpose, configuration, and workflow support using the Hugging Face connector. The 44 endpoints are grouped below by resource area.
- Models. GET /api/models, /models-tags-by-type, /models/{repo_id}, and /models/{repo_id}/revision/{revision}.
- Datasets. GET /api/datasets (+ tags, {repo_id}, revision, croissant, and parquet at subset/split/shard levels).
- Spaces. GET /api/spaces, /spaces/{repo_id}, and /spaces/{repo_id}/revision/{revision}.
- Papers & collections. GET /api/daily_papers, /papers/{arxiv_id}, /arxiv/{arxiv_id}/repos; collections CRUD (GET/POST/PATCH/DELETE).
- Repositories. POST /api/repos/create, /repos/move, DELETE /repos/delete, PUT settings, and resource-group assignment.
- Organizations & resource groups. GET/POST/PATCH/DELETE resource groups, members, users, and settings.
- Identity. GET /api/whoami-v2 for authenticated user info.
Documentation
Detailed Integration Documentation
Models
| Actions | GET /api/models · /api/models-tags-by-type · /api/models/{repo_id} · /api/models/{repo_id}/revision/{revision} |
|---|---|
| Purpose | Lists models (with search/author/filter/sort/limit), lists all model tags, and retrieves a specific model or model revision. |
| Configuration | Configure the connector with the base URL (https://huggingface.co). Public reads need no auth; write/admin actions require a Bearer token. |
| Parameters | Optional (list): search; author; filter; sort (downloads/author/lastModified); direction (-1/1); limit; full; config. Required (detail): repo_id (and revision). |
| Output | Successful: JSON array or object of model metadata (id, name, author, tags). Failure: 400 / 500. |
| Workflow example | GET /api/models with search=bert and limit=10, then GET /api/models/bert-base-uncased for detail. |
Datasets
| Actions | GET /api/datasets (+ -tags-by-type, /{repo_id}, /revision/{revision}, /croissant, /parquet…) |
|---|---|
| Purpose | Lists datasets and tags, retrieves a dataset or revision, Croissant metadata, and Parquet files at subset / split / shard levels. |
| Configuration | Configure the connector with the base URL (https://huggingface.co). Public reads need no auth; write/admin actions require a Bearer token. |
| Parameters | Optional (list): search; author; filter; sort; direction; limit; full; config. Required (detail/parquet): repo_id (plus subset, split, and n for shards). |
| Output | Successful: JSON arrays/objects of dataset metadata, file lists, or a binary Parquet shard. Failure: 400 / 404 / 500. |
| Workflow example | GET /api/datasets/squad/parquet/default/train, then GET …/train/0.parquet to download a shard. |
Spaces
| Actions | GET /api/spaces · /api/spaces/{repo_id} · /api/spaces/{repo_id}/revision/{revision} |
|---|---|
| Purpose | Lists Spaces (with search/author/filter/sort/limit), and retrieves a specific Space or Space revision. |
| Configuration | Configure the connector with the base URL (https://huggingface.co). Public reads need no auth; write/admin actions require a Bearer token. |
| Parameters | Optional (list): search; author; filter; sort; direction; limit; full. Required (detail): repo_id (and revision). |
| Output | Successful: JSON array or object of Space metadata (id, name, author, tags). Failure: 400 / 404 / 500. |
| Workflow example | GET /api/spaces with search=gradio and limit=10 to build an application gallery. |
Papers & Collections
| Actions | GET /api/daily_papers · /papers/{arxiv_id} · /arxiv/{arxiv_id}/repos · collections GET/POST/PATCH/DELETE (+ items) |
|---|---|
| Purpose | Retrieves daily/curated papers, paper metadata, repos linked to a paper, and full CRUD over collections and their items. |
| Configuration | Configure the connector with the base URL (https://huggingface.co). Public reads need no auth; write/admin actions require a Bearer token. Collection writes require a Bearer token. |
| Parameters | Papers optional: date/month/week; arxiv_id (path). Collections: namespace, slug, id, item_id; POST/PATCH bodies (title, description, private, note, position, item). |
| Output | Successful: JSON papers/repos arrays, or collection objects and confirmation messages. Failure: 400 / 401 / 404 / 500. |
| Workflow example | GET /api/daily_papers?date=2025-05-31, then POST /api/collections to curate results. |
Repositories
| Actions | POST /api/repos/create · /repos/move · DELETE /repos/delete · PUT /repos/{repo_type}/{repo_id}/settings · POST /api/{repo_type}/{namespace}/{repo}/resource-group |
|---|---|
| Purpose | Creates, moves/renames, and deletes repositories; updates visibility settings; and assigns a repository to a resource group. |
| Configuration | Configure the connector with the base URL (https://huggingface.co). Public reads need no auth; write/admin actions require a Bearer token. All repository writes require a Bearer token. |
| Parameters | Required: name/repo_id; type (model/dataset/space) as applicable; Bearer token. Optional: organization; private; sdk (Spaces); fromRepo/toRepo (move); resourceGroupId. |
| Output | Successful: JSON with repository id/name/type or a confirmation message. Failure: 400 / 401 / 404 / 500. |
| Workflow example | POST /api/repos/create {name: my-model, type: model}, then PUT settings {private: true}. |
Organizations & Resource Groups
| Actions | GET/POST/PATCH/DELETE /api/organizations/{name}/resource-groups(…) · members · users · settings |
|---|---|
| Purpose | Lists organization members and resource groups, creates/updates/deletes resource groups, manages users and roles, and updates auto-join settings. |
| Configuration | Configure the connector with the base URL (https://huggingface.co). Public reads need no auth; write/admin actions require a Bearer token. All organization actions require a Bearer token. |
| Parameters | Required: name; resourceGroupId / username as applicable; Bearer token. Optional: description; users [{user, role}]; repos; autoJoin {enabled, role}; role (admin/write/read). |
| Output | Successful: JSON with resource-group or member objects and confirmation messages. Failure: 400 / 401 / 404 / 500. |
| Workflow example | POST /api/organizations/huggingface/resource-groups {name: ResearchGroup}, then add users with roles. |
Identity
| Action | GET /api/whoami-v2 |
|---|---|
| Purpose | Retrieves authenticated user information. |
| Configuration | Configure the connector with the base URL (https://huggingface.co). Public reads need no auth; write/admin actions require a Bearer token. Requires a Bearer token. |
| Parameters | Required: Authorization Bearer token; Accept header. |
| Output | Successful: JSON with username and a list of organizations. Failure: 400 / 401 / 500. |
| Workflow example | GET /api/whoami-v2 to display the authenticated user’s profile. |
Example Workflow: AI-Powered Application Development
| Collections | Create and manage collections with POST/PATCH /api/collections… |
|---|---|
| Repositories | Create, move, or delete repositories with POST /api/repos/create, /move, and DELETE /repos/delete. |
| Datasets & models | Fetch with GET /api/datasets and /api/models for integration into AI pipelines. |
| Orgs & research | Manage resource groups, and access papers and linked repos via GET /api/papers/{arxiv_id}. |
Use Case
A machine-learning research lab integrates the Hugging Face Connector with GCP to streamline access to models, datasets, and papers. Using GET /api/models and GET /api/datasets via huggingface.co, the lab retrieves resources like bert-base-uncased and squad; data is fetched in Parquet (GET /api/datasets/{repo_id}/parquet) and ingested into BigQuery for scalable experimentation. Metadata from GET /api/papers/{arxiv_id} enhances traceability, model versioning supports reproducibility, and repository assets are cataloged in Cloud Storage for rapid prototyping across NLP tasks.
Support
For technical support, contact custom-connectors-support@isolutions.sa.