canonical: https://jentic.com/apis/huggingface.co/huggingface # Hugging Face Hub API Jentic publishes the only available OpenAPI specification for the Hugging Face Hub API, keeping it validated and agent-ready. The Hugging Face Hub API is the management surface for everything on huggingface.co outside of model inference - repositories for models, datasets, and Spaces, plus collections, papers, organizations, jobs, inference endpoints, and user settings. Through it an integration can list and search the Hub, create or update repos, manage discussions and pull requests, run scheduled jobs, and configure notifications and webhooks. It is the API that wraps what the official huggingface_hub Python client exposes, in HTTP form. ## For AI agents Browse and manage Hugging Face Hub repos, datasets, Spaces, collections, jobs, and inference endpoints, with full discussion and webhook support. ## Scope Does not run model inference, host serving traffic, or train models - use for Hugging Face Hub repo, discussion, job, and account management only. ## Capabilities - List, search, and inspect models, datasets, and Spaces on the Hugging Face Hub - Create, rename, move, and delete repositories of any type on the Hub - Open, comment on, and merge discussions and pull requests against a repo - Run and schedule jobs against Hub-hosted compute and read their logs - Manage inference endpoints attached to a model repo - Configure account-level webhooks, notifications, and watch settings - Manage organization membership, billing, and SSH or API token credentials ## Use cases ### Programmatic Hub repo management Create, rename, and delete model and dataset repositories on the Hugging Face Hub from CI without going through the web UI. The API supports private repos, organization ownership, and revision-level operations so a release pipeline can push a new model artifact, tag the revision, and update the model card in one run. Example prompt: Call POST /api/repos/create with name, type='model', and private=true, then patch the model card via the repo's resolve endpoint. ### Hub search and discovery for agents Power agent-facing tooling that needs to find the right model, dataset, or Space on the Hugging Face Hub. The search and listing endpoints return paginated results filterable by tag, library, language, license, and downloads so an agent can shortlist candidates and inspect each repo's metadata before pulling the artifact. Example prompt: Call GET /api/models with filter=text-classification and library=transformers, then GET /api/models/{id} for each shortlisted repo to read its model card metadata. ### Discussion and pull request automation Triage discussions and pull requests across many Hub repositories from a single bot - surface stale issues, auto-comment on license-flagged uploads, or merge approved community contributions into model cards. The discussions endpoints expose the full thread including reactions and revision diffs so the bot can act on real context. Example prompt: List discussions on a repo, post a comment via the discussions API on each open PR older than 14 days, then merge the ones with maintainer approval. ### Scheduled jobs on Hub compute Run training, evaluation, or dataset preparation jobs against Hugging Face Hub compute on a schedule and stream the logs back into an observability tool. Scheduled job configuration, run listing, and per-run log retrieval are all exposed through the API so the orchestration layer does not need to scrape the UI. Example prompt: POST /api/scheduled-jobs with the job spec, then poll GET /api/jobs/{id}/logs to stream output back into the orchestrator. ### Agent-driven Hub workflows through Jentic An AI agent that builds a curated dataset of evaluation models uses Jentic to find the Hugging Face search and repo-create operations, loads their schemas, and runs them with a single Hugging Face token held in your Jentic One instance. The agent never holds the raw token in its prompt context. Example prompt: Through Jentic, search 'find Hugging Face models for text classification', load GET /api/models, execute it with filter='text-classification', then iterate to load each repo's metadata. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /api/models | List and search models | | GET | /api/datasets | List and search datasets | | GET | /api/spaces | List and search Spaces | | POST | /api/repos/create | Create a new repository of any type | | DELETE | /api/repos/delete | Delete an existing repository | | GET | /api/settings/webhooks | List configured webhooks | | POST | /api/settings/webhooks | Create a new webhook | | GET | /api/notifications | Read the notification feed | ## Key resources - **Models** — List, search, create, and inspect model repositories - **Datasets** — List, search, create, and inspect dataset repositories - **Spaces** — List, search, create, and inspect Spaces - **Organizations** — Manage organization membership, billing, and visibility - **Discussions** — Open, comment, and merge discussions and pull requests on repos - **Jobs** — Run, schedule, and inspect Hub compute jobs - **Settings** — Manage account-level webhooks, notifications, and watch lists ## Why Jentic - **Setup:** Wiring the Hugging Face Hub API by hand means holding a user access token, targeting huggingface.co, and paging listings of models, datasets, and spaces yourself. Through Jentic you install once, import the Hugging Face Hub API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** This API exposes repo actions through fixed endpoints where the target is named in the request body (/api/repos/create, /api/repos/delete), so limit the agent to the operations it needs, such as listing models or reading notifications. You choose the operations it may call, so creating or deleting a repo is not included unless you add it. - **Credential handling:** Your Hugging Face user access token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find Hugging Face models' or 'create a Hugging Face repo', and Jentic returns the matching Hub operation with its input schema, including filters and pagination cursors, so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **OpenAI** — Hosted-model platform with managed inference and fine-tuning instead of an open Hub of community artifacts - **Replicate** — Hosted inference platform for community models with simpler run-a-model semantics - **Cohere** — First-party hosted language and embedding models from a single vendor - **GitHub** — Source control for the training code that produces the artifacts pushed to Hugging Face ## FAQ ### Why is there no official OpenAPI spec for Hugging Face Hub API? Hugging Face does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Hugging Face Hub API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Hugging Face Hub API use? The Hub API uses Hugging Face user access tokens passed as a Bearer header. Through Jentic the token sits in your encrypted Jentic One instance and is injected at execution time so the agent never sees the raw token. ### Can I create a private model repository through this API? Yes. POST /api/repos/create accepts type='model' along with private=true and an optional organization owner, so the new repo is created with restricted visibility from the start. ### What are the rate limits for the Hugging Face Hub API? Hugging Face applies per-token rate limits that scale with the user's tier; Pro and enterprise tokens get substantially higher limits than free accounts. Authenticated calls always have higher quotas than unauthenticated ones, so always include the Bearer token. ### How do I search for models through Jentic? Search Jentic for 'find Hugging Face models', load the schema for GET /api/models, and execute it with filters like library, tag, or language. Jentic returns the parsed search results ready for the agent to iterate over. ### Does this API run model inference? No - model inference goes through the separate Hugging Face Inference API and Inference Endpoints. This Hub API manages the repositories, jobs, discussions, and account settings around models rather than running them. ### Can I configure webhooks for repo events? Yes. POST /api/settings/webhooks creates a webhook that fires on configured repo events, and the per-webhook endpoints let you pause, replay, or delete the webhook from code. ### Can I limit what my agent is allowed to do with the Hugging Face Hub API? Yes. Because you run Jentic One yourself, your own rules decide which Hub operations the agent may call, so you can allow read-only actions like GET /api/models or GET /api/notifications while withholding write operations. Since destructive actions such as /api/repos/create and /api/repos/delete name their target in the request body, they are only reachable if you explicitly add them to what the agent may use. The Hugging Face access token is held by your Jentic One instance and injected at execution time, so the agent never handles the raw credential.