---
read_when:
    - Uç noktaları ekleme/değiştirme
    - CLI ↔ kayıt defteri isteklerinde hata ayıklama
summary: HTTP API referansı (genel + CLI uç noktaları + kimlik doğrulama).
x-i18n:
    generated_at: "2026-07-26T22:36:34Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 5b180bbd56d20a3d88c1fe74ccab0fd0ecbe0e8c9624cd1afd2070a2ca1f7fb3
    source_path: clawhub/http-api.md
    workflow: 16
---

# HTTP API

Temel URL: `https://clawhub.ai` (varsayılan).

Tüm v1 yolları `/api/v1/...` altındadır.
Eski `/api/...` ve `/api/cli/...` uyumluluk için korunmaktadır (bkz. `DEPRECATIONS.md`).
OpenAPI: `/api/v1/openapi.json`.

## Herkese açık kataloğun yeniden kullanımı

Üçüncü taraf dizinler, ClawHub Skills öğelerini listelemek veya aramak için herkese açık okuma uç noktalarını kullanabilir. Lütfen sonuçları önbelleğe alın, `429`/`Retry-After` kurallarına uyun, kullanıcıları standart ClawHub listesine (`https://clawhub.ai/<owner>/skills/<slug>`) geri yönlendirin ve ClawHub'ın üçüncü taraf siteyi desteklediği izlenimini vermekten kaçının. Gizli, özel veya moderasyon tarafından engellenmiş içerikleri herkese açık API yüzeyinin dışında yansıtmaya çalışmayın.

Web kısa ad kısayolları kayıt defteri aileleri arasında çözümlenir, ancak API istemcileri yol
önceliğini yeniden oluşturmak yerine okuma uç noktalarının döndürdüğü standart URL'leri
kullanmalıdır.

## Hız sınırları

Uygulama modeli:

- Anonim istekler: IP başına uygulanır.
- Kimliği doğrulanmış istekler (geçerli Bearer belirteci): kullanıcı kovası başına uygulanır.
- Belirteç eksik veya geçersizse davranış, IP tabanlı uygulamaya geri döner.
- Kimliği doğrulanmış yazma uç noktaları, sunucu nedeni biliyorsa yalnızca `Unauthorized` döndürmemelidir.
  Eksik belirteçler, geçersiz/iptal edilmiş belirteçler ve silinmiş/yasaklanmış/devre dışı bırakılmış
  hesapların her biri, CLI istemcilerinin kullanıcılara kendilerini neyin engellediğini
  bildirebilmesi için eyleme geçirilebilir metin almalıdır.

- Okuma: IP başına 3000/dk., anahtar başına 12000/dk.
- Yazma: IP başına 300/dk., anahtar başına 3000/dk.
- İndirme: IP başına 1200/dk., anahtar başına 6000/dk. (indirme uç noktaları)

Üstbilgiler:

- Eski uyumluluk: `X-RateLimit-Limit`, `X-RateLimit-Reset`
- Standartlaştırılmış: `RateLimit-Limit`, `RateLimit-Reset`
- `429` durumunda: `X-RateLimit-Remaining: 0` ve `RateLimit-Remaining: 0`
- `429` durumunda: `Retry-After`

Üstbilgi anlamları:

- `X-RateLimit-Reset`: mutlak Unix epoch saniyesi
- `RateLimit-Reset`: sıfırlamaya kadar geçen saniye (gecikme)
- `X-RateLimit-Remaining` / `RateLimit-Remaining`: mevcut olduğunda kalan kesin bütçe.
  Parçalanmış başarılı istekler, yaklaşık bir genel değer döndürmek yerine bu üstbilgiyi atlar.
- `Retry-After`: `429` durumunda yeniden denemeden önce beklenecek saniye (gecikme)

Örnek `429` yanıtı:

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

Hız sınırı aşıldı
```

İstemci rehberi:

- `Retry-After` mevcutsa yeniden denemeden önce belirtilen saniye kadar bekleyin.
- Eş zamanlı yeniden denemeleri önlemek için rastgele sapmalı geri çekilme kullanın.
- `Retry-After` eksikse `RateLimit-Reset` değerine geri dönün (veya `X-RateLimit-Reset` üzerinden hesaplayın).

IP kaynağı:

- `cf-connecting-ip` dahil güvenilir istemci IP üstbilgilerini yalnızca
  dağıtım, güvenilir iletilmiş üstbilgileri açıkça etkinleştirdiğinde kullanır.
- ClawHub, istemci IP'lerini uçta belirlemek için güvenilir iletme üstbilgilerini kullanır.
- Güvenilir bir istemci IP'si yoksa anonim istekler, yalnızca hız sınırı türüne
  göre kapsamlandırılmış yedek kovaları kullanır. Bu yedek kovalar; çağıran tarafından sağlanan
  yolları, kısa adları, paket adlarını, sürümleri, sorgu dizelerini veya diğer
  yapıt parametrelerini içermez.

## Hata yanıtları

Herkese açık v1 hata yanıtları `content-type: text/plain; charset=utf-8` ile düz metindir.
Buna doğrulama hataları (`400`), eksik herkese açık kaynaklar (`404`), kimlik doğrulama ve
izin hataları (`401`/`403`), hız sınırları (`429`) ve engellenmiş indirmeler dahildir. İstemciler
yanıt gövdesini insanlar tarafından okunabilir bir dize olarak okumalıdır. Bilinmeyen sorgu parametreleri
uyumluluk için yok sayılır, ancak geçersiz değerlere sahip tanınan sorgu parametreleri
`400` döndürür.

## Herkese açık uç noktalar (kimlik doğrulama yok)

### `GET /api/v1/search`

Sorgu parametreleri:

- `q` (gerekli): sorgu dizesi
- `limit` (isteğe bağlı): tam sayı
- `highlightedOnly` (isteğe bağlı): öne çıkarılan Skills öğelerine göre filtrelemek için `true`
- `nonSuspiciousOnly` (isteğe bağlı): şüpheli (`flagged.suspicious`) Skills öğelerini gizlemek için `true`
- `nonSuspicious` (isteğe bağlı): `nonSuspiciousOnly` için eski takma ad

Yanıt:

```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"
      }
    }
  ]
}
```

Notlar:

- Sonuçlar ilgi sırasına göre döndürülür (gömme benzerliği + tam kısa ad/ad belirteci destekleri + küçük bir popülerlik önceliği).
- İlgi, popülerlikten daha güçlüdür. Kesin bir kısa ad veya görünen ad belirteci eşleşmesi, etkileşimi çok daha güçlü olan daha gevşek bir eşleşmeden üst sırada yer alabilir.
- ASCII metni, sözcük ve noktalama sınırlarında belirteçlere ayrılır. Örneğin `personal-map` bağımsız bir `map` belirteci içerirken `amap-jsapi-skill`; `amap`, `jsapi` ve `skill` içerir; bu nedenle `map` araması, `personal-map` için `amap-jsapi-skill` değerinden daha güçlü bir sözcüksel eşleşme sağlar.
- Popülerlik logaritmik olarak ölçeklendirilir ve sınırlandırılır. Yüksek etkileşimli Skills öğeleri, sorgu metniyle eşleşme daha zayıf olduğunda daha alt sırada yer alabilir.
- Şüpheli veya gizli moderasyon durumu, çağıran filtrelerine ve mevcut moderasyon durumuna bağlı olarak bir Skill öğesini herkese açık aramadan kaldırabilir.

Yayıncıların bulunabilirliğine ilişkin rehber:

- Kullanıcıların tam olarak arayacağı terimleri görünen ada, özete ve etiketlere ekleyin. Bağımsız bir kısa ad belirtecini yalnızca korumak istediğiniz kararlı bir kimlikse kullanın.
- Yeni kısa ad uzun vadede daha iyi bir standart ad olmadığı sürece yalnızca tek bir sorgunun peşinden gitmek için kısa adı değiştirmeyin. Eski kısa adlar yönlendirme takma adlarına dönüşür, ancak standart URL, görüntülenen kısa ad ve gelecekteki arama özetleri yeni kısa adı kullanır.
- Yeniden adlandırma takma adları, kayıt defteri üzerinden çözümlenen eski URL'ler ve kurulumlar için çözümlemeyi korur; ancak arama sıralaması, yeniden adlandırma dizine eklendikten sonra standart Skill meta verilerine dayanır. Mevcut istatistikler Skill öğesiyle birlikte kalır.
- Bir Skill öğesi beklenmedik biçimde görünmüyorsa sıralamayla ilgili meta verileri değiştirmeden önce oturum açmış durumdayken `clawhub inspect @owner/slug` ile moderasyon durumunu kontrol edin.

### `GET /api/v1/skills`

Sorgu parametreleri:

- `limit` (isteğe bağlı): tam sayı (1–200)
- `cursor` (isteğe bağlı): `trending` dışındaki herhangi bir sıralama için sayfalama imleci
- `sort` (isteğe bağlı): `updated` (varsayılan), `recommended` (takma ad: `default`), `createdAt` (takma ad: `newest`), `downloads`, `stars` (takma ad: `rating`), eski kurulum takma adları `installsCurrent`/`installs`/`installsAllTime`, `downloads` değerine eşlenir, `trending`
- `nonSuspiciousOnly` (isteğe bağlı): şüpheli (`flagged.suspicious`) Skills öğelerini gizlemek için `true`
- `nonSuspicious` (isteğe bağlı): `nonSuspiciousOnly` için eski takma ad

Geçersiz `sort` değerleri `400` döndürür.

Notlar:

- `recommended`, etkileşim ve güncellik sinyallerini kullanır.
- `trending`, son 7 gündeki kurulumlara göre sıralar (telemetri tabanlı).
- `createdAt`, yeni Skill taramaları için kararlıdır; mevcut Skills öğeleri yeniden yayımlandığında `updated` değişir.
- `nonSuspiciousOnly=true` olduğunda imleç tabanlı sıralamalar, şüpheli Skills öğeleri sayfa alındıktan sonra filtrelendiği için bir sayfada `limit` öğeden daha azını döndürebilir.
- Mevcut olduğunda sayfalamaya devam etmek için `nextCursor` kullanın. Kısa bir sayfa tek başına sonuçların sona erdiği anlamına gelmez.

Yanıt:

```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}`

Yanıt:

```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
  }
}
```

Notlar:

- Sahibin yeniden adlandırma/birleştirme akışlarıyla oluşturulan eski kısa adlar standart Skill öğesine çözümlenir.
- `metadata.os`: Skill ön bilgilerinde belirtilen işletim sistemi kısıtlamaları (ör. `["macos"]`, `["linux"]`). Belirtilmemişse `null`.
- `metadata.systems`: Nix sistem hedefleri (ör. `["aarch64-darwin", "x86_64-linux"]`). Belirtilmemişse `null`.
- Skill öğesinin platform meta verisi yoksa `metadata`, `null` değeridir.
- `moderation` yalnızca Skill öğesi işaretlendiğinde veya sahibi görüntülediğinde dahil edilir.

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

Yapılandırılmış moderasyon durumunu döndürür.

Yanıt:

```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": ""
      }
    ]
  }
}
```

Notlar:

- Sahipler ve moderatörler, gizli Skills öğelerinin moderasyon ayrıntılarına erişebilir.
- Herkese açık çağıranlar yalnızca önceden işaretlenmiş görünür Skills öğeleri için `200` alır.
- Kanıtlar herkese açık çağıranlar için sansürlenir ve ham parçacıkları yalnızca sahipler/moderatörler için içerir.

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

Bir Skill öğesini moderatör incelemesi için bildirin. Bildirimler Skill düzeyindedir, isteğe bağlı olarak
bir sürüme bağlanır ve Skill bildirim kuyruğuna aktarılır.

Kimlik doğrulama:

- Bir API belirteci gerektirir.

İstek:

```json
{ "reason": "Şüpheli kurulum adımı", "version": "1.2.3" }
```

Yanıt:

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

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

Skill bildirimlerini almak için moderatör/yönetici uç noktası.

Sorgu parametreleri:

- `status` (isteğe bağlı): `open` (varsayılan), `confirmed`, `dismissed` veya `all`
- `limit` (isteğe bağlı): tam sayı (1-200)
- `cursor` (isteğe bağlı): sayfalama imleci

Yanıt:

```json
{
  "items": [
    {
      "reportId": "skillReports:...",
      "skillId": "skills:...",
      "skillVersionId": "skillVersions:...",
      "slug": "gifgrep",
      "displayName": "GifGrep",
      "version": "1.2.3",
      "reason": "Şüpheli yükleme adımı",
      "status": "open",
      "createdAt": 1730000000000,
      "reporter": {
        "userId": "users:...",
        "handle": "reporter",
        "displayName": "Bildiren"
      },
      "triagedAt": null,
      "triagedBy": null,
      "triageNote": null
    }
  ],
  "nextCursor": null,
  "done": true
}
```

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

Skill raporlarını çözümlemeye veya yeniden açmaya yönelik moderatör/yönetici uç noktası.

İstek:

```json
{ "status": "confirmed", "note": "İncelendi ve etkilenen sürüm gizlendi.", "finalAction": "hide" }
```

`note`, `confirmed` ve `dismissed` için gereklidir; `status`
yeniden `open` olarak ayarlanırken atlanabilir. Skill'i aynı denetlenebilir iş akışında
gizlemek için triyaj edilmiş bir raporla `finalAction: "hide"` iletin.

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

Sorgu parametreleri:

- `limit` (isteğe bağlı): tam sayı
- `cursor` (isteğe bağlı): sayfalama imleci

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

Sürüm meta verilerini ve dosya listesini döndürür.

- `version.security`, mevcut olduğunda normalleştirilmiş tarama doğrulama durumunu ve
  tarayıcı ayrıntılarını (VirusTotal + LLM) içerir.

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

Bir skill sürümünün güvenlik taraması doğrulama ayrıntılarını döndürür.

Sorgu parametreleri:

- `version` (isteğe bağlı): belirli sürüm dizesi.
- `tag` (isteğe bağlı): etiketlenmiş bir sürümü çözümle (örneğin `latest`).

Notlar:

- Ne `version` ne de `tag` sağlanmışsa en son sürümü kullanır.
- Normalleştirilmiş doğrulama durumunun yanı sıra tarayıcıya özgü ayrıntıları içerir.
- `security.hasScanResult`, yalnızca bir tarayıcı kesin bir karar (`clean`, `suspicious` veya `malicious`) ürettiğinde `true` olur.
- `moderation`, en son sürümden türetilmiş güncel bir skill düzeyi moderasyon anlık görüntüsüdür.
- Geçmiş bir sürümü sorgularken `moderation` ve `security` değerlerini aynı sürüm bağlamı olarak değerlendirmeden önce `moderation.matchesRequestedVersion` ve `moderation.sourceVersion` değerlerini kontrol edin.

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

Yeni ClawScan işleri için kimliği doğrulanmış gönderim uç noktası.

Yerel yükleme taramaları artık desteklenmemektedir. `multipart/form-data` veya
`{ "source": { "kind": "upload" } }` kullanan istekler `410` döndürür.

Yayımlanmış taramalar JSON kullanır:

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

Notlar:

- Tarama isteği yükleri ve indirilebilir raporlar, saklama süresinin ardından tarama isteği deposundan silinir.
- Yayımlanmış taramalar, sahip/yayımcı yönetim erişimi veya platform moderatörü/yöneticisi yetkisi gerektirir.
- Yayımlanmış taramalar yalnızca `update: true` olduğunda ve tarama başarıyla tamamlandığında geri yazar.
- Yanıt, `{ "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." } }` ile birlikte `202` olur.
- Tarama işleri eşzamansızdır. Manuel tarama isteklerine normal yayımlama/geriye dönük doldurma işlerinden önce öncelik verilir ancak tamamlanma yine de çalışan kullanılabilirliğine bağlıdır.

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

Gönderilmiş bir tarama için kimliği doğrulanmış yoklama uç noktası.

- Kuyrukta/çalışıyor/başarılı/başarısız durumunu döndürür.
- İstemcilerin isteğin önünde kaç öncelikli manuel tarama bulunduğunu gösterebilmesi için kuyruktayken `queue.queuedAhead` ve `queue.position` döndürür. Çok büyük kuyruklar sınırlandırılır ve `queuedAheadIsEstimate: true` ile bildirilir.
- Mevcut olduğunda `report`; `clawscan`, `skillspector`, `staticAnalysis` ve `virustotal` bölümlerini içerir.
- Başarısız tarama işleri, `lastError` ile birlikte `status: "failed"` döndürür.

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

Kimliği doğrulanmış rapor arşivi uç noktası.

- Başarılı bir tarama gerektirir; sonlanmamış taramalar `409` döndürür.
- `manifest.json`, `clawscan.json`, `skillspector.json`, `static-analysis.json`, `virustotal.json` ve `README.md` içeren bir ZIP döndürür.

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

Gönderilmiş sürümler için kimliği doğrulanmış, depolanmış rapor arşivi uç noktası.

- Skill veya plugin için sahip/yayımcı yönetim erişimi ya da platform moderatörü/yöneticisi yetkisi gerektirir.
- Engellenmiş veya gizlenmiş sürümler dahil, gönderilen tam sürümün depolanmış tarama sonuçlarını döndürür.
- `kind` varsayılan olarak `skill` değerini alır; plugin/paket taramaları için `kind=plugin` kullanın.
- Tarama isteği indirmeleriyle aynı ZIP yapısını döndürür.

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

Yalnızca yöneticilere açık standart toplu yeniden tarama rotası. Eski `POST /api/v1/skills/-/rescan-batch` ile aynı yük yapısını kabul eder.

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

Yalnızca yöneticilere açık standart toplu durum rotası. `{ "jobIds": ["..."] }` değerini kabul eder ve eski `POST /api/v1/skills/-/rescan-batch/status` ile aynı toplu sayaçları döndürür.

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

`clawhub skill verify` tarafından kullanılan Skill Card doğrulama zarfını döndürür.

Sorgu parametreleri:

- `version` (isteğe bağlı): belirli sürüm dizesi.
- `tag` (isteğe bağlı): etiketlenmiş bir sürümü çözümle (örneğin `latest`).

Notlar:

- `ok`, yalnızca seçilen sürümde oluşturulmuş bir Skill Card bulunduğunda, sürüm moderasyon tarafından kötü amaçlı yazılım nedeniyle engellenmediğinde ve ClawScan doğrulaması temiz olduğunda `true` olur.
- Skill kimliği, yayımcı kimliği ve seçilen sürüm meta verileri, kabuk otomasyonunun iç içe sarmalayıcıları açmadan bunları okuyabilmesi için üst düzey zarf alanlarıdır (`slug`, `displayName`, `publisherHandle`, `version`, `resolvedFrom`, `tag`, `createdAt`).
- `security`, üst düzey ClawScan/güvenlik kararıdır. Otomasyon, `ok`, `decision`, `reasons` ve `security.status` değerlerini temel almalıdır.
- `security.signals`; `staticScan`, `virusTotal` ve `skillSpector` gibi destekleyici tarayıcı kanıtlarını içerir.
- `security.signals.dependencyRegistry`, v1 yanıt uyumluluğu için korunur ancak bağımlılık kayıt defteri varlık tarayıcısı kullanımdan kaldırılmıştır ve bu anahtar her zaman `null` olur.
- `provenance`, yalnızca ClawHub yayımlama veya içe aktarma sırasında bir GitHub deposunu/referansını/işlemesini/yolunu çözümleyip depoladığında `server-resolved-github-import` olur; aksi takdirde `unavailable` olur.

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

Tam skill sürümlerinin güncel, kompakt güvenlik kararlarını döndürür. Bu
koleksiyon uç noktası, OpenClaw Control UI gibi görüntülemesi gereken kurulu
ClawHub skill sürümlerini zaten bilen istemciler için tasarlanmıştır.

İstek:

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

Notlar:

- `items`, 1-100 benzersiz `{ slug, version }` çifti içermelidir.
- Sonuçlar öğe bazındadır; eksik tek bir skill veya sürüm tüm yanıtın başarısız olmasına neden olmaz.
- Yanıt yalnızca güvenlik verilerini içerir. Skill Card verilerini, oluşturulmuş kart durumunu, yapıt dosyası listelerini veya ayrıntılı tarayıcı yüklerini içermez.
- `security.signals` yalnızca durum düzeyinde destekleyici kanıt içerir; tüm tarayıcı ayrıntıları için `/scan` veya ClawHub güvenlik denetimi sayfasını kullanın.
- `security.signals.dependencyRegistry`, v1 yanıt uyumluluğu için korunur ancak bağımlılık kayıt defteri varlık tarayıcısı kullanımdan kaldırılmıştır ve bu anahtar her zaman `null` olur.
- Skill Card'ın bulunmaması bu uç noktanın `ok`, `decision` veya `reasons` değerlerini etkilemez; istemciler kart içeriğine ihtiyaç duyduklarında kurulu `skill-card.md` değerini yerel olarak okumalıdır.
- Tek bir skill için Skill Card doğrulama zarfına ihtiyaç duyduğunuzda `/verify`, oluşturulmuş kart Markdown'una ihtiyaç duyduğunuzda `/card` ve ayrıntılı tarayıcı verilerine ihtiyaç duyduğunuzda `/scan` kullanın.

Yanıt:

```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": "Sürüm bulunamadı" },
      "security": null
    }
  ]
}
```

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

Depolanan dosyanın tam baytlarını indirme olarak döndürür. Sınırlandırılmış, kaçış karakterleri uygulanmış
metin önizlemesi istemek için `preview=1` ekleyin; geçerli UTF-8 baytlarına sahip tüm dosyalar,
uzantısından veya MIME meta verilerinden bağımsız olarak önizlenebilir.

Sorgu parametreleri:

- `path` (gerekli)
- `version` (isteğe bağlı)
- `tag` (isteğe bağlı)
- `preview=1` (isteğe bağlı; baytlar geçerli UTF-8 değilse `text/plain` veya `415` döndürür)

Notlar:

- Varsayılan olarak en son sürümü kullanır.
- Ham indirme sınırı: 10MB.
- Metin önizleme sınırı: 200KB.

### `GET /api/v1/packages`

Şunlar için birleşik katalog uç noktası:

- skill'ler
- kod plugin'leri
- paket plugin'leri

Sorgu parametreleri:

- `limit` (isteğe bağlı): tam sayı (1–100)
- `cursor` (isteğe bağlı): sayfalama imleci
- `family` (isteğe bağlı): `skill`, `code-plugin` veya `bundle-plugin`
- `channel` (isteğe bağlı): `official`, `community` veya `private`
- `isOfficial` (isteğe bağlı): `true` veya `false`
- `sort` (isteğe bağlı): `updated` (varsayılan), `recommended`, `trending`, `downloads`, eski takma ad `installs`
- `category` (isteğe bağlı): plugin kategori filtresi. Yalnızca istek
  plugin paketleriyle sınırlandırıldığında desteklenir (`/api/v1/plugins`,
  `/api/v1/code-plugins`, `/api/v1/bundle-plugins` veya `family=code-plugin`/`family=bundle-plugin`
  içeren paket uç noktaları). Denetimli kategoriler ve eski v1 filtre
  takma adları `GET /api/v1/plugins` altında belgelenmiştir.

Notlar:

- `family`, `channel`, `isOfficial`, `featured`,
  `highlightedOnly` veya `sort` için geçersiz değerler `400` döndürür. Bilinmeyen sorgu parametreleri yok sayılır.
- `GET /api/v1/code-plugins` ve `GET /api/v1/bundle-plugins`, sabit aile takma adları olarak kalır.
- Skill girdileri skill kayıt defteri tarafından desteklenmeye devam eder ve yine yalnızca `POST /api/v1/skills` aracılığıyla yayımlanabilir.
- `POST /api/v1/packages` hâlâ yalnızca kod plugin'i ve paket plugin'i sürümleri içindir.
- Anonim çağıranlar yalnızca genel paket kanallarını görür.
- Kimliği doğrulanmış çağıranlar, liste/arama sonuçlarında üyesi oldukları yayımcılara ait özel paketleri görebilir.
- `channel=private` yalnızca kimliği doğrulanmış çağıranın okuyabildiği paketleri döndürür.

### `GET /api/v1/packages/search`

Skill'ler ve plugin paketleri genelinde birleşik katalog araması.

Sorgu parametreleri:

- `q` (zorunlu): sorgu dizesi
- `limit` (isteğe bağlı): tam sayı (1–100)
- `family` (isteğe bağlı): `skill`, `code-plugin` veya `bundle-plugin`
- `channel` (isteğe bağlı): `official`, `community` veya `private`
- `isOfficial` (isteğe bağlı): `true` veya `false`
- `category` (isteğe bağlı): plugin kategorisi filtresi. Yalnızca istek
  plugin paketleriyle sınırlandırıldığında desteklenir. Denetlenen kategoriler ve eski v1
  filtre takma adları `GET /api/v1/plugins` altında belgelenmiştir.

Notlar:

- `family`, `channel`, `isOfficial`, `featured` veya
  `highlightedOnly` için geçersiz değerler `400` döndürür. Bilinmeyen sorgu parametreleri yok sayılır.
- Anonim çağıranlar yalnızca herkese açık paket kanallarını görür.
- Kimliği doğrulanmış çağıranlar, üyesi oldukları yayıncılara ait özel paketlerde arama yapabilir.
- `channel=private` yalnızca kimliği doğrulanmış çağıranın okuyabildiği paketleri döndürür.

### `GET /api/v1/plugins`

Kod plugini ve paket plugini paketlerinde yalnızca pluginlere yönelik katalog taraması.

Sorgu parametreleri:

- `limit` (isteğe bağlı): tam sayı (1-100)
- `cursor` (isteğe bağlı): sayfalama imleci
- `isOfficial` (isteğe bağlı): `true` veya `false`
- `sort` (isteğe bağlı): `recommended` (varsayılan), `trending`, `downloads`, `updated`, eski takma ad `installs`
- `category` (isteğe bağlı): plugin kategorisi filtresi. Geçerli değerler:
  `channels`, `models`, `memory`, `context`, `voice`, `media`, `web`,
  `tools`, `runtime`, `gateway`, `security`, `other`.

Eski v1 filtre takma adları okuma uç noktalarında kabul edilmeye devam eder:

- `mcp-tooling`, `data` ve `automation`, `tools` olarak çözümlenir.
- `observability` ve `deployment`, `gateway` olarak çözümlenir.
- `dev-tools`, `runtime` olarak çözümlenir.

`trending`, yedi günlük kurulum/indirme liderlik tablosudur ve tüm zamanların toplamlarını kullanmaz.
Birleşik `/api/v1/packages` uç noktasında yalnızca pluginlere yöneliktir; Skills kataloğu için
`/api/v1/skills?sort=trending` kullanın.

Eski takma adlar, saklanan veya yazar tarafından bildirilen kategori değerleri olarak kabul edilmez.

### `GET /api/v1/skills/export`

Çevrimdışı analiz için en son herkese açık Skills öğelerinin toplu dışa aktarımı.

Kimlik doğrulama:

- API tokeni zorunludur.

Sorgu parametreleri:

- `startDate` (zorunlu): Skill `updatedAt` için Unix milisaniye alt sınırı.
- `endDate` (zorunlu): Skill `updatedAt` için Unix milisaniye üst sınırı.
- `limit` (isteğe bağlı): tam sayı (1-250), varsayılan `250`.
- `cursor` (isteğe bağlı): önceki yanıttan alınan sayfalama imleci.

Yanıt:

- Gövde: ZIP arşivi.
- Dışa aktarılan her Skill öğesinin kökü `{publisher}/{slug}/` konumundadır.
- Barındırılan Skills öğeleri, saklanan en son sürüm dosyalarını içerir ve
  `_manifest.json` içinde `sourceRef: "public-clawhub"` ile listelenir.
- `clean` veya `suspicious` taraması bulunan güncel GitHub destekli Skills öğeleri;
  `_source_handoff.json` içinde `sourceRef: "public-github"`, depo, commit, yol,
  içerik karması ve arşiv URL'siyle yer alır. ClawHub tarafından barındırılan kaynak dosyalarını içermezler.
- Her Skill öğesi `_export_skill_meta.json` içerir.
- `_manifest.json` her zaman ZIP kökünde yer alır.
- `_errors.json`, tek tek Skills öğeleri veya dosyalar dışa
  aktarılamadığında eklenir.

Başlıklar:

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

### `GET /api/v1/plugins/export`

Çevrimdışı analiz için en son herkese açık plugin sürümlerinin toplu dışa aktarımı.

Kimlik doğrulama:

- API tokeni zorunludur.

Sorgu parametreleri:

- `startDate` (zorunlu): Plugin `updatedAt` için Unix milisaniye alt sınırı.
- `endDate` (zorunlu): Plugin `updatedAt` için Unix milisaniye üst sınırı.
- `limit` (isteğe bağlı): tam sayı (1-250), varsayılan `250`.
- `cursor` (isteğe bağlı): önceki yanıttan alınan sayfalama imleci.
- `family` (isteğe bağlı): `code-plugin` veya `bundle-plugin`. Atlanması, her iki
  plugin ailesi anlamına gelir.

Yanıt:

- Gövde: ZIP arşivi.
- Dışa aktarılan her pluginin kökü `{family}/{packageName}/` konumundadır.
- Dışa aktarılan her plugin, en son sürümün saklanan dosyalarını içerir.
- Plugin başına dışa aktarma meta verileri
  `__clawhub_export/{family}/{packageName}/plugin_meta.json` konumunda saklanır.
- `_manifest.json` her zaman ZIP kökünde yer alır.
- `_errors.json`, tek tek pluginler veya dosyalar dışa
  aktarılamadığında eklenir.

Başlıklar:

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

### `GET /api/v1/plugins/search`

Kod plugini ve paket plugini paketlerinde yalnızca pluginlere yönelik arama.

Sorgu parametreleri:

- `q` (zorunlu): sorgu dizesi
- `limit` (isteğe bağlı): tam sayı (1-100)
- `isOfficial` (isteğe bağlı): `true` veya `false`
- `category` (isteğe bağlı): plugin kategorisi filtresi. Geçerli değerler:
  `channels`, `models`, `memory`, `context`, `voice`, `media`, `web`,
  `tools`, `runtime`, `gateway`, `security`, `other`.

Notlar:

- `GET /api/v1/plugins` altında belgelenen eski v1 filtre takma adları da
  kabul edilir.
- Kategori filtreleme, arama sorgusunun yeniden yazılması değil, plugin kategori özeti
  satırlarıyla desteklenen gerçek bir API filtresidir.
- Sonuçlar ilgililik sırasına göre döndürülür ve şu anda sayfalanmaz.
- Plugin aramasına yönelik tarayıcı kullanıcı arayüzü sıralama denetimleri, yüklenen ilgililik sonuçlarını
  mevcut `/skills` tarama davranışıyla eşleşecek biçimde yeniden sıralar.

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

Paket ayrıntısı meta verilerini döndürür.

Notlar:

- Skills öğeleri de birleşik katalogda bu rota üzerinden çözümlenebilir.
- Çağıran, sahibi olan yayıncıyı okuyamadığı sürece özel paketler `404` döndürür.

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

Bir paketi ve tüm sürümlerini geçici olarak siler.

Notlar:

- Paket sahibi, kuruluş yayıncısının sahibi/yöneticisi,
  platform moderatörü veya platform yöneticisi için bir API tokeni gerektirir.

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

Sürüm geçmişini döndürür.

Sorgu parametreleri:

- `limit` (isteğe bağlı): tam sayı (1–100)
- `cursor` (isteğe bağlı): sayfalama imleci

Notlar:

- Çağıran, sahibi olan yayıncıyı okuyamadığı sürece özel paketler `404` döndürür.

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

Dosya meta verileri, uyumluluk, doğrulama, yapıt meta verileri
ve tarama verileri dâhil olmak üzere bir paket sürümünü döndürür.

Notlar:

- `version.artifact.kind`, eski dünya paket arşivleri için `legacy-zip` veya
  ClawPack destekli sürümler için `npm-pack` değeridir.
- ClawPack sürümleri, npm uyumlu `npmIntegrity`, `npmShasum` ve
  `npmTarballName` alanlarını içerir.
- `version.sha256hash`, eski istemcilere yönelik kullanımdan kaldırılmış uyumluluk meta verisidir.
  `/api/v1/packages/{name}/download` tarafından döndürülen tam ZIP baytlarının karmasını alır.
  Modern istemciler, kanonik sürüm yapıtını tanımlayan
  `version.artifact.sha256` değerini kullanmalıdır.
- `version.vtAnalysis`, `version.llmAnalysis` ve `version.staticScan`,
  tarama verileri mevcut olduğunda eklenir.
- Çağıran, sahibi olan yayıncıyı okuyamadığı sürece özel paketler `404` döndürür.

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

Kurulum istemcileri için tam paket sürümünün güvenlik ve güven özetini döndürür.
Bu, çözümlenen bir sürümün kurulup kurulamayacağına karar vermek için herkese açık
OpenClaw tüketim yüzeyidir.

Kimlik doğrulama:

- Herkese açık okuma uç noktası. Sahip, yayıncı, moderatör veya yönetici tokeni
  gerekmez.

Yanıt:

```json
{
  "package": {
    "name": "@openclaw/example-plugin",
    "displayName": "Örnek 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
  }
}
```

Yanıt alanları:

- `package.name`, `package.displayName` ve `package.family`,
  çözümlenen kayıt defteri paketini tanımlar.
- `release.releaseId`, `release.version` ve `release.createdAt`,
  değerlendirilen tam sürümü tanımlar.
- `release.artifactKind`, `release.artifactSha256`, `release.npmIntegrity`,
  `release.npmShasum` ve `release.npmTarballName`, sürüm yapıtı için
  bilindiklerinde bulunur.
- `trust.scanStatus`, tarayıcı girdilerinden ve manuel sürüm moderasyonundan
  türetilen etkin güven durumudur.
- `trust.moderationState` null olabilir. Manuel sürüm
  moderasyonu olmadığında `null` değerindedir.
- `trust.blockedFromDownload`, kurulum engelleme sinyalidir. OpenClaw ve diğer
  kurulum istemcileri, tarayıcı veya moderasyon alanlarından engelleme kurallarını
  yeniden türetmek yerine bu değer `true` olduğunda kurulumu engellemelidir.
- `trust.reasons`, kullanıcıya yönelik ve denetim amaçlı açıklama listesidir. Neden kodları
  `manual:quarantined`, `scan:malicious` ve
  `package:malicious` gibi kararlı, kısa dizelerdir.
- `trust.pending`, bir veya daha fazla güven girdisinin hâlâ tamamlanmayı beklediği anlamına gelir.
- `trust.stale`, güven özetinin güncelliğini yitirmiş girdilerden hesaplandığı ve
  yüksek güvenli bir izin kararından önce yenilenmesi gerektiği anlamına gelir.

Notlar:

- Bu uç nokta tam sürüme özeldir. İstemciler bunu yalnızca en son
  paket meta verilerini okuduktan sonra değil, kurmayı amaçladıkları paket sürümünü
  çözümledikten sonra çağırmalıdır.
- Çağıran, sahibi olan yayıncıyı okuyamadığı sürece özel paketler `404` döndürür.
- Bu uç nokta, sahip/moderatör moderasyon uç noktalarından kasıtlı olarak daha
  dar kapsamlıdır. Bildirimde bulunanların kimliklerini, bildirim gövdelerini, özel kanıtları
  veya dahili inceleme zaman çizelgelerini değil; kurulum kararını ve herkese açık açıklamayı
  sunar.

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

Bir paket sürümü için açık yapıt çözümleyici meta verilerini döndürür.

Notlar:

- Eski paket sürümleri, bir `legacy-zip` yapıtı ve eski bir ZIP
  `downloadUrl` döndürür.
- ClawPack sürümleri; bir `npm-pack` yapıtı, npm bütünlük alanları, bir
  `tarballUrl` ve eski ZIP uyumluluk URL'sini döndürür.
- Bu, OpenClaw çözümleyici yüzeyidir; paylaşılan bir URL'den arşiv biçiminin
  tahmin edilmesini önler.

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

Sürüm yapıtını açık çözümleyici yolu üzerinden indirir.

Notlar:

- ClawPack sürümleri, yüklenen npm-pack `.tgz` baytlarının aynısını aktarır.
- Eski ZIP sürümleri `/api/v1/packages/{name}/download?version=` konumuna yönlendirilir.
- İndirme hız sınırı grubunu kullanır.

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

OpenClaw'ın gelecekteki kullanımı için hesaplanan hazırlık durumunu döndürür.

Hazırlık denetimleri şunları kapsar:

- resmî kanal durumu
- en son sürümün kullanılabilirliği
- ClawPack npm-pack yapıtının kullanılabilirliği
- yapıt özeti
- kaynak depo ve commit kökeni
- OpenClaw uyumluluk meta verileri
- ana makine hedefleri
- tarama durumu

Yanıt:

```json
{
  "package": {
    "name": "@openclaw/example-plugin",
    "displayName": "Örnek Plugin",
    "family": "code-plugin",
    "isOfficial": true,
    "latestVersion": "1.2.3"
  },
  "ready": false,
  "checks": [
    {
      "id": "clawpack",
      "label": "ClawPack yapıtı",
      "status": "fail",
      "message": "En son sürüm yalnızca eski ZIP biçimindedir."
    }
  ],
  "blockers": ["clawpack"]
}
```

### `GET /api/v1/packages/migrations`

Resmî OpenClaw Plugin geçiş satırlarını listelemeye yönelik moderatör uç noktası.

Kimlik doğrulama:

- Moderatör veya yönetici kullanıcıya ait bir API belirteci gerektirir.

Sorgu parametreleri:

- `phase` (isteğe bağlı): `planned`, `published`, `clawpack-ready`,
  `legacy-zip-only`, `metadata-ready`, `blocked`, `ready-for-openclaw` veya
  `all` (varsayılan).
- `limit` (isteğe bağlı): tam sayı (1-100)
- `cursor` (isteğe bağlı): sayfalama imleci

Yanıt:

```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 eksik"],
      "hostTargetsComplete": true,
      "scanClean": false,
      "moderationApproved": false,
      "runtimeBundlesReady": false,
      "notes": null,
      "createdAt": 1760000000000,
      "updatedAt": 1760000000000
    }
  ],
  "nextCursor": null,
  "done": true
}
```

### `POST /api/v1/packages/migrations`

Resmî bir Plugin geçiş satırı oluşturmaya veya güncellemeye yönelik yönetici uç noktası.

Kimlik doğrulama:

- Yönetici kullanıcıya ait bir API belirteci gerektirir.

İstek gövdesi:

```json
{
  "bundledPluginId": "core.search",
  "packageName": "@openclaw/search-plugin",
  "owner": "platform",
  "sourceRepo": "openclaw/openclaw",
  "sourcePath": "plugins/search",
  "sourceCommit": "abc123",
  "phase": "blocked",
  "blockers": ["ClawPack eksik"],
  "hostTargetsComplete": true,
  "scanClean": false,
  "moderationApproved": false,
  "runtimeBundlesReady": false,
  "notes": "yayıncı yüklemesi bekleniyor"
}
```

Notlar:

- `bundledPluginId` küçük harfe dönüştürülerek normalleştirilir ve kararlı upsert anahtarıdır.
- `packageName` npm adına göre normalleştirilir; planlanan
  geçişlerde paket mevcut olmayabilir.
- Bu yalnızca geçiş hazırlığını izler. OpenClaw'ı değiştirmez veya
  ClawPack oluşturmaz.

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

Paket sürümü inceleme kuyruklarına yönelik moderatör/yönetici uç noktası.

Kimlik doğrulama:

- Moderatör veya yönetici kullanıcıya ait bir API belirteci gerektirir.

Sorgu parametreleri:

- `status` (isteğe bağlı): `open` (varsayılan), `blocked`, `manual` veya `all`
- `limit` (isteğe bağlı): tam sayı (1-100)
- `cursor` (isteğe bağlı): sayfalama imleci

Durumların anlamları:

- `open`: şüpheli, kötü amaçlı, bekleyen, karantinaya alınmış, iptal edilmiş veya bildirilmiş sürümler.
- `blocked`: karantinaya alınmış, iptal edilmiş veya kötü amaçlı sürümler.
- `manual`: manuel moderasyon geçersiz kılmasına sahip herhangi bir sürüm.
- `all`: manuel geçersiz kılmaya, temiz olmayan tarama durumuna veya paket bildirimine sahip herhangi bir sürüm.

Yanıt:

```json
{
  "items": [
    {
      "packageId": "packages:...",
      "releaseId": "packageReleases:...",
      "name": "@openclaw/example-plugin",
      "displayName": "Örnek Plugin",
      "family": "code-plugin",
      "channel": "community",
      "isOfficial": false,
      "version": "1.2.3",
      "createdAt": 1730000000000,
      "artifactKind": "npm-pack",
      "scanStatus": "malicious",
      "moderationState": "quarantined",
      "moderationReason": "manuel inceleme",
      "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`

Bir paketi moderatör incelemesi için bildirin. Bildirimler paket düzeyindedir ve isteğe bağlı olarak
bir sürüme bağlanabilir. Moderasyon kuyruğunu beslerler ancak kendi başlarına indirmeleri otomatik olarak gizlemez veya
engellemezler; moderatörler yapıtları onaylamak, karantinaya almak veya iptal etmek için
sürüm moderasyonunu kullanmalıdır.

Kimlik doğrulama:

- Bir API belirteci gerektirir.

İstek:

```json
{ "reason": "Şüpheli yerel ikili dosya", "version": "1.2.3" }
```

Yanıt:

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

### `GET /api/v1/packages/reports`

Paket bildirimlerini almaya yönelik moderatör/yönetici uç noktası.

Kimlik doğrulama:

- Moderatör veya yönetici kullanıcıya ait bir API belirteci gerektirir.

Sorgu parametreleri:

- `status` (isteğe bağlı): `open` (varsayılan), `confirmed`, `dismissed` veya `all`
- `limit` (isteğe bağlı): tam sayı (1-100)
- `cursor` (isteğe bağlı): sayfalama imleci

Yanıt:

```json
{
  "items": [
    {
      "reportId": "packageReports:...",
      "packageId": "packages:...",
      "releaseId": "packageReleases:...",
      "name": "@openclaw/example-plugin",
      "displayName": "Örnek Plugin",
      "family": "code-plugin",
      "version": "1.2.3",
      "reason": "Şüpheli yerel ikili dosya",
      "status": "open",
      "createdAt": 1730000000000,
      "reporter": {
        "userId": "users:...",
        "handle": "reporter",
        "displayName": "Bildiren"
      },
      "triagedAt": null,
      "triagedBy": null,
      "triageNote": null
    }
  ],
  "nextCursor": null,
  "done": true
}
```

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

Paket moderasyonu görünürlüğüne yönelik sahip/moderatör uç noktası.

Kimlik doğrulama:

- Paket sahibine, yayıncı üyesine, moderatöre veya
  yönetici kullanıcıya ait bir API belirteci gerektirir.

Yanıt:

```json
{
  "package": {
    "packageId": "packages:...",
    "name": "@openclaw/example-plugin",
    "displayName": "Örnek Plugin",
    "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": "manuel inceleme",
    "blockedFromDownload": true,
    "reasons": ["manual:quarantined", "scan:malicious", "reports:2"],
    "createdAt": 1730000000000
  }
}
```

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

Paket bildirimlerini çözümlemeye veya yeniden açmaya yönelik moderatör/yönetici uç noktası.

İstek:

```json
{
  "status": "confirmed",
  "note": "Etkilenen sürüm incelendi ve karantinaya alındı.",
  "finalAction": "quarantine"
}
```

`note`, `confirmed` ve `dismissed` için gereklidir; `status`
yeniden `open` olarak ayarlanırken atlanabilir. Aynı denetlenebilir iş akışında
sürüm moderasyonu uygulamak için onaylanmış bir bildirimle `finalAction: "quarantine"` veya
`finalAction: "revoke"` iletin.

Yanıt:

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

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

Paket sürümü incelemesine yönelik moderatör/yönetici uç noktası.

İstek:

```json
{ "state": "quarantined", "reason": "Şüpheli yerel yük." }
```

Desteklenen durumlar:

- `approved`: manuel olarak incelendi ve izin verildi.
- `quarantined`: takip işlemi beklenirken engellendi.
- `revoked`: bir sürüme daha önce güvenildikten sonra engellendi.

Karantinaya alınmış ve iptal edilmiş sürümler, yapıt indirme rotalarından `403` döndürür.
Her değişiklik bir denetim günlüğü girdisi yazar.

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

Tam olarak depolanan paket dosyası baytlarını indirme olarak döndürür. Skill dosyaları için kullanılan aynı sınırlı
UTF-8 metin önizlemesini istemek üzere `preview=1` ekleyin.

Sorgu parametreleri:

- `path` (gerekli)
- `version` (isteğe bağlı)
- `tag` (isteğe bağlı)
- `preview=1` (isteğe bağlı; baytlar geçerli UTF-8 değilse `text/plain` veya `415` döndürür)

Notlar:

- Varsayılan olarak en son sürümü kullanır.
- İndirme grubunu değil, okuma hız sınırı grubunu kullanır.
- Ham indirme sınırı: 10MB.
- Metin önizleme sınırı: 200KB; opak dosyalar yalnızca önizleme isteklerinde `415` döndürür.
- Bekleyen VirusTotal taramaları okumaları engellemez; kötü amaçlı sürümler başka yerlerde yine de erişime kapatılabilir.
- Çağıran, sahibi olan yayıncıyı okuyamıyorsa özel paketler `404` döndürür.

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

Bir paket sürümü için eski deterministik ZIP arşivini indirir.

Sorgu parametreleri:

- `version` (isteğe bağlı)
- `tag` (isteğe bağlı)

Notlar:

- Varsayılan olarak en son sürümü kullanır.
- Skills, `GET /api/v1/download` konumuna yönlendirilir.
- Eski OpenClaw istemcilerinin çalışmaya devam etmesi için Plugin/paket arşivleri,
  `package/` köküne sahip zip dosyalarıdır.
- Bu rota yalnızca ZIP olarak kalır. ClawPack `.tgz` dosyalarını aktarmaz.
- Yanıtlar, çözümleyici bütünlük denetimleri için `ETag`, `Digest`, `X-ClawHub-Artifact-Type` ve
  `X-ClawHub-Artifact-Sha256` başlıklarını içerir.
- Yalnızca kayıt defterine ait meta veriler indirilen arşive eklenmez.
- Bekleyen VirusTotal taramaları indirmeleri engellemez; kötü amaçlı sürümler `403` döndürür.
- Çağıran sahip değilse özel paketler `404` döndürür.

### `GET /api/npm/{package}`

ClawPack destekli paket sürümleri için npm uyumlu bir packument döndürür.

Notlar:

- Yalnızca yüklenmiş ClawPack npm-pack tarball'larına sahip sürümler listelenir.
- Yalnızca eski ZIP biçimindeki sürümler kasıtlı olarak hariç tutulur.
- `dist.tarball`, `dist.integrity` ve `dist.shasum`, kullanıcıların isterlerse npm'i aynaya
  yönlendirebilmesi için npm uyumlu alanlar kullanır.
- Kapsamlı paket packument'ları hem `/api/npm/@scope/name` hem de npm'in
  kodlanmış `/api/npm/@scope%2Fname` istek yolunu destekler.

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

npm ayna istemcileri için yüklenen ClawPack tarball baytlarının aynısını aktarır.

Notlar:

- İndirme hız sınırı grubunu kullanır.
- İndirme başlıkları ClawHub SHA-256 ile npm bütünlük/shasum meta verilerini içerir.
- Moderasyon ve özel paket erişim denetimleri uygulanmaya devam eder.

### `GET /api/v1/resolve`

CLI tarafından yerel bir parmak izini bilinen bir sürümle eşlemek için kullanılır.

Sorgu parametreleri:

- `slug` (gerekli)
- `hash` (gerekli): paket parmak izinin 64 karakterli onaltılık sha256 değeri

Yanıt:

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

### `GET /api/v1/download`

Barındırılan bir skill sürümünün ZIP dosyasını indirir veya `clean` ya da `suspicious` taramasına sahip, barındırılan
sürümü bulunmayan güncel bir GitHub destekli skill için GitHub kaynak devrini döndürür.

Sorgu parametreleri:

- `slug` (gerekli)
- `version` (isteğe bağlı): semver dizesi
- `tag` (isteğe bağlı): etiket adı (ör. `latest`)

Notlar:

- Ne `version` ne de `tag` sağlanırsa en son sürüm kullanılır.
- Geçici olarak silinen sürümler `410` döndürür.
- GitHub destekli skill devirleri baytları proxy üzerinden iletmez veya yansıtmaz. JSON yanıtı
  `sourceRef: "public-github"`, `repo`, `commit`, `path`, `contentHash`
  ve `archiveUrl` içerir; tarama/güncel durum bir geçittir ve başarılı yanıt
  yükü meta verilerine dahil edilmez.
- İndirme istatistikleri UTC günü başına benzersiz kimlikler olarak sayılır (API belirteci geçerliyse `userId`, aksi takdirde IP).

## Kimlik doğrulama uç noktaları (Bearer belirteci)

Tüm uç noktalar şunu gerektirir:

```
Authorization: Bearer clh_...
```

### `GET /api/v1/whoami`

Belirteci doğrular ve kullanıcı tanıtıcısını döndürür.

### `POST /api/v1/skills`

Yeni bir sürüm yayımlar.

- Tercih edilen: `payload` JSON ve `files[]` bloblarıyla `multipart/form-data`.
- `files` içeren JSON gövdesi de (storageId tabanlı) kabul edilir.
- İsteğe bağlı yük alanı: `ownerHandle`. Mevcut olduğunda API bu
  yayıncıyı sunucu tarafında çözümler ve aktörün yayıncı erişimine sahip olmasını gerektirir.
- İsteğe bağlı yük alanı: `migrateOwner`. `ownerHandle` ile `true` olduğunda,
  aktör hem mevcut hem de hedef yayıncılarda yönetici/sahipse mevcut bir
  skill bu sahibe taşınabilir. Bu açık onay olmadan sahip değişiklikleri
  reddedilir.

### `POST /api/v1/packages`

Bir kod Plugin'i veya paket Plugin'i sürümü yayımlar.

- Bearer belirteciyle kimlik doğrulaması gerektirir.
- `multipart/form-data` gerektirir.
- İzin verilen form alanları `payload`, yinelenen `files` blobları veya tek bir `clawpack`
  tarball başvurusudur. `clawpack`, bir `.tgz` blobu veya
  yükleme URL'si akışının döndürdüğü depolama kimliği olabilir. Hazırlanmış depolama kimliği yayımları, bu yükleme URL'siyle
  döndürülen `clawpackUploadTicket` değerini de içermelidir.
- `files` ya da `clawpack` kullanın; aynı istekte asla ikisini birden kullanmayın.
- JSON gövdeleri ve çağıran tarafından sağlanan `payload.files` / `payload.artifact`
  meta verileri reddedilir.
- Doğrudan çok parçalı yayımlama istekleri 18MB ile sınırlıdır. ClawPack tarball'ları,
  120MB tarball sınırına kadar yükleme URL'si akışını kullanabilir.
- İsteğe bağlı yük alanı: `ownerHandle`. Mevcut olduğunda yalnızca yöneticiler bu sahip adına yayımlayabilir.

Doğrulamada öne çıkanlar:

- `family`, `code-plugin` veya `bundle-plugin` olmalıdır.
- Plugin paketleri `openclaw.plugin.json` gerektirir. ClawPack `.tgz` yüklemeleri
  bunu `package/openclaw.plugin.json` konumunda içermelidir.
- Kod Plugin'leri `package.json`, kaynak depo meta verileri, kaynak commit
  meta verileri, yapılandırma şeması meta verileri, `openclaw.compat.pluginApi` ve
  `openclaw.build.openclawVersion` gerektirir.
- `openclaw.hostTargets` ve `openclaw.environment` isteğe bağlı meta verilerdir.
- Yalnızca `openclaw` kuruluş yayıncısı ve mevcut `openclaw` kuruluş üyelerinin
  kişisel yayıncıları `official` kanalına yayımlayabilir.
- Başkası adına yayımlamalarda da resmî kanal uygunluğu hedef sahip hesabına göre doğrulanır.

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

Bir skill'i geçici olarak siler / geri yükler (sahip, moderatör veya yönetici).

İsteğe bağlı JSON gövdesi:

```json
{ "reason": "Hukuki inceleme beklenirken moderasyon için bekletildi." }
```

Mevcut olduğunda `reason`, skill moderasyon notu olarak saklanır ve denetim günlüğüne kopyalanır.
Sahip tarafından başlatılan geçici silmeler slug'ı 30 gün boyunca ayırır; ardından slug başka bir
yayıncı tarafından alınabilir. Bu süre sonu geçerli olduğunda silme yanıtı `slugReservedUntil` içerir.
Moderatör/yönetici gizlemeleri ve güvenlik kaldırmaları bu şekilde sona ermez.

Silme yanıtı:

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

Durum kodları:

- `200`: başarılı
- `401`: yetkisiz
- `403`: yasak
- `404`: skill/kullanıcı bulunamadı
- `500`: dahili sunucu hatası

### `POST /api/v1/users/publisher`

Yalnızca yöneticiler içindir. Bir tanıtıcı için kuruluş yayıncısının mevcut olmasını sağlar. Tanıtıcı hâlâ
eski bir paylaşılan kullanıcı/kişisel yayıncıya işaret ediyorsa uç nokta önce bunu kuruluş yayıncısına taşır.
Yeni oluşturulan bir kuruluş için `memberHandle` sağlayın; işlemi yapan yönetici üye olarak eklenmez.
`memberRole` varsayılan olarak `owner` değerini alır.

- Gövde: `{ "handle": "openclaw", "displayName": "OpenClaw", "memberHandle": "alice", "memberRole": "owner", "trusted": true }`
- Yanıt: `{ "ok": true, "publisherId": "...", "handle": "openclaw", "created": true, "migrated": false, "trusted": true, "member": { "userId": "...", "handle": "alice", "role": "owner" } }`

### `POST /api/v1/publishers`

Kimliği doğrulanmış, kullanıcı tarafından kuruluş yayıncısı oluşturma. Yeni bir kuruluş yayıncısı oluşturur ve
çağıranı sahip olarak ekler. Bu uç nokta mevcut kullanıcı/kişisel tanıtıcıları taşımaz ve
yayıncıyı güvenilir/resmî olarak işaretlemez.

- Gövde: `{ "handle": "opik", "displayName": "Opik" }`
- Yanıt: `{ "ok": true, "publisherId": "...", "handle": "opik", "created": true, "trusted": false }`
- Tanıtıcı zaten bir yayıncı, kullanıcı veya kişisel yayıncı tarafından kullanılıyorsa `409` döndürür.

### `POST /api/v1/users/reserve`

Yalnızca yöneticiler içindir. Bir sürüm yayımlamadan kök slug'ları ve paket adlarını hak sahibi için ayırır.
Paket adları, sürüm satırı bulunmayan özel yer tutucu paketlere dönüşür; böylece aynı
sahip daha sonra gerçek kod Plugin'i veya paket Plugin'i sürümünü bu adla yayımlayabilir.

- Gövde: `{ "handle": "openclaw", "slugs": ["diffs"], "packageNames": ["@openclaw/diffs"], "reason": "reserved for official OpenClaw plugin" }`
- Yanıt: `{ "ok": true, "succeeded": 2, "failed": 0, "results": [{ "kind": "slug", "name": "diffs", "ok": true, "action": "reserved" }] }`

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

Yalnızca yöneticiler içindir. Convex Auth hesap satırlarını düzenlemeden, doğrulanmış yedek GitHub OAuth sorumlusu
için kişisel yayıncıyı kurtarır. İstek her iki değişmez GitHub
sağlayıcı hesap kimliğini de belirtmelidir; değiştirilebilir tanıtıcılar yalnızca operatöre yönelik bir koruma olarak kullanılır.

Uç nokta varsayılan olarak deneme çalıştırması yapar. Kurtarmayı uygulamak için personelin her iki
GitHub sorumlusu arasındaki sürekliliği bağımsız olarak doğrulamasının ardından `dryRun: false` ve
`confirmIdentityVerified: true` gerekir. Hedef kullanıcının mevcut kişisel
yayıncısında skill'ler, paketler veya GitHub skill kaynakları varsa kurtarma güvenli biçimde başarısız olur.
Kurtarma ayrıca kurtarılan yayıncının skill'leri, skill slug takma adları, paketleri,
paket denetçisi uyarıları ve türetilmiş arama özeti satırlarındaki eski `ownerUserId` alanlarını taşır;
böylece doğrudan sahip yolları yeni yayıncı yetkisiyle uyumlu olur. Kurtarılan tanıtıcıya ait etkin bir
korumalı tanıtıcı ayırması da yedek kullanıcıya yeniden atanır; böylece sonraki
profil eşitlemesi eski kullanıcının rakip yetkisini geri yükleyemez. Her birincil tablo,
uygulama işlemi başına 100 satırla sınırlıdır; daha büyük kurtarmalarda önce sürdürülebilir bir sahip taşıması kullanılmalıdır.
GitHub skill kaynakları yayıncı kapsamındadır ve yeniden yazılmak yerine kontrol edilmiş olarak bildirilir.

- Gövde: `{ "handle": "gingiris", "nextUserHandle": "gingiris-1031", "previousGitHubProviderAccountId": "123", "nextGitHubProviderAccountId": "456", "reason": "Verified account continuity for issue #2555", "confirmIdentityVerified": true, "dryRun": false }`
- Yanıt: `{ "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" }`

### Sahip slug yönetimi uç noktaları

- `POST /api/v1/skills/{slug}/rename`
  - Gövde: `{ "newSlug": "new-canonical-slug" }`
  - Yanıt: `{ "ok": true, "slug": "new-canonical-slug", "previousSlug": "old-slug" }`
- `POST /api/v1/skills/{slug}/merge`
  - Gövde: `{ "targetSlug": "canonical-target-slug" }`
  - Yanıt: `{ "ok": true, "sourceSlug": "old-slug", "targetSlug": "canonical-target-slug" }`

Notlar:

- Her iki uç nokta da API belirteciyle kimlik doğrulaması gerektirir ve yalnızca skill sahibi için çalışır.
- `rename`, önceki slug'ı yönlendirme takma adı olarak korur.
- `merge`, kaynak listesini gizler ve kaynak slug'ını hedef listeye yönlendirir.

### Sahiplik devri uç noktaları

- `POST /api/v1/skills/{slug}/transfer`
  - Gövde: `{ "toUserHandle": "target_handle", "message": "optional" }`
  - Yanıt: `{ "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`
  - Yanıt (kabul/ret/iptal): `{ "ok": true, "skillSlug": "demo-skill?" }`
- `GET /api/v1/transfers/incoming`
- `GET /api/v1/transfers/outgoing`
  - Yanıt biçimi: `{ "transfers": [{ "_id": "...", "skill": { "slug": "demo", "displayName": "Demo" }, "fromUser"|"toUser": { "handle": "..." }, "message": "...", "requestedAt": 0, "expiresAt": 0 }] }`

### `POST /api/v1/users/ban`

Bir kullanıcıyı yasaklar ve sahip olduğu skill'leri kalıcı olarak siler (yalnızca moderatör/yönetici).

Gövde:

```json
{ "handle": "user_handle", "reason": "isteğe bağlı yasaklama nedeni" }
```

veya

```json
{ "userId": "users_...", "reason": "isteğe bağlı yasaklama nedeni" }
```

Yanıt:

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

### `POST /api/v1/users/unban`

Bir kullanıcının yasağını kaldırır ve uygun skill'leri geri yükler (yalnızca yönetici).

Gövde:

```json
{ "handle": "user_handle", "reason": "isteğe bağlı yasak kaldırma nedeni" }
```

veya

```json
{ "userId": "users_...", "reason": "isteğe bağlı yasak kaldırma nedeni" }
```

Yanıt:

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

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

Yasağı kaldırmadan veya içeriği geri yüklemeden mevcut bir yasağın saklanan nedenini değiştirir
(yalnızca yönetici). `dryRun`, `false` olmadığı sürece varsayılan olarak deneme çalıştırması yapar.

Gövde:

```json
{ "handle": "user_handle", "reason": "toplu yayımlama spam'i", "dryRun": true }
```

veya

```json
{ "userId": "users_...", "reason": "toplu yayımlama spam'i", "dryRun": false }
```

Yanıt:

```json
{
  "ok": true,
  "dryRun": false,
  "userId": "users_...",
  "handle": "user_handle",
  "previousReason": "kötü amaçlı yazılım nedeniyle otomatik yasaklama",
  "nextReason": "toplu yayımlama spam'i",
  "changed": true
}
```

### `POST /api/v1/users/role`

Bir kullanıcı rolünü değiştirir (yalnızca yönetici).

Gövde:

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

veya

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

Yanıt:

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

### `GET /api/v1/users`

Kullanıcıları listeler veya arar (yalnızca yönetici).

Sorgu parametreleri:

- `q` (isteğe bağlı): arama sorgusu
- `query` (isteğe bağlı): `q` için takma ad
- `limit` (isteğe bağlı): en fazla sonuç sayısı (varsayılan 20, en fazla 200)

Yanıt:

```json
{
  "items": [
    {
      "userId": "users_...",
      "handle": "user_handle",
      "displayName": "Kullanıcı",
      "name": "Kullanıcı",
      "role": "moderator"
    }
  ],
  "total": 1
}
```

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

Bir Yer İşareti ekler/kaldırır. Eski `stars` rotası ve yanıt alanı adları
uyumluluk amacıyla korunur. Her iki uç nokta da eşgüçlüdür.

Yanıtlar:

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

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

## Eski CLI uç noktaları (kullanımdan kaldırıldı)

Eski CLI sürümleri için hâlâ desteklenir:

- `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`

Kaldırma planı için `DEPRECATIONS.md` bölümüne bakın.

`POST /api/cli/upload-url`, `uploadUrl` ve `uploadTicket` döndürür. Bir ClawPack tarball'ını
hazırlayan paket yayımları, elde edilen depolama kimliğini `clawpack` ve döndürülen bileti
`clawpackUploadTicket` olarak göndermelidir.

## Kayıt defteri keşfi (`/.well-known/clawhub.json`)

CLI, kayıt defteri/kimlik doğrulama ayarlarını siteden keşfedebilir:

- `/.well-known/clawhub.json` (JSON, tercih edilen)
- `/.well-known/clawdhub.json` (eski)

Şema:

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

Kendi sunucunuzda barındırıyorsanız bu dosyayı sunun (veya `CLAWHUB_REGISTRY` değerini açıkça ayarlayın; eski `CLAWDHUB_REGISTRY`).