# Hugging Face — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Discover and browse the most popular Hugging Face Spaces ranked by likes, trending score, or recent updates to find the best machine learning demos and tools for your needs. Filter through top-performing projects to quickly identify trending applications and highly-rated community contributions.

**Category:** Developer Tools | **Website:** [huggingface.co/](https://huggingface.co/) | **Docs:** [parse.bot/marketplace/8c59c63b-7661-4ff7-927a-f10054f8ca15/huggingface-co-api](https://parse.bot/marketplace/8c59c63b-7661-4ff7-927a-f10054f8ca15/huggingface-co-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/hugging-face/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### List top spaces

List Spaces ranked by the chosen sort criterion. Each Space includes its identifier, title, author, like count, SDK, tags, and timestamps. Results are returned as a single page; pass offset to advance manually. When sort is trendingScore, each item also carries its trending_score.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `direction` | string | No | Sort direction: -1 for descending, 1 for ascending. |
| `limit` | integer | No | Number of Spaces to return per page (1–100). |
| `offset` | integer | No | Number of items to skip for pagination. |
| `search` | string | No | Free-text filter applied to Space names and descriptions. Omit to return all Spaces. |
| `sort` | string | No | Ranking criterion for the returned list. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/hugging-face/list-top-spaces \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"direction":"<string>","limit":"<integer>","offset":"<integer>","search":"<string>","sort":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.