Search public models through the Hugging Face models API (huggingface.co/api/models). This is the public catalog, not a private Hub namespace. Send a keyword such as bert or llama, a models page URL, or the full pagination.next URL from a previous response. The response is { results, pagination }.
Model ids look like google-bert/bert-base-uncased. Pass results[].id to /v2/huggingface/model.
GET and POST take the same query.
GET https://api.piloterr.com/v2/huggingface/search?query=bert
The first card for bert is google-bert/bert-base-uncased, pipeline fill-mask, library transformers. Its likes and downloads match /v2/huggingface/model for that id. pagination.next is a cursor URL on huggingface.co/api/models. Send that whole URL back as query to read the following page.
| Parameter |
Required |
Example |
query |
yes |
bert |
query is required. A keyword becomes search on the models API with a page size of 20. A https://huggingface.co/models URL is accepted when it has search, q, or cursor. A https://huggingface.co/api/models URL, including pagination.next, is passed through. Any other host returns 400.
A keyword request sets pagination.page to 1, pagination.per_page to the number of models returned (20 when the page is full), and pagination.total_results and pagination.total_pages to null. Hugging Face does not print a page count. pagination.next is the rel="next" link, or null when that link is absent.
Page 2 of bert is the pagination.next URL from page 1. On that call pagination.page is null, because a cursor URL has no page number. The ids on page 2 are different from page 1, and next is another cursor URL while further pages exist. next is null only when the models API sends no next link. Do not build a page=2 URL yourself. Pass the cursor you received.
Ids are unique on a page. They use the owner/name form.
| Field |
Type |
Meaning |
results[].id |
string |
Model id, owner/name |
results[].url |
string |
Model page, https://huggingface.co/ plus the id |
results[].pipeline_tag |
string or null |
Task, such as fill-mask |
results[].library_name |
string or null |
Library, such as transformers |
results[].likes |
number or null |
Likes |
results[].downloads |
number or null |
Downloads |
results[].trending_score |
number or null |
Trending score |
results[].private |
boolean or null |
Private flag |
results[].tags |
array |
Tags from the models API |
results[].created_at |
string or null |
Creation time |
pagination.page |
integer or null |
1 on a keyword search. null when query is a cursor URL |
pagination.per_page |
integer or null |
Models on this page |
pagination.total_results |
null |
Not provided by the models API |
pagination.total_pages |
null |
Not provided by the models API |
pagination.next |
string or null |
Cursor URL, or null on the last page |
- Find
google-bert/bert-base-uncased from the keyword bert and keep the id for the model call.
- Follow
pagination.next once to read the next 20 bert models, and stop when next is null.
- Sort the first page by
downloads before choosing a fill-mask model to open.
| Code |
Meaning |
400 |
Empty query, or a URL outside huggingface.co |
401 |
Missing API key |
404 |
The payload was not a model list |
500 |
The fetch failed |
Hugging Face Model
