Get started

HTTP-API

Basis-URL: https://clawhub.ai (standaard).

Alle v1-paden vallen onder /api/v1/.... Verouderde /api/... en /api/cli/... blijven beschikbaar voor compatibiliteit (zie DEPRECATIONS.md). OpenAPI: /api/v1/openapi.json.

Hergebruik van de openbare catalogus

Externe directory's mogen de openbare leesendpoints gebruiken om ClawHub-Skills weer te geven of te doorzoeken. Cache de resultaten, respecteer 429/Retry-After, verwijs gebruikers terug naar de canonieke ClawHub-vermelding (https://clawhub.ai/<owner>/skills/<slug>) en wek niet de indruk dat ClawHub de externe site onderschrijft. Probeer geen verborgen, privé- of door moderatie geblokkeerde inhoud buiten het openbare API-oppervlak te spiegelen.

Verkorte webslugs worden tussen registerfamilies omgezet, maar API-clients moeten de canonieke URL's gebruiken die leesendpoints retourneren, in plaats van zelf de routeprioriteit te reconstrueren.

Frequentielimieten

Handhavingsmodel:

Anonieme verzoeken: gehandhaafd per IP-adres.
Geverifieerde verzoeken (geldig Bearer-token): gehandhaafd per gebruikersbucket.
Als het token ontbreekt of ongeldig is, valt het gedrag terug op handhaving per IP-adres.
Geverifieerde schrijfendpoints mogen niet alleen een kale Unauthorized retourneren wanneer de server de reden kent. Ontbrekende tokens, ongeldige/ingetrokken tokens en verwijderde/verbannen/uitgeschakelde accounts moeten elk bruikbare tekst opleveren, zodat CLI- clients gebruikers kunnen vertellen wat hen heeft geblokkeerd.
Lezen: 3000/min per IP-adres, 12000/min per sleutel
Schrijven: 300/min per IP-adres, 3000/min per sleutel
Downloaden: 1200/min per IP-adres, 6000/min per sleutel (downloadendpoints)

Headers:

Compatibiliteit met verouderde versies: X-RateLimit-Limit, X-RateLimit-Reset
Gestandaardiseerd: RateLimit-Limit, RateLimit-Reset
Bij 429: X-RateLimit-Remaining: 0 en RateLimit-Remaining: 0
Bij 429: Retry-After

Betekenis van headers:

X-RateLimit-Reset: absolute Unix-epochtijd in seconden
RateLimit-Reset: aantal seconden tot reset (vertraging)
X-RateLimit-Remaining / RateLimit-Remaining: exact resterend budget, indien aanwezig. Geslaagde gesharde verzoeken laten deze header weg in plaats van een geschatte globale waarde te retourneren.
Retry-After: aantal seconden dat moet worden gewacht voordat opnieuw wordt geprobeerd (vertraging) bij 429

Voorbeeld van een 429-respons:

http

HTTP/2 429content-type: text/plain; charset=utf-8x-ratelimit-limit: 20x-ratelimit-remaining: 0x-ratelimit-reset: 1771404540ratelimit-limit: 20ratelimit-remaining: 0ratelimit-reset: 34retry-after: 34 Frequentielimiet overschreden

Richtlijnen voor clients:

Als Retry-After bestaat, wacht dan dat aantal seconden voordat je het opnieuw probeert.
Gebruik back-off met jitter om gesynchroniseerde nieuwe pogingen te voorkomen.
Als Retry-After ontbreekt, val dan terug op RateLimit-Reset (of bereken dit op basis van X-RateLimit-Reset).

IP-bron:

Gebruikt vertrouwde headers voor client-IP-adressen, waaronder cf-connecting-ip, alleen wanneer de implementatie vertrouwde doorgestuurde headers expliciet inschakelt.
ClawHub gebruikt vertrouwde doorgestuurde headers om client-IP-adressen aan de rand te identificeren.
Als er geen vertrouwd client-IP-adres beschikbaar is, gebruiken anonieme verzoeken fallback-buckets die alleen door het type frequentielimiet zijn afgebakend. Deze fallback-buckets bevatten geen door de aanroeper aangeleverde paden, slugs, pakketnamen, versies, querystrings of andere artefactparameters.

Foutresponsen

Openbare v1-foutresponsen zijn platte tekst met content-type: text/plain; charset=utf-8. Dit omvat validatiefouten (400), ontbrekende openbare bronnen (404), verificatie- en machtigingsfouten (401/403), frequentielimieten (429) en geblokkeerde downloads. Clients moeten de responsbody als een voor mensen leesbare tekenreeks verwerken. Onbekende queryparameters worden voor compatibiliteit genegeerd, maar herkende queryparameters met ongeldige waarden retourneren 400.

Openbare endpoints (geen verificatie)

`GET /api/v1/search`

Queryparameters:

q (vereist): querytekenreeks
limit (optioneel): geheel getal
highlightedOnly (optioneel): true om te filteren op uitgelichte Skills
nonSuspiciousOnly (optioneel): true om verdachte (flagged.suspicious) Skills te verbergen
nonSuspicious (optioneel): verouderde alias voor nonSuspiciousOnly

Respons:

json

{  "results": [    {      "score": 0.123,      "slug": "gifgrep",      "displayName": "GifGrep",      "summary": "…",      "version": "1.2.3",      "updatedAt": 1730000000000,      "ownerHandle": "openclaw",      "owner": {        "handle": "openclaw",        "displayName": "OpenClaw",        "image": "https://example.com/avatar.png"      }    }  ]}

Opmerkingen:

Resultaten worden geretourneerd in volgorde van relevantie (overeenkomst van embeddings + boosts voor exacte slug-/naamstokens + een kleine voorafgaande populariteitsweging).
Relevantie weegt zwaarder dan populariteit. Een exacte overeenkomst met een slug- of weergavenaamtoken kan hoger eindigen dan een ruimere overeenkomst met veel sterkere betrokkenheid.
ASCII-tekst wordt getokeniseerd op woord- en interpunctiegrenzen. personal-map bevat bijvoorbeeld een zelfstandig map-token, terwijl amap-jsapi-skill amap, jsapi en skill bevat; zoeken naar map geeft personal-map daarom een sterkere lexicale overeenkomst dan amap-jsapi-skill.
Populariteit wordt logaritmisch geschaald en begrensd. Skills met veel betrokkenheid kunnen lager eindigen wanneer de querytekst minder goed overeenkomt.
Een verdachte of verborgen moderatiestatus kan een Skill uit openbare zoekresultaten verwijderen, afhankelijk van de filters van de aanroeper en de huidige moderatiestatus.

Richtlijnen voor vindbaarheid van uitgevers:

Plaats de termen waarop gebruikers letterlijk zullen zoeken in de weergavenaam, samenvatting en tags. Gebruik alleen een zelfstandig slugtoken wanneer dit ook een stabiele identiteit is die je wilt behouden.
Wijzig een slug niet alleen om op één query in te spelen, tenzij de nieuwe slug op lange termijn een betere canonieke naam is. Oude slugs worden omleidingsaliassen, maar de canonieke URL, weergegeven slug en toekomstige zoeksamenvattingen gebruiken de nieuwe slug.
Hernoemingsaliassen behouden de resolutie voor oude URL's en installaties die via het register worden omgezet, maar de zoekrangschikking is gebaseerd op de canonieke Skill-metadata nadat de hernoeming is geïndexeerd. Bestaande statistieken blijven aan de Skill gekoppeld.
Als een Skill onverwacht onzichtbaar is, controleer dan eerst de moderatiestatus met clawhub inspect @owner/slug terwijl je bent ingelogd, voordat je metadata wijzigt die verband houdt met de rangschikking.

`GET /api/v1/skills`

Queryparameters:

limit (optioneel): geheel getal (1–200)
cursor (optioneel): pagineringscursor voor elke sortering anders dan trending
sort (optioneel): updated (standaard), recommended (alias: default), createdAt (alias: newest), downloads, stars (alias: rating), verouderde installatiealiassen installsCurrent/installs/installsAllTime verwijzen naar downloads, trending
nonSuspiciousOnly (optioneel): true om verdachte (flagged.suspicious) Skills te verbergen
nonSuspicious (optioneel): verouderde alias voor nonSuspiciousOnly

Ongeldige waarden voor sort retourneren 400.

Opmerkingen:

recommended gebruikt signalen voor betrokkenheid en recentheid.
trending rangschikt op basis van installaties in de afgelopen 7 dagen (op basis van telemetrie).
createdAt is stabiel voor crawls van nieuwe Skills; updated verandert wanneer bestaande Skills opnieuw worden gepubliceerd.
Bij nonSuspiciousOnly=true kunnen sorteringen op basis van een cursor minder dan limit items op een pagina retourneren, omdat verdachte Skills na het ophalen van de pagina worden uitgefilterd.
Gebruik nextCursor om de paginering voort te zetten wanneer deze aanwezig is. Een korte pagina betekent op zichzelf niet dat het einde van de resultaten is bereikt.

Respons:

json

{  "items": [    {      "slug": "gifgrep",      "displayName": "GifGrep",      "summary": "…",      "topics": ["Productivity"],      "tags": { "latest": "1.2.3" },      "stats": {},      "createdAt": 0,      "updatedAt": 0,      "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" },      "metadata": { "os": ["macos"], "systems": ["aarch64-darwin"] }    }  ],  "nextCursor": null}

`GET /api/v1/skills/{slug}`

Respons:

json

{  "skill": {    "slug": "gifgrep",    "displayName": "GifGrep",    "summary": "…",    "topics": ["Productivity"],    "tags": { "latest": "1.2.3" },    "stats": {},    "createdAt": 0,    "updatedAt": 0  },  "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" },  "metadata": { "os": ["macos"], "systems": ["aarch64-darwin"] },  "owner": { "handle": "steipete", "displayName": "Peter", "image": null },  "moderation": {    "isSuspicious": false,    "isMalwareBlocked": false,    "verdict": "clean",    "reasonCodes": [],    "summary": null,    "engineVersion": "v2.0.0",    "updatedAt": 0  }}

Opmerkingen:

Oude slugs die zijn aangemaakt door hernoemings-/samenvoegingsflows van eigenaren worden omgezet naar de canonieke Skill.
metadata.os: OS-beperkingen die in de frontmatter van de Skill zijn gedeclareerd (bijv. ["macos"], ["linux"]). null indien niet gedeclareerd.
metadata.systems: Nix-systeemdoelen (bijv. ["aarch64-darwin", "x86_64-linux"]). null indien niet gedeclareerd.
metadata is null als de Skill geen platformmetadata heeft.
moderation wordt alleen opgenomen wanneer de Skill is gemarkeerd of de eigenaar deze bekijkt.

`GET /api/v1/skills/{slug}/moderation`

Retourneert gestructureerde moderatiestatus.

Respons:

json

{  "moderation": {    "isSuspicious": true,    "isMalwareBlocked": false,    "verdict": "suspicious",    "reasonCodes": ["suspicious.dynamic_code_execution"],    "summary": "Detected: suspicious.dynamic_code_execution",    "engineVersion": "v2.0.0",    "updatedAt": 0,    "legacyReason": null,    "evidence": [      {        "code": "suspicious.dynamic_code_execution",        "severity": "critical",        "file": "index.ts",        "line": 3,        "message": "Dynamic code execution detected.",        "evidence": ""      }    ]  }}

Opmerkingen:

Eigenaren en moderators hebben toegang tot moderatiedetails voor verborgen Skills.
Openbare aanroepers krijgen 200 alleen voor reeds gemarkeerde zichtbare Skills.
Bewijs wordt voor openbare aanroepers geredigeerd en bevat alleen ruwe fragmenten voor eigenaren/moderators.

`POST /api/v1/skills/{slug}/report`

Rapporteer een Skill ter beoordeling door een moderator. Rapporten gelden voor de hele Skill, zijn optioneel gekoppeld aan een versie en worden toegevoegd aan de wachtrij met Skill-rapporten.

Verificatie:

Vereist een API-token.

Verzoek:

json

{ "reason": "Suspicious install step", "version": "1.2.3" }

Respons:

json

{  "ok": true,  "reported": true,  "alreadyReported": false,  "reportId": "skillReports:...",  "skillId": "skills:...",  "reportCount": 1}

`GET /api/v1/skills/-/reports`

Endpoint voor moderators/beheerders voor de intake van Skill-rapporten.

Queryparameters:

status (optioneel): open (standaard), confirmed, dismissed of all
limit (optioneel): geheel getal (1-200)
cursor (optioneel): pagineringscursor

Respons:

json

{  "items": [    {      "reportId": "skillReports:...",      "skillId": "skills:...",      "skillVersionId": "skillVersions:...",      "slug": "gifgrep",      "displayName": "GifGrep",      "version": "1.2.3",      "reason": "Verdachte installatiestap",      "status": "open",      "createdAt": 1730000000000,      "reporter": {        "userId": "users:...",        "handle": "reporter",        "displayName": "Melder"      },      "triagedAt": null,      "triagedBy": null,      "triageNote": null    }  ],  "nextCursor": null,  "done": true}

`POST /api/v1/skills/-/reports/{reportId}/triage`

Endpoint voor moderators/beheerders om skillmeldingen af te handelen of te heropenen.

Verzoek:

json

{ "status": "confirmed", "note": "Beoordeeld en betreffende versie verborgen.", "finalAction": "hide" }

note is vereist voor confirmed en dismissed; deze mag worden weggelaten wanneer status weer wordt ingesteld op open. Geef finalAction: "hide" door met een getriageerde melding om de skill binnen dezelfde controleerbare workflow te verbergen.

`GET /api/v1/skills/{slug}/versions`

Queryparameters:

limit (optioneel): geheel getal
cursor (optioneel): pagineringscursor

`GET /api/v1/skills/{slug}/versions/{version}`

Retourneert versiemetadata en een bestandenlijst.

version.security bevat, indien beschikbaar, de genormaliseerde verificatiestatus van de scan en scannergegevens (VirusTotal + LLM).

`GET /api/v1/skills/{slug}/scan`

Retourneert details van de beveiligingsscanverificatie voor een skillversie.

Queryparameters:

version (optioneel): specifieke versietekenreeks.
tag (optioneel): een getagde versie omzetten (bijvoorbeeld latest).

Opmerkingen:

Als noch version noch tag is opgegeven, wordt de nieuwste versie gebruikt.
Bevat de genormaliseerde verificatiestatus plus scannerspecifieke details.
security.hasScanResult is alleen true wanneer een scanner een definitief oordeel heeft opgeleverd (clean, suspicious of malicious).
moderation is een actuele moderatiemomentopname op skillniveau, afgeleid van de nieuwste versie.
Controleer bij het opvragen van een historische versie moderation.matchesRequestedVersion en moderation.sourceVersion voordat je moderation en security als dezelfde versiecontext behandelt.

`POST /api/v1/skills/-/scan`

Geverifieerd indieningsendpoint voor nieuwe ClawScan-taken.

Scans van lokale uploads worden niet meer ondersteund. Verzoeken die multipart/form-data of { "source": { "kind": "upload" } } gebruiken, retourneren 410.

Gepubliceerde scans gebruiken JSON:

json

{  "source": { "kind": "published", "slug": "gifgrep", "version": "1.2.3" },  "update": false}

Opmerkingen:

Payloads van scanverzoeken en downloadbare rapporten verlopen in de opslag voor scanverzoeken na het bewaarvenster.
Gepubliceerde scans vereisen beheerstoegang als eigenaar/uitgever of bevoegdheid als platformmoderator/-beheerder.
Gepubliceerde scans schrijven alleen terug wanneer update: true en de scan met succes wordt voltooid.
Het antwoord is 202 met { "ok": true, "scanId": "...", "jobId": "...", "status": "queued", "sourceKind": "published", "update": false, "queue": { "queuedAhead": 0, "queuedAheadIsEstimate": false, "position": 1, "running": 0, "runningIsEstimate": false, "note": "Scans are asynchronous and may take time to complete." } }.
Scantaken zijn asynchroon. Handmatige scanverzoeken krijgen voorrang boven normaal publicatie-/backfillwerk, maar voltooiing blijft afhankelijk van de beschikbaarheid van workers.

`GET /api/v1/skills/-/scan/{scanId}`

Geverifieerd pollingendpoint voor een ingediende scan.

Retourneert de status in wachtrij/actief/geslaagd/mislukt.
Retourneert queue.queuedAhead en queue.position zolang het verzoek in de wachtrij staat, zodat clients kunnen tonen hoeveel handmatige scans met prioriteit vóór het verzoek staan. Zeer grote wachtrijen worden begrensd en gerapporteerd met queuedAheadIsEstimate: true.
Indien beschikbaar bevat report de secties clawscan, skillspector, staticAnalysis en virustotal.
Mislukte scantaken retourneren status: "failed" met lastError.

`GET /api/v1/skills/-/scan/{scanId}/download`

Geverifieerd endpoint voor rapportarchieven.

Vereist een geslaagde scan; niet-afgesloten scans retourneren 409.
Retourneert een ZIP-bestand met manifest.json, clawscan.json, skillspector.json, static-analysis.json, virustotal.json en README.md.

`GET /api/v1/skills/-/scan/download/{name}?version=<version>&kind=skill|plugin`

Geverifieerd endpoint voor opgeslagen rapportarchieven van ingediende versies.

Vereist beheerstoegang als eigenaar/uitgever tot de skill of Plugin, of bevoegdheid als platformmoderator/-beheerder.
Retourneert opgeslagen scanresultaten voor exact de ingediende versie, inclusief geblokkeerde of verborgen versies.
kind is standaard skill; gebruik kind=plugin voor scans van plugins/pakketten.
Retourneert dezelfde ZIP-structuur als downloads van scanverzoeken.

`POST /api/v1/skills/-/scan/batch`

Canonieke batchroute voor opnieuw scannen, alleen voor beheerders. Deze accepteert dezelfde payloadstructuur als de verouderde POST /api/v1/skills/-/rescan-batch.

`POST /api/v1/skills/-/scan/batch/status`

Canonieke batchstatusroute, alleen voor beheerders. Deze accepteert { "jobIds": ["..."] } en retourneert dezelfde geaggregeerde tellers als de verouderde POST /api/v1/skills/-/rescan-batch/status.

`GET /api/v1/skills/{slug}/verify`

Retourneert de verificatie-envelop van de Skill Card die door clawhub skill verify wordt gebruikt.

Queryparameters:

version (optioneel): specifieke versietekenreeks.
tag (optioneel): een getagde versie omzetten (bijvoorbeeld latest).

Opmerkingen:

ok is alleen true wanneer voor de geselecteerde versie een Skill Card is gegenereerd, deze niet door moderatie als malware is geblokkeerd en de ClawScan-verificatie schoon is.
De skillidentiteit, uitgeversidentiteit en metadata van de geselecteerde versie zijn envelopvelden op het hoogste niveau (slug, displayName, publisherHandle, version, resolvedFrom, tag, createdAt), zodat shellautomatisering deze kan lezen zonder geneste wrappers uit te pakken.
security is het ClawScan-/beveiligingsoordeel op het hoogste niveau. Automatisering moet zich baseren op ok, decision, reasons en security.status.
security.signals bevat ondersteunend scannerbewijs, zoals staticScan, virusTotal en skillSpector.
security.signals.dependencyRegistry blijft behouden voor compatibiliteit met v1-antwoorden, maar de scanner voor het bestaan van afhankelijkheden in het register is buiten gebruik gesteld en deze sleutel is altijd null.
provenance is alleen server-resolved-github-import wanneer ClawHub tijdens publicatie of import een GitHub-repo/ref/commit/pad heeft omgezet en opgeslagen; anders is deze unavailable.

`POST /api/v1/skills/-/security-verdicts`

Retourneert actuele compacte beveiligingsoordelen voor exacte skillversies. Dit collectie-endpoint is bedoeld voor clients die al weten welke geïnstalleerde ClawHub-skillversies ze moeten weergeven, zoals de OpenClaw Control UI.

Verzoek:

json

{  "items": [{ "slug": "gifgrep", "version": "1.2.3" }]}

Opmerkingen:

items moet 1-100 unieke { slug, version }-paren bevatten.
Resultaten worden per item geretourneerd; één ontbrekende skill of versie laat niet het hele antwoord mislukken.
Het antwoord bevat alleen beveiligingsgegevens. Het bevat geen Skill Card-gegevens, status van gegenereerde kaarten, lijsten met artefactbestanden of gedetailleerde scannerpayloads.
security.signals bevat alleen ondersteunend bewijs op statusniveau; gebruik /scan of de beveiligingsauditpagina van ClawHub voor volledige scannergegevens.
security.signals.dependencyRegistry blijft behouden voor compatibiliteit met v1-antwoorden, maar de scanner voor het bestaan van afhankelijkheden in het register is buiten gebruik gesteld en deze sleutel is altijd null.
Het ontbreken van een Skill Card heeft geen invloed op ok, decision of reasons van dit endpoint; clients moeten de geïnstalleerde skill-card.md lokaal lezen wanneer ze kaartinhoud nodig hebben.
Gebruik /verify wanneer je de Skill Card-verificatie-envelop voor één skill nodig hebt, /card wanneer je gegenereerde kaart-Markdown nodig hebt en /scan wanneer je gedetailleerde scannergegevens nodig hebt.

Antwoord:

json

{  "schema": "clawhub.skill.security-verdicts.v1",  "items": [    {      "ok": true,      "decision": "pass",      "reasons": [],      "requestedSlug": "gifgrep",      "slug": "gifgrep",      "displayName": "GifGrep",      "publisherHandle": "steipete",      "publisherDisplayName": "Peter",      "requestedVersion": "1.2.3",      "version": "1.2.3",      "createdAt": 0,      "checkedAt": 0,      "skillUrl": "https://clawhub.ai/steipete/skills/gifgrep",      "securityAuditUrl": "https://clawhub.ai/steipete/skills/gifgrep/security-audit?version=1.2.3",      "security": {        "status": "clean",        "passed": true,        "signals": {          "staticScan": { "status": "clean", "reasonCodes": [] },          "virusTotal": null,          "skillSpector": null,          "dependencyRegistry": null        }      }    },    {      "ok": false,      "decision": "fail",      "reasons": ["version.not_found"],      "requestedSlug": "missing-version",      "requestedVersion": "1.0.0",      "error": { "code": "version_not_found", "message": "Versie niet gevonden" },      "security": null    }  ]}

`GET /api/v1/skills/{slug}/file`

Retourneert exact de opgeslagen bestandsbytes als download. Voeg preview=1 toe om een begrensd voorbeeld met geëscapete tekst op te vragen; elk bestand met geldige UTF-8-bytes kan als voorbeeld worden weergegeven, ongeacht de extensie of MIME- metadata.

Queryparameters:

path (vereist)
version (optioneel)
tag (optioneel)
preview=1 (optioneel; retourneert text/plain of 415 wanneer de bytes geen geldige UTF-8 vormen)

Opmerkingen:

Gebruikt standaard de nieuwste versie.
Limiet voor onbewerkte downloads: 10MB.
Limiet voor tekstvoorbeelden: 200KB.

`GET /api/v1/packages`

Uniform catalogusendpoint voor:

skills
codeplugins
bundelplugins

Queryparameters:

limit (optioneel): geheel getal (1–100)
cursor (optioneel): pagineringscursor
family (optioneel): skill, code-plugin of bundle-plugin
channel (optioneel): official, community of private
isOfficial (optioneel): true of false
sort (optioneel): updated (standaard), recommended, trending, downloads, verouderde alias installs
category (optioneel): filter voor plugincategorieën. Wordt alleen ondersteund wanneer het verzoek is beperkt tot pluginpakketten (/api/v1/plugins, /api/v1/code-plugins, /api/v1/bundle-plugins of pakketendpoints met family=code-plugin/family=bundle-plugin). Beheerde categorieën en verouderde v1-filteraliassen worden gedocumenteerd onder GET /api/v1/plugins.

Opmerkingen:

Ongeldige waarden voor family, channel, isOfficial, featured, highlightedOnly of sort retourneren 400. Onbekende queryparameters worden genegeerd.
GET /api/v1/code-plugins en GET /api/v1/bundle-plugins blijven aliassen voor vaste families.
Skillvermeldingen blijven gebaseerd op het skillregister en kunnen nog steeds alleen via POST /api/v1/skills worden gepubliceerd.
POST /api/v1/packages is nog steeds alleen bedoeld voor releases van codeplugins en bundelplugins.
Anonieme aanroepers zien alleen openbare pakketkanalen.
Geverifieerde aanroepers kunnen in lijst-/zoekresultaten privépakketten zien van uitgevers waartoe ze behoren.
channel=private retourneert alleen pakketten die de geverifieerde aanroeper kan lezen.

`GET /api/v1/packages/search`

Uniform zoeken in de catalogus voor skills en pluginpakketten.

Queryparameters:

q (verplicht): querytekenreeks
limit (optioneel): geheel getal (1–100)
family (optioneel): skill, code-plugin of bundle-plugin
channel (optioneel): official, community of private
isOfficial (optioneel): true of false
category (optioneel): filter voor Plugin-categorieën. Wordt alleen ondersteund wanneer het verzoek is beperkt tot Plugin-pakketten. Beheerde categorieën en verouderde v1- filteraliassen zijn gedocumenteerd onder GET /api/v1/plugins.

Opmerkingen:

Ongeldige waarden voor family, channel, isOfficial, featured of highlightedOnly retourneren 400. Onbekende queryparameters worden genegeerd.
Anonieme aanroepers zien alleen openbare pakketkanalen.
Geverifieerde aanroepers kunnen zoeken in privépakketten van uitgevers waartoe ze behoren.
channel=private retourneert alleen pakketten die de geverifieerde aanroeper kan lezen.

`GET /api/v1/plugins`

Bladeren door de catalogus, uitsluitend voor Plugins, in code-Plugin- en bundel-Plugin-pakketten.

Queryparameters:

limit (optioneel): geheel getal (1-100)
cursor (optioneel): pagineringscursor
isOfficial (optioneel): true of false
sort (optioneel): recommended (standaard), trending, downloads, updated, verouderde alias installs
category (optioneel): filter voor Plugin-categorieën. Huidige waarden: channels, models, memory, context, voice, media, web, tools, runtime, gateway, security, other.

Verouderde v1-filteraliassen blijven geaccepteerd op leeseindpunten:

mcp-tooling, data en automation worden herleid tot tools.
observability en deployment worden herleid tot gateway.
dev-tools wordt herleid tot runtime.

trending is een ranglijst voor installaties/downloads over zeven dagen en gebruikt geen totalen over de gehele periode. Op het uniforme /api/v1/packages-eindpunt geldt dit alleen voor Plugins; gebruik /api/v1/skills?sort=trending voor de Skills-catalogus.

Verouderde aliassen worden niet geaccepteerd als opgeslagen of door auteurs gedeclareerde categoriewaarden.

`GET /api/v1/skills/export`

Bulkexport van de nieuwste openbare Skills voor offlineanalyse.

Authenticatie:

API-token vereist.

Queryparameters:

startDate (verplicht): ondergrens in Unix-milliseconden voor updatedAt van de Skill.
endDate (verplicht): bovengrens in Unix-milliseconden voor updatedAt van de Skill.
limit (optioneel): geheel getal (1-250), standaard 250.
cursor (optioneel): pagineringscursor uit het vorige antwoord.

Antwoord:

Inhoud: ZIP-archief.
Elke geëxporteerde Skill heeft {publisher}/{slug}/ als hoofdmap.
Gehoste Skills bevatten de bestanden van de laatst opgeslagen versie en worden vermeld in _manifest.json met sourceRef: "public-clawhub".
Huidige door GitHub ondersteunde Skills met een clean- of suspicious-scan bevatten _source_handoff.json met sourceRef: "public-github", repository, commit, pad, inhoudshash en archief-URL. Ze bevatten geen door ClawHub gehoste bronbestanden.
Elke Skill bevat _export_skill_meta.json.
_manifest.json wordt altijd opgenomen in de hoofdmap van het ZIP-bestand.
_errors.json wordt opgenomen wanneer afzonderlijke Skills of bestanden niet konden worden geëxporteerd.

Headers:

X-Next-Cursor
X-Has-More
X-Total-Returned
X-Date-Range
X-Export-Errors

`GET /api/v1/plugins/export`

Bulkexport van de nieuwste openbare Plugin-releases voor offlineanalyse.

Authenticatie:

API-token vereist.

Queryparameters:

startDate (verplicht): ondergrens in Unix-milliseconden voor updatedAt van de Plugin.
endDate (verplicht): bovengrens in Unix-milliseconden voor updatedAt van de Plugin.
limit (optioneel): geheel getal (1-250), standaard 250.
cursor (optioneel): pagineringscursor uit het vorige antwoord.
family (optioneel): code-plugin of bundle-plugin. Weglaten betekent beide Plugin-families.

Antwoord:

Inhoud: ZIP-archief.
Elke geëxporteerde Plugin heeft {family}/{packageName}/ als hoofdmap.
Elke geëxporteerde Plugin bevat de opgeslagen bestanden van de nieuwste release.
Exportmetadata per Plugin wordt opgeslagen in __clawhub_export/{family}/{packageName}/plugin_meta.json.
_manifest.json wordt altijd opgenomen in de hoofdmap van het ZIP-bestand.
_errors.json wordt opgenomen wanneer afzonderlijke Plugins of bestanden niet konden worden geëxporteerd.

Headers:

X-Next-Cursor
X-Has-More
X-Total-Returned
X-Date-Range
X-Export-Errors

`GET /api/v1/plugins/search`

Zoeken, uitsluitend naar Plugins, in code-Plugin- en bundel-Plugin-pakketten.

Queryparameters:

q (verplicht): querytekenreeks
limit (optioneel): geheel getal (1-100)
isOfficial (optioneel): true of false
category (optioneel): filter voor Plugin-categorieën. Huidige waarden: channels, models, memory, context, voice, media, web, tools, runtime, gateway, security, other.

Opmerkingen:

De verouderde v1-filteraliassen die onder GET /api/v1/plugins zijn gedocumenteerd, worden ook geaccepteerd.
Categoriefiltering is een echt API-filter dat wordt ondersteund door digest- rijen voor Plugin-categorieën, niet door een herschrijving van de zoekquery.
Resultaten worden in volgorde van relevantie geretourneerd en worden momenteel niet gepagineerd.
Sorteerknoppen in de browserinterface voor het zoeken naar Plugins herschikken de geladen relevantieresultaten, overeenkomstig het huidige bladergedrag van /skills.

`GET /api/v1/packages/{name}`

Retourneert detailmetadata van het pakket.

Opmerkingen:

Skills kunnen in de uniforme catalogus ook via deze route worden herleid.
Privépakketten retourneren 404, tenzij de aanroeper de eigenaar-uitgever kan lezen.

`DELETE /api/v1/packages/{name}`

Verwijdert een pakket en alle releases via een zachte verwijdering.

Opmerkingen:

Vereist een API-token voor de pakketeigenaar, een eigenaar/beheerder van de organisatie-uitgever, platformmoderator of platformbeheerder.

`GET /api/v1/packages/{name}/versions`

Retourneert de versiegeschiedenis.

Queryparameters:

limit (optioneel): geheel getal (1–100)
cursor (optioneel): pagineringscursor

Opmerkingen:

Privépakketten retourneren 404, tenzij de aanroeper de eigenaar-uitgever kan lezen.

`GET /api/v1/packages/{name}/versions/{version}`

Retourneert één pakketversie, inclusief bestandsmetadata, compatibiliteit, verificatie, artefactmetadata en scangegevens.

Opmerkingen:

version.artifact.kind is legacy-zip voor pakketarchieven uit het oude systeem of npm-pack voor door ClawPack ondersteunde releases.
ClawPack-releases bevatten npm-compatibele velden npmIntegrity, npmShasum en npmTarballName.
version.sha256hash is verouderde compatibiliteitsmetadata voor oude clients. Deze hasht exact de ZIP-bytes die door /api/v1/packages/{name}/download worden geretourneerd. Moderne clients moeten version.artifact.sha256 gebruiken, waarmee het canonieke releaseartefact wordt geïdentificeerd.
version.vtAnalysis, version.llmAnalysis en version.staticScan worden opgenomen wanneer scangegevens bestaan.
Privépakketten retourneren 404, tenzij de aanroeper de eigenaar-uitgever kan lezen.

`GET /api/v1/packages/{name}/versions/{version}/security`

Retourneert het exacte beveiligings- en vertrouwensoverzicht van de pakketrelease voor installatie- clients. Dit is het openbare OpenClaw-gebruiksoppervlak om te bepalen of een herleide release kan worden geïnstalleerd.

Authenticatie:

Openbaar leeseindpunt. Er is geen token van een eigenaar, uitgever, moderator of beheerder vereist.

Antwoord:

json

{  "package": {    "name": "@openclaw/example-plugin",    "displayName": "Voorbeeld-Plugin",    "family": "code-plugin"  },  "release": {    "releaseId": "packageReleases:...",    "version": "1.2.3",    "artifactKind": "npm-pack",    "artifactSha256": "0123456789abcdef...",    "npmIntegrity": "sha512-...",    "npmShasum": "0123456789abcdef0123456789abcdef01234567",    "npmTarballName": "example-plugin-1.2.3.tgz",    "createdAt": 1730000000000  },  "trust": {    "scanStatus": "malicious",    "moderationState": "quarantined",    "blockedFromDownload": true,    "reasons": ["manual:quarantined", "scan:malicious"],    "pending": false,    "stale": false  }}

Antwoordvelden:

package.name, package.displayName en package.family identificeren het herleide registerpakket.
release.releaseId, release.version en release.createdAt identificeren de exacte release die is beoordeeld.
release.artifactKind, release.artifactSha256, release.npmIntegrity, release.npmShasum en release.npmTarballName zijn aanwezig wanneer ze bekend zijn voor het releaseartefact.
trust.scanStatus is de effectieve vertrouwensstatus die is afgeleid van scannerinvoer en handmatige releasemoderatie.
trust.moderationState mag null zijn. De waarde is null wanneer er geen handmatige releasemoderatie bestaat.
trust.blockedFromDownload is het blokkeringssignaal voor installatie. OpenClaw en andere installatieclients moeten de installatie blokkeren wanneer deze waarde true is, in plaats van blokkeringsregels opnieuw af te leiden uit scanner- of moderatievelden.
trust.reasons is de lijst met uitleg voor gebruikers en audits. Redencodes zijn stabiele, compacte tekenreeksen, zoals manual:quarantined, scan:malicious en package:malicious.
trust.pending betekent dat een of meer vertrouwensinvoerwaarden nog op voltooiing wachten.
trust.stale betekent dat het vertrouwensoverzicht is berekend op basis van verouderde invoer en moet worden behandeld alsof vernieuwing vereist is voordat met hoge zekerheid een toestemmingsbesluit wordt genomen.

Opmerkingen:

Dit eindpunt is versiespecifiek. Clients moeten het aanroepen nadat ze de pakketversie hebben herleid die ze willen installeren, niet alleen nadat ze de nieuwste pakketmetadata hebben gelezen.
Privépakketten retourneren 404, tenzij de aanroeper de eigenaar-uitgever kan lezen.
Dit eindpunt is opzettelijk beperkter dan moderatie-eindpunten voor eigenaren/moderators. Het stelt de installatiebeslissing en openbare uitleg beschikbaar, niet de identiteit van melders, meldingsinhoud, privébewijs of interne beoordelings- tijdlijnen.

`GET /api/v1/packages/{name}/versions/{version}/artifact`

Retourneert de expliciete metadata van de artefactresolver voor een pakketversie.

Opmerkingen:

Verouderde pakketversies retourneren een legacy-zip-artefact en een verouderde ZIP- downloadUrl.
ClawPack-versies retourneren een npm-pack-artefact, npm-integriteitsvelden, een tarballUrl en de verouderde ZIP-compatibiliteits-URL.
Dit is het OpenClaw-resolveroppervlak; hiermee wordt voorkomen dat de archiefindeling wordt afgeleid uit een gedeelde URL.

`GET /api/v1/packages/{name}/versions/{version}/artifact/download`

Downloadt het versieartefact via het expliciete resolverpad.

Opmerkingen:

ClawPack-versies streamen exact de bytes van het geüploade npm-pack .tgz.
Verouderde ZIP-versies leiden om naar /api/v1/packages/{name}/download?version=.
Gebruikt de snelheidsbucket voor downloads.

`GET /api/v1/packages/{name}/readiness`

Retourneert de berekende gereedheid voor toekomstig gebruik door OpenClaw.

Gereedheidscontroles omvatten:

status van het officiële kanaal
beschikbaarheid van de nieuwste versie
beschikbaarheid van het ClawPack npm-pack-artefact
artefactdigest
herkomst van bronrepository en commit
compatibiliteitsmetadata voor OpenClaw
hostdoelen
scanstatus

Respons:

json

{  "package": {    "name": "@openclaw/example-plugin",    "displayName": "Voorbeeldplugin",    "family": "code-plugin",    "isOfficial": true,    "latestVersion": "1.2.3"  },  "ready": false,  "checks": [    {      "id": "clawpack",      "label": "ClawPack-artefact",      "status": "fail",      "message": "De nieuwste versie is uitsluitend beschikbaar als verouderd ZIP-bestand."    }  ],  "blockers": ["clawpack"]}

`GET /api/v1/packages/migrations`

Moderatorendpoint voor het weergeven van migratieregels voor officiële OpenClaw-plugins.

Authenticatie:

Vereist een API-token voor een moderator- of beheerdersgebruiker.

Queryparameters:

phase (optioneel): planned, published, clawpack-ready, legacy-zip-only, metadata-ready, blocked, ready-for-openclaw of all (standaard).
limit (optioneel): geheel getal (1-100)
cursor (optioneel): pagineringscursor

Respons:

json

{  "items": [    {      "migrationId": "officialPluginMigrations:...",      "bundledPluginId": "core.search",      "packageName": "@openclaw/search-plugin",      "packageId": "packages:...",      "owner": "platform",      "sourceRepo": "openclaw/openclaw",      "sourcePath": "plugins/search",      "sourceCommit": "abc123",      "phase": "blocked",      "blockers": ["ClawPack ontbreekt"],      "hostTargetsComplete": true,      "scanClean": false,      "moderationApproved": false,      "runtimeBundlesReady": false,      "notes": null,      "createdAt": 1760000000000,      "updatedAt": 1760000000000    }  ],  "nextCursor": null,  "done": true}

`POST /api/v1/packages/migrations`

Beheerdersendpoint voor het maken of bijwerken van een migratieregel voor een officiële plugin.

Authenticatie:

Vereist een API-token voor een beheerdersgebruiker.

Aanvraagbody:

json

{  "bundledPluginId": "core.search",  "packageName": "@openclaw/search-plugin",  "owner": "platform",  "sourceRepo": "openclaw/openclaw",  "sourcePath": "plugins/search",  "sourceCommit": "abc123",  "phase": "blocked",  "blockers": ["ClawPack ontbreekt"],  "hostTargetsComplete": true,  "scanClean": false,  "moderationApproved": false,  "runtimeBundlesReady": false,  "notes": "wacht op upload door uitgever"}

Opmerkingen:

bundledPluginId wordt genormaliseerd naar kleine letters en is de stabiele upsertsleutel.
packageName wordt genormaliseerd als npm-naam; het pakket mag ontbreken voor geplande migraties.
Dit houdt alleen de migratiegereedheid bij. Het wijzigt OpenClaw niet en genereert geen ClawPacks.

`GET /api/v1/packages/moderation/queue`

Moderator-/beheerdersendpoint voor beoordelingswachtrijen van pakketreleases.

Authenticatie:

Vereist een API-token voor een moderator- of beheerdersgebruiker.

Queryparameters:

status (optioneel): open (standaard), blocked, manual of all
limit (optioneel): geheel getal (1-100)
cursor (optioneel): pagineringscursor

Betekenis van statussen:

open: verdachte, schadelijke, in behandeling zijnde, in quarantaine geplaatste, ingetrokken of gemelde releases.
blocked: in quarantaine geplaatste, ingetrokken of schadelijke releases.
manual: elke release met een handmatige moderatie-override.
all: elke release met een handmatige override, een niet-schone scanstatus of een pakketmelding.

Respons:

json

{  "items": [    {      "packageId": "packages:...",      "releaseId": "packageReleases:...",      "name": "@openclaw/example-plugin",      "displayName": "Voorbeeldplugin",      "family": "code-plugin",      "channel": "community",      "isOfficial": false,      "version": "1.2.3",      "createdAt": 1730000000000,      "artifactKind": "npm-pack",      "scanStatus": "malicious",      "moderationState": "quarantined",      "moderationReason": "handmatige beoordeling",      "sourceRepo": "openclaw/example-plugin",      "sourceCommit": "abc123",      "reportCount": 2,      "lastReportedAt": 1730000001000,      "reasons": ["manual:quarantined", "scan:malicious", "reports:2"]    }  ],  "nextCursor": null,  "done": true}

`POST /api/v1/packages/{name}/report`

Meld een pakket voor beoordeling door een moderator. Meldingen gelden op pakketniveau en kunnen optioneel aan een versie worden gekoppeld. Ze worden aan de moderatiewachtrij toegevoegd, maar verbergen of blokkeren op zichzelf downloads niet automatisch; moderators moeten releasemoderatie gebruiken om artefacten goed te keuren, in quarantaine te plaatsen of in te trekken.

Authenticatie:

Vereist een API-token.

Aanvraag:

json

{ "reason": "Verdacht systeemeigen binair bestand", "version": "1.2.3" }

Respons:

json

{  "ok": true,  "reported": true,  "alreadyReported": false,  "packageId": "packages:...",  "releaseId": "packageReleases:...",  "reportCount": 1}

`GET /api/v1/packages/reports`

Moderator-/beheerdersendpoint voor de intake van pakketmeldingen.

Authenticatie:

Vereist een API-token voor een moderator- of beheerdersgebruiker.

Queryparameters:

status (optioneel): open (standaard), confirmed, dismissed of all
limit (optioneel): geheel getal (1-100)
cursor (optioneel): pagineringscursor

Respons:

json

{  "items": [    {      "reportId": "packageReports:...",      "packageId": "packages:...",      "releaseId": "packageReleases:...",      "name": "@openclaw/example-plugin",      "displayName": "Voorbeeldplugin",      "family": "code-plugin",      "version": "1.2.3",      "reason": "Verdacht systeemeigen binair bestand",      "status": "open",      "createdAt": 1730000000000,      "reporter": {        "userId": "users:...",        "handle": "reporter",        "displayName": "Melder"      },      "triagedAt": null,      "triagedBy": null,      "triageNote": null    }  ],  "nextCursor": null,  "done": true}

`GET /api/v1/packages/{name}/moderation`

Eigenaar-/moderatorendpoint voor inzicht in pakketmoderatie.

Authenticatie:

Vereist een API-token voor de pakketeigenaar, een lid van de uitgever, een moderator of een beheerdersgebruiker.

Respons:

json

{  "package": {    "packageId": "packages:...",    "name": "@openclaw/example-plugin",    "displayName": "Voorbeeldplugin",    "family": "code-plugin",    "channel": "community",    "isOfficial": false,    "reportCount": 2,    "lastReportedAt": 1730000001000,    "scanStatus": "malicious"  },  "latestRelease": {    "releaseId": "packageReleases:...",    "version": "1.2.3",    "artifactKind": "npm-pack",    "scanStatus": "malicious",    "moderationState": "quarantined",    "moderationReason": "handmatige beoordeling",    "blockedFromDownload": true,    "reasons": ["manual:quarantined", "scan:malicious", "reports:2"],    "createdAt": 1730000000000  }}

`POST /api/v1/packages/reports/{reportId}/triage`

Moderator-/beheerdersendpoint voor het afhandelen of heropenen van pakketmeldingen.

Aanvraag:

json

{  "status": "confirmed",  "note": "Beoordeeld en de betreffende release in quarantaine geplaatst.",  "finalAction": "quarantine"}

note is vereist voor confirmed en dismissed; het mag worden weggelaten wanneer status wordt teruggezet naar open. Geef finalAction: "quarantine" of finalAction: "revoke" door met een bevestigde melding om releasemoderatie toe te passen binnen dezelfde controleerbare workflow.

Respons:

json

{  "ok": true,  "reportId": "packageReports:...",  "packageId": "packages:...",  "status": "confirmed",  "reportCount": 0}

`POST /api/v1/packages/{name}/versions/{version}/moderation`

Moderator-/beheerdersendpoint voor de beoordeling van pakketreleases.

Aanvraag:

json

{ "state": "quarantined", "reason": "Verdachte systeemeigen payload." }

Ondersteunde statussen:

approved: handmatig beoordeeld en toegestaan.
quarantined: geblokkeerd in afwachting van vervolgactie.
revoked: geblokkeerd nadat een release eerder werd vertrouwd.

In quarantaine geplaatste en ingetrokken releases retourneren 403 vanuit routes voor het downloaden van artefacten. Elke wijziging schrijft een vermelding naar het auditlogboek.

`GET /api/v1/packages/{name}/file`

Retourneert de exacte opgeslagen bytes van een pakketbestand als download. Voeg preview=1 toe om dezelfde begrensde UTF-8-tekstvoorvertoning aan te vragen die voor skillbestanden wordt gebruikt.

Queryparameters:

path (vereist)
version (optioneel)
tag (optioneel)
preview=1 (optioneel; retourneert text/plain of 415 wanneer de bytes geen geldige UTF-8 vormen)

Opmerkingen:

Gebruikt standaard de nieuwste release.
Gebruikt de snelheidsbucket voor lezen, niet die voor downloads.
Limiet voor onbewerkte downloads: 10MB.
Limiet voor tekstvoorvertoning: 200KB; ondoorzichtige bestanden retourneren alleen bij voorvertoningsaanvragen 415.
Lopende VirusTotal-scans blokkeren leesacties niet; schadelijke releases kunnen elders nog steeds worden achtergehouden.
Privépakketten retourneren 404, tenzij de aanroeper de eigenaar-uitgever mag lezen.

`GET /api/v1/packages/{name}/download`

Downloadt het verouderde deterministische ZIP-archief voor een pakketrelease.

Queryparameters:

version (optioneel)
tag (optioneel)

Opmerkingen:

Gebruikt standaard de nieuwste release.
Skills leiden om naar GET /api/v1/download.
Plugin-/pakketarchieven zijn ZIP-bestanden met een package/-hoofdmap, zodat oude OpenClaw- clients blijven werken.
Deze route blijft uitsluitend ZIP ondersteunen. De route streamt geen ClawPack .tgz-bestanden.
Responsen bevatten de headers ETag, Digest, X-ClawHub-Artifact-Type en X-ClawHub-Artifact-Sha256 voor integriteitscontroles door de resolver.
Metadata die alleen voor het register bestemd is, wordt niet in het gedownloade archief geïnjecteerd.
Lopende VirusTotal-scans blokkeren downloads niet; schadelijke releases retourneren 403.
Privépakketten retourneren 404, tenzij de aanroeper de eigenaar is.

`GET /api/npm/{package}`

Retourneert een npm-compatibele packument voor pakketversies die door ClawPack worden ondersteund.

Opmerkingen:

Alleen versies met geüploade ClawPack npm-pack-tarballs worden vermeld.
Verouderde versies die uitsluitend als ZIP beschikbaar zijn, worden bewust weggelaten.
dist.tarball, dist.integrity en dist.shasum gebruiken npm-compatibele velden, zodat gebruikers npm desgewenst naar de mirror kunnen verwijzen.
Packuments van pakketten met een scope ondersteunen zowel /api/npm/@scope/name als het gecodeerde aanvraagpad /api/npm/@scope%2Fname van npm.

`GET /api/npm/{package}/-/{tarball}.tgz`

Streamt de exacte bytes van de geüploade ClawPack-tarball voor npm-mirrorclients.

Opmerkingen:

Gebruikt de snelheidsbucket voor downloads.
Downloadheaders bevatten de ClawHub SHA-256 plus npm-metadata voor integriteit en shasum.
Controles voor moderatie en toegang tot privépakketten blijven van toepassing.

`GET /api/v1/resolve`

Wordt door de CLI gebruikt om een lokale vingerafdruk aan een bekende versie te koppelen.

Queryparameters:

slug (vereist)
hash (vereist): hexadecimale sha256 van 64 tekens van de bundelvingerafdruk

Respons:

json

{ "slug": "gifgrep", "match": { "version": "1.2.2" }, "latestVersion": { "version": "1.2.3" } }

`GET /api/v1/download`

Downloadt een ZIP-bestand van een gehoste skillversie, of retourneert een overdracht naar GitHub-broncode voor een huidige door GitHub ondersteunde skill met een clean- of suspicious-scan en zonder gehoste versie.

Queryparameters:

slug (verplicht)
version (optioneel): semver-tekenreeks
tag (optioneel): tagnaam (bijv. latest)

Opmerkingen:

Als noch version noch tag is opgegeven, wordt de nieuwste versie gebruikt.
Voor zacht verwijderde versies wordt 410 geretourneerd.
Overdrachten voor door GitHub ondersteunde skills proxyen of spiegelen geen bytes. Het JSON-antwoord bevat sourceRef: "public-github", repo, commit, path, contentHash en archiveUrl; de scan-/huidige status is een toegangspoort en wordt niet als metagegevens van de geslaagde payload opgenomen.
Downloadstatistieken worden geteld als unieke identiteiten per UTC-dag (userId wanneer het API-token geldig is, anders het IP-adres).

Authenticatie-eindpunten (Bearer-token)

Alle eindpunten vereisen:

Code

Authorization: Bearer clh_...

`GET /api/v1/whoami`

Valideert het token en retourneert de gebruikershandle.

`POST /api/v1/skills`

Publiceert een nieuwe versie.

Bij voorkeur: multipart/form-data met payload-JSON + files[]-blobs.
Een JSON-body met files (op basis van storageId) wordt ook geaccepteerd.
Optioneel payloadveld: ownerHandle. Indien aanwezig, bepaalt de API die uitgever aan serverzijde en moet de actor uitgeverstoegang hebben.
Optioneel payloadveld: migrateOwner. Bij true met ownerHandle kan een bestaande skill naar die eigenaar worden verplaatst als de actor beheerder/eigenaar is bij zowel de huidige als de doeluitgever. Zonder deze expliciete toestemming worden eigenaarswijzigingen geweigerd.

`POST /api/v1/packages`

Publiceert een release van een codeplugin of bundelplugin.

Vereist authenticatie met een Bearer-token.
Vereist multipart/form-data.
Toegestane formuliervelden zijn payload, herhaalde files-blobs of één clawpack- tarballverwijzing. clawpack kan een .tgz-blob zijn of een opslag-ID dat door de upload-URL-flow is geretourneerd. Gefaseerde publicaties met een opslag-ID moeten ook de clawpackUploadTicket bevatten die met die upload-URL is geretourneerd.
Gebruik files of clawpack, nooit beide in hetzelfde verzoek.
JSON-bodies en door de aanroeper aangeleverde payload.files- / payload.artifact- metagegevens worden geweigerd.
Rechtstreekse meerdelige publicatieverzoeken zijn beperkt tot 18MB. ClawPack-tarballs kunnen de upload-URL-flow gebruiken tot de tarballlimiet van 120MB.
Optioneel payloadveld: ownerHandle. Indien aanwezig, mogen alleen beheerders namens die eigenaar publiceren.

Belangrijkste validaties:

family moet code-plugin of bundle-plugin zijn.
Pluginpakketten vereisen openclaw.plugin.json. ClawPack-uploads van .tgz moeten dit bevatten op package/openclaw.plugin.json.
Codeplugins vereisen package.json, metagegevens van de bronrepository, metagegevens van de broncommit, metagegevens van het configuratieschema, openclaw.compat.pluginApi en openclaw.build.openclawVersion.
openclaw.hostTargets en openclaw.environment zijn optionele metagegevens.
Alleen de organisatie-uitgever openclaw en de persoonlijke uitgevers van huidige leden van de organisatie openclaw mogen naar het kanaal official publiceren.
Bij publicaties namens anderen wordt de geschiktheid voor het officiële kanaal nog steeds aan de hand van het doeleigenaarsaccount gevalideerd.

`DELETE /api/v1/skills/{slug}` / `POST /api/v1/skills/{slug}/undelete`

Een skill zacht verwijderen / herstellen (eigenaar, moderator of beheerder).

Optionele JSON-body:

json

{ "reason": "Vastgehouden voor moderatie in afwachting van juridische beoordeling." }

Indien aanwezig, wordt reason opgeslagen als moderatienotitie van de skill en naar het auditlogboek gekopieerd. Door de eigenaar geïnitieerde zachte verwijderingen reserveren de slug 30 dagen, waarna een andere uitgever de slug kan claimen. Het verwijderingsantwoord bevat slugReservedUntil wanneer deze vervaldatum van toepassing is. Verbergingen door moderators/beheerders en verwijderingen om veiligheidsredenen verlopen niet op deze manier.

Verwijderingsantwoord:

json

{ "ok": true, "slugReservedUntil": 1730000000000 }

Statuscodes:

200: geslaagd
401: niet geautoriseerd
403: verboden
404: skill/gebruiker niet gevonden
500: interne serverfout

`POST /api/v1/users/publisher`

Alleen voor beheerders. Zorgt dat er een organisatie-uitgever voor een handle bestaat. Als de handle nog naar een oude gedeelde gebruiker/persoonlijke uitgever verwijst, migreert het eindpunt deze eerst naar een organisatie-uitgever. Geef voor een nieuw aangemaakte organisatie memberHandle op; de handelende beheerder wordt niet als lid toegevoegd. memberRole is standaard owner.

Body: { "handle": "openclaw", "displayName": "OpenClaw", "memberHandle": "alice", "memberRole": "owner", "trusted": true }
Antwoord: { "ok": true, "publisherId": "...", "handle": "openclaw", "created": true, "migrated": false, "trusted": true, "member": { "userId": "...", "handle": "alice", "role": "owner" } }

`POST /api/v1/publishers`

Geauthenticeerde selfservice voor het aanmaken van een organisatie-uitgever. Maakt een nieuwe organisatie-uitgever aan en voegt de aanroeper als eigenaar toe. Dit eindpunt migreert geen bestaande gebruikers-/persoonlijke handles en markeert de uitgever niet als vertrouwd/officieel.

Body: { "handle": "opik", "displayName": "Opik" }
Antwoord: { "ok": true, "publisherId": "...", "handle": "opik", "created": true, "trusted": false }
Retourneert 409 wanneer de handle al door een uitgever, gebruiker of persoonlijke uitgever wordt gebruikt.

`POST /api/v1/users/reserve`

Alleen voor beheerders. Reserveert hoofdslugs en pakketnamen voor de rechtmatige eigenaar zonder een release te publiceren. Pakketnamen worden persoonlijke tijdelijke pakketten zonder releaseregels, zodat dezelfde eigenaar later de echte release van de codeplugin of bundelplugin onder die naam kan publiceren.

Body: { "handle": "openclaw", "slugs": ["diffs"], "packageNames": ["@openclaw/diffs"], "reason": "reserved for official OpenClaw plugin" }
Antwoord: { "ok": true, "succeeded": 2, "failed": 0, "results": [{ "kind": "slug", "name": "diffs", "ok": true, "action": "reserved" }] }

`POST /api/v1/users/publisher-recovery`

Alleen voor beheerders. Herstelt een persoonlijke uitgever voor een geverifieerde vervangende GitHub OAuth-principal zonder Convex Auth-accountregels te bewerken. Het verzoek moet beide onveranderlijke GitHub- provideraccount-ID's noemen; veranderlijke handles worden alleen gebruikt als beveiliging voor de operator.

Het eindpunt voert standaard een testuitvoering uit. Voor het toepassen van het herstel zijn dryRun: false en confirmIdentityVerified: true vereist nadat medewerkers onafhankelijk de continuïteit tussen beide GitHub-principals hebben geverifieerd. Het herstel mislukt veilig wanneer de huidige persoonlijke uitgever van de doelgebruiker skills, pakketten of GitHub-skillbronnen heeft. Het herstel migreert ook oude ownerUserId-velden voor de skills van de herstelde uitgever, skill-slugaliassen, pakketten, pakketinspectiewaarschuwingen en afgeleide zoekdigestregels, zodat paden voor directe eigenaren overeenkomen met de nieuwe uitgeversbevoegdheid. Een actieve reservering voor de beveiligde handle van de herstelde handle wordt ook opnieuw toegewezen aan de vervangende gebruiker, zodat latere profielsynchronisatie de concurrerende bevoegdheid van de voormalige gebruiker niet kan herstellen. Elke primaire tabel is beperkt tot 100 regels per toepassingstransactie; grotere herstelacties moeten eerst een hervatbare eigenaarsmigratie gebruiken. GitHub-skillbronnen vallen onder de uitgever en worden als gecontroleerd gerapporteerd in plaats van herschreven.

Body: { "handle": "gingiris", "nextUserHandle": "gingiris-1031", "previousGitHubProviderAccountId": "123", "nextGitHubProviderAccountId": "456", "reason": "Verified account continuity for issue #2555", "confirmIdentityVerified": true, "dryRun": false }
Antwoord: { "ok": true, "dryRun": false, "recovered": true, "publisherId": "...", "handle": "gingiris", "previousUser": { "userId": "...", "handle": "gingiris", "nextHandle": "gingiris-recovered", "githubProviderAccountId": "123", "authAccountCount": 1 }, "nextUser": { "userId": "...", "handle": "gingiris-1031", "nextHandle": "gingiris", "githubProviderAccountId": "456", "authAccountCount": 1 }, "retiredPersonalPublisher": null, "resourceOwnerMigration": { "limitPerTable": 100, "skills": 1, "skillSlugAliases": 1, "packages": 0, "packageInspectorWarnings": 0, "githubSourcesChecked": 1, "handleReservations": 1 }, "identityVerified": true, "reason": "Verified account continuity for issue #2555" }

Eindpunten voor beheer van eigenaars-slugs

POST /api/v1/skills/{slug}/rename
- Body: { "newSlug": "new-canonical-slug" }
- Antwoord: { "ok": true, "slug": "new-canonical-slug", "previousSlug": "old-slug" }
POST /api/v1/skills/{slug}/merge
- Body: { "targetSlug": "canonical-target-slug" }
- Antwoord: { "ok": true, "sourceSlug": "old-slug", "targetSlug": "canonical-target-slug" }

Opmerkingen:

Beide eindpunten vereisen authenticatie met een API-token en werken alleen voor de eigenaar van de skill.
rename behoudt de vorige slug als omleidingsalias.
merge verbergt de bronvermelding en leidt de bronslug om naar de doelvermelding.

Eindpunten voor eigendomsoverdracht

POST /api/v1/skills/{slug}/transfer
- Body: { "toUserHandle": "target_handle", "message": "optional" }
- Antwoord: { "ok": true, "transferId": "skillOwnershipTransfers:...", "toUserHandle": "target_handle", "expiresAt": 1730000000000 }
POST /api/v1/skills/{slug}/transfer/accept
POST /api/v1/skills/{slug}/transfer/reject
POST /api/v1/skills/{slug}/transfer/cancel
- Antwoord (accepteren/weigeren/annuleren): { "ok": true, "skillSlug": "demo-skill?" }
GET /api/v1/transfers/incoming
GET /api/v1/transfers/outgoing
- Antwoordstructuur: { "transfers": [{ "_id": "...", "skill": { "slug": "demo", "displayName": "Demo" }, "fromUser"|"toUser": { "handle": "..." }, "message": "...", "requestedAt": 0, "expiresAt": 0 }] }

`POST /api/v1/users/ban`

Een gebruiker verbannen en skills waarvan deze eigenaar is permanent verwijderen (alleen moderator/beheerder).

Body:

json

{ "handle": "user_handle", "reason": "optionele reden voor verbanning" }

json

{ "userId": "users_...", "reason": "optionele reden voor verbanning" }

Antwoord:

json

{ "ok": true, "alreadyBanned": false, "deletedSkills": 3 }

`POST /api/v1/users/unban`

De verbanning van een gebruiker opheffen en in aanmerking komende skills herstellen (alleen beheerder).

Body:

json

{ "handle": "user_handle", "reason": "optionele reden voor opheffing van verbanning" }

json

{ "userId": "users_...", "reason": "optionele reden voor opheffing van verbanning" }

Antwoord:

json

{ "ok": true, "alreadyUnbanned": false, "restoredSkills": 3 }

`POST /api/v1/users/reclassify-ban`

De opgeslagen reden voor een bestaande verbanning wijzigen zonder de verbanning op te heffen of inhoud te herstellen (alleen beheerder). Voert standaard een testuitvoering uit, tenzij dryRun gelijk is aan false.

Body:

json

{ "handle": "user_handle", "reason": "spam door massapublicatie", "dryRun": true }

json

{ "userId": "users_...", "reason": "spam door massapublicatie", "dryRun": false }

Antwoord:

json

{  "ok": true,  "dryRun": false,  "userId": "users_...",  "handle": "user_handle",  "previousReason": "automatische verbanning wegens malware",  "nextReason": "spam door massapublicatie",  "changed": true}

`POST /api/v1/users/role`

Een gebruikersrol wijzigen (alleen beheerder).

Body:

json

{ "handle": "user_handle", "role": "moderator" }

json

{ "userId": "users_...", "role": "admin" }

Antwoord:

json

{ "ok": true, "role": "moderator" }

`GET /api/v1/users`

Gebruikers weergeven of zoeken (alleen beheerder).

Queryparameters:

q (optioneel): zoekopdracht
query (optioneel): alias voor q
limit (optioneel): maximumaantal resultaten (standaard 20, maximaal 200)

Antwoord:

json

{  "items": [    {      "userId": "users_...",      "handle": "user_handle",      "displayName": "Gebruiker",      "name": "Gebruiker",      "role": "moderator"    }  ],  "total": 1}

`POST /api/v1/stars/{slug}` / `DELETE /api/v1/stars/{slug}`

Een bladwijzer toevoegen/verwijderen. De oude stars-route en namen van antwoordvelden blijven beschikbaar voor compatibiliteit. Beide eindpunten zijn idempotent.

Antwoorden:

json

{ "ok": true, "starred": true, "alreadyStarred": false }

json

{ "ok": true, "unstarred": true, "alreadyUnstarred": false }

Oude CLI-eindpunten (afgeschaft)

Nog steeds ondersteund voor oudere CLI-versies:

GET /api/cli/whoami
POST /api/cli/upload-url
POST /api/cli/publish
POST /api/cli/telemetry/install
POST /api/cli/skill/delete
POST /api/cli/skill/undelete

Zie DEPRECATIONS.md voor het verwijderingsplan.

POST /api/cli/upload-url retourneert uploadUrl en uploadTicket. Pakketpublicaties die een ClawPack-tarball klaarzetten, moeten het resulterende opslag-ID als clawpack en het geretourneerde ticket als clawpackUploadTicket verzenden.

Registerdetectie (`/.well-known/clawhub.json`)

De CLI kan register-/authenticatie-instellingen via de site vinden:

/.well-known/clawhub.json (JSON, bij voorkeur)
/.well-known/clawdhub.json (oud)

Schema:

json

{ "apiBase": "https://clawhub.ai", "authBase": "https://clawhub.ai", "minCliVersion": "0.0.5" }

Als je zelf host, bied je dit bestand aan (of stel je CLAWHUB_REGISTRY expliciet in; voorheen CLAWDHUB_REGISTRY).

Was this useful?

HTTP-API

Hergebruik van de openbare catalogus

Frequentielimieten

Foutresponsen

Openbare endpoints (geen verificatie)

GET /api/v1/search

GET /api/v1/skills

GET /api/v1/skills/{slug}

GET /api/v1/skills/{slug}/moderation

POST /api/v1/skills/{slug}/report

GET /api/v1/skills/-/reports

POST /api/v1/skills/-/reports/{reportId}/triage

GET /api/v1/skills/{slug}/versions

GET /api/v1/skills/{slug}/versions/{version}

GET /api/v1/skills/{slug}/scan

POST /api/v1/skills/-/scan

GET /api/v1/skills/-/scan/{scanId}

GET /api/v1/skills/-/scan/{scanId}/download

GET /api/v1/skills/-/scan/download/{name}?version=<version>&kind=skill|plugin

POST /api/v1/skills/-/scan/batch

POST /api/v1/skills/-/scan/batch/status

GET /api/v1/skills/{slug}/verify

POST /api/v1/skills/-/security-verdicts

GET /api/v1/skills/{slug}/file

GET /api/v1/packages

GET /api/v1/packages/search

GET /api/v1/plugins

GET /api/v1/skills/export

GET /api/v1/plugins/export

GET /api/v1/plugins/search

GET /api/v1/packages/{name}

DELETE /api/v1/packages/{name}

GET /api/v1/packages/{name}/versions

GET /api/v1/packages/{name}/versions/{version}

GET /api/v1/packages/{name}/versions/{version}/security

GET /api/v1/packages/{name}/versions/{version}/artifact

GET /api/v1/packages/{name}/versions/{version}/artifact/download

GET /api/v1/packages/{name}/readiness

GET /api/v1/packages/migrations

POST /api/v1/packages/migrations

GET /api/v1/packages/moderation/queue

POST /api/v1/packages/{name}/report

GET /api/v1/packages/reports

GET /api/v1/packages/{name}/moderation

POST /api/v1/packages/reports/{reportId}/triage

POST /api/v1/packages/{name}/versions/{version}/moderation

GET /api/v1/packages/{name}/file

GET /api/v1/packages/{name}/download

GET /api/npm/{package}

GET /api/npm/{package}/-/{tarball}.tgz

GET /api/v1/resolve

GET /api/v1/download

Authenticatie-eindpunten (Bearer-token)

GET /api/v1/whoami

POST /api/v1/skills

POST /api/v1/packages

DELETE /api/v1/skills/{slug} / POST /api/v1/skills/{slug}/undelete

POST /api/v1/users/publisher

POST /api/v1/publishers

POST /api/v1/users/reserve

POST /api/v1/users/publisher-recovery

Eindpunten voor beheer van eigenaars-slugs

Eindpunten voor eigendomsoverdracht

POST /api/v1/users/ban

POST /api/v1/users/unban

POST /api/v1/users/reclassify-ban

POST /api/v1/users/role

GET /api/v1/users

POST /api/v1/stars/{slug} / DELETE /api/v1/stars/{slug}

Oude CLI-eindpunten (afgeschaft)

Registerdetectie (/.well-known/clawhub.json)

On this page

`GET /api/v1/search`

`GET /api/v1/skills`

`GET /api/v1/skills/{slug}`

`GET /api/v1/skills/{slug}/moderation`

`POST /api/v1/skills/{slug}/report`

`GET /api/v1/skills/-/reports`

`POST /api/v1/skills/-/reports/{reportId}/triage`

`GET /api/v1/skills/{slug}/versions`

`GET /api/v1/skills/{slug}/versions/{version}`

`GET /api/v1/skills/{slug}/scan`

`POST /api/v1/skills/-/scan`

`GET /api/v1/skills/-/scan/{scanId}`

`GET /api/v1/skills/-/scan/{scanId}/download`

`GET /api/v1/skills/-/scan/download/{name}?version=<version>&kind=skill|plugin`

`POST /api/v1/skills/-/scan/batch`

`POST /api/v1/skills/-/scan/batch/status`

`GET /api/v1/skills/{slug}/verify`

`POST /api/v1/skills/-/security-verdicts`

`GET /api/v1/skills/{slug}/file`

`GET /api/v1/packages`

`GET /api/v1/packages/search`

`GET /api/v1/plugins`

`GET /api/v1/skills/export`

`GET /api/v1/plugins/export`

`GET /api/v1/plugins/search`

`GET /api/v1/packages/{name}`

`DELETE /api/v1/packages/{name}`

`GET /api/v1/packages/{name}/versions`

`GET /api/v1/packages/{name}/versions/{version}`

`GET /api/v1/packages/{name}/versions/{version}/security`

`GET /api/v1/packages/{name}/versions/{version}/artifact`

`GET /api/v1/packages/{name}/versions/{version}/artifact/download`

`GET /api/v1/packages/{name}/readiness`

`GET /api/v1/packages/migrations`

`POST /api/v1/packages/migrations`

`GET /api/v1/packages/moderation/queue`

`POST /api/v1/packages/{name}/report`

`GET /api/v1/packages/reports`

`GET /api/v1/packages/{name}/moderation`

`POST /api/v1/packages/reports/{reportId}/triage`

`POST /api/v1/packages/{name}/versions/{version}/moderation`

`GET /api/v1/packages/{name}/file`

`GET /api/v1/packages/{name}/download`

`GET /api/npm/{package}`

`GET /api/npm/{package}/-/{tarball}.tgz`

`GET /api/v1/resolve`

`GET /api/v1/download`

`GET /api/v1/whoami`

`POST /api/v1/skills`

`POST /api/v1/packages`

`DELETE /api/v1/skills/{slug}` / `POST /api/v1/skills/{slug}/undelete`

`POST /api/v1/users/publisher`

`POST /api/v1/publishers`

`POST /api/v1/users/reserve`

`POST /api/v1/users/publisher-recovery`

`POST /api/v1/users/ban`

`POST /api/v1/users/unban`

`POST /api/v1/users/reclassify-ban`

`POST /api/v1/users/role`

`GET /api/v1/users`

`POST /api/v1/stars/{slug}` / `DELETE /api/v1/stars/{slug}`

Registerdetectie (`/.well-known/clawhub.json`)