---
read_when:
    - API-clients bouwen
    - Eindpunten of schema's toevoegen
summary: Overzicht en conventies van de openbare REST API (v1).
x-i18n:
    generated_at: "2026-07-27T05:03:46Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 31b0051506912d2aa0d724ed7b6542e09ef16dc92998ddbdd3e379f783954436
    source_path: clawhub/api.md
    workflow: 16
---

# API v1

Basis: `https://clawhub.ai`

OpenAPI: `/api/v1/openapi.json`

## Hergebruik van de openbare catalogus

Je kunt boven op de openbare lees-API's van ClawHub een catalogus, directory of zoekinterface van derden bouwen. Openbare metadata en bestanden van Skills worden gepubliceerd volgens de licentieregels voor Skills van ClawHub, terwijl de API zelf snelheidslimieten heeft en verantwoord moet worden gebruikt.

Richtlijnen:

- Gebruik openbare leeseindpunten zoals `GET /api/v1/skills`, `GET /api/v1/search` en `GET /api/v1/skills/{slug}` voor catalogusvermeldingen.
- Cache reacties en respecteer `429`, `Retry-After` en headers voor snelheidslimieten in plaats van agressief te pollen.
- Link bij het weergeven van vermeldingen terug naar de canonieke URL van de ClawHub-skill, zodat gebruikers de bronvermelding in het register kunnen bekijken.
- Gebruik canonieke pagina-URL's in de vorm `https://clawhub.ai/<owner>/skills/<slug>`.
- Wek niet de indruk dat ClawHub de website van derden onderschrijft, verifieert of beheert.
- Spiegel geen verborgen, privé- of door moderatie geblokkeerde inhoud door openbare API-filters of authenticatiegrenzen te omzeilen.

## Authenticatie

- Openbaar lezen: geen token vereist.
- Schrijven + account: `Authorization: Bearer clh_...`.

## Snelheidslimieten

Authenticatiebewuste handhaving:

- Anonieme aanvragen: per IP.
- Geverifieerde aanvragen (geldig Bearer-token): per gebruikersbucket.
- Bij een ontbrekend/ongeldig token wordt teruggevallen op handhaving per IP.

- Lezen: 3000/min per IP, 12000/min per sleutel
- Schrijven: 300/min per IP, 3000/min per sleutel
- Downloaden: 1200/min per IP, 6000/min per sleutel

Headers: `X-RateLimit-Limit`, `X-RateLimit-Reset`, `RateLimit-Limit`, `RateLimit-Reset`;
`X-RateLimit-Remaining`, `RateLimit-Remaining` en `Retry-After` worden opgenomen bij `429`.

Semantiek:

- `X-RateLimit-Reset`: seconden sinds het Unix-tijdperk (absoluut tijdstip van reset)
- `RateLimit-Reset`: aantal seconden vertraging tot de reset
- `X-RateLimit-Remaining` / `RateLimit-Remaining`: exact resterend budget indien
  aanwezig; succesvolle gesharde aanvragen laten dit weg in plaats van een globale
  waarde bij benadering terug te geven
- `Retry-After`: aantal seconden dat moet worden gewacht bij `429`

Voorbeeld van `429`:

```http
HTTP/2 429
x-ratelimit-limit: 20
x-ratelimit-remaining: 0
x-ratelimit-reset: 1771404540
ratelimit-limit: 20
ratelimit-remaining: 0
ratelimit-reset: 34
retry-after: 34
```

Afhandeling door de client:

- Geef de voorkeur aan `Retry-After` indien aanwezig.
- Gebruik anders `RateLimit-Reset` of leid de vertraging af uit `X-RateLimit-Reset`.
- Voeg jitter toe aan nieuwe pogingen.

## Fouten

- v1-fouten zijn platte tekst (`text/plain; charset=utf-8`), waaronder `400`,
  `401`, `403`, `404`, `429` en reacties voor geblokkeerde downloads.
- Onbekende queryparameters worden voor compatibiliteit genegeerd.
- Bekende queryparameters met ongeldige waarden retourneren `400`.

## Eindpunten

Openbaar lezen:

- `GET /api/v1/search?q=...`
  - Optionele filters: `highlightedOnly=true`, `nonSuspiciousOnly=true`
  - Verouderde alias: `nonSuspicious=true`
- `GET /api/v1/skills?limit=&cursor=&sort=`
  - `sort`: `updated` (standaard), `recommended` (`default`), `createdAt` (`newest`), `downloads`, `stars` (`rating`), verouderde installatiealiassen `installsCurrent`/`installs`/`installsAllTime` verwijzen naar `downloads`, `trending`
  - Ongeldige waarden voor `sort` retourneren `400`
  - `cursor` is van toepassing op sorteringen die niet `trending` zijn
  - Optioneel filter: `nonSuspiciousOnly=true`
  - Verouderde alias: `nonSuspicious=true`
  - Met `nonSuspiciousOnly=true` kunnen cursorgebaseerde pagina's minder dan `limit` items bevatten; gebruik `nextCursor` om door te gaan.
  - `recommended` gebruikt signalen voor betrokkenheid en recentheid.
- `GET /api/v1/skills/{slug}`
- `GET /api/v1/skills/{slug}/moderation`
- `GET /api/v1/skills/{slug}/versions?limit=&cursor=`
- `GET /api/v1/skills/{slug}/versions/{version}`
- `GET /api/v1/skills/{slug}/scan?version=&tag=`
- `GET /api/v1/skills/{slug}/file?path=&version=&tag=`
- `GET /api/v1/resolve?slug=&hash=`
- `GET /api/v1/download?slug=&version=&tag=`
  - Gehoste Skills retourneren deterministische ZIP-bytes.
  - Huidige door GitHub ondersteunde Skills met een `clean`- of `suspicious`-scan retourneren een
    JSON-`public-github`-overdrachtsdescriptor in plaats van bytes van ClawHub.
- `GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=`
  - Gehoste Skills worden geëxporteerd als opgeslagen bestanden.
  - Huidige door GitHub ondersteunde Skills met een `clean`- of `suspicious`-scan worden geëxporteerd
    als `public-github`-overdrachtsdescriptors.
- `GET /api/v1/packages?limit=&cursor=&sort=`
  - `sort`: `updated` (standaard), `recommended`, `downloads`, verouderde alias `installs`
  - Ongeldige waarden voor `sort` retourneren `400`
- `GET /api/v1/plugins?limit=&cursor=&sort=`
  - `sort`: `recommended` (standaard), `downloads`, `updated`, verouderde alias `installs`
- `GET /api/v1/plugins/search?q=...`
- `GET /api/v1/packages/{name}/versions/{version}/artifact`
- `GET /api/v1/packages/{name}/versions/{version}/security`
- `GET /api/v1/packages/{name}/versions/{version}/artifact/download`
- `GET /api/npm/{package}`
- `GET /api/npm/{package}/-/{tarball}.tgz`

Authenticatie vereist:

- `POST /api/v1/skills` (publiceren, bij voorkeur multipart)
- `DELETE /api/v1/skills/{slug}`
- `DELETE /api/v1/packages/{name}`
- `POST /api/v1/skills/{slug}/undelete`
- `POST /api/v1/packages/{name}/undelete`
- `POST /api/v1/skills/{slug}/rename`
- `POST /api/v1/skills/{slug}/merge`
- `POST /api/v1/skills/{slug}/transfer`
- `POST /api/v1/packages/{name}/transfer`
- `POST /api/v1/skills/{slug}/transfer/accept`
- `POST /api/v1/skills/{slug}/transfer/reject`
- `POST /api/v1/skills/{slug}/transfer/cancel`
- `GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=`
- `GET /api/v1/plugins/export?startDate=&endDate=&limit=&cursor=&family=`
- `GET /api/v1/transfers/incoming`
- `GET /api/v1/transfers/outgoing`
- `GET /api/v1/whoami`

Alleen voor beheerders:

- `POST /api/v1/users/reserve` reserveert root-slugs en privéplaatshouders voor pakketten zonder release voor een eigenaarshandle.

## Verouderd

Verouderde `/api/*` en `/api/cli/*` zijn nog steeds beschikbaar. Zie `DEPRECATIONS.md`.