HTTP API

Базовый URL: https://clawhub.ai (по умолчанию).

Все пути v1 находятся в /api/v1/.... Устаревшие /api/... и /api/cli/... сохраняются для совместимости (см. DEPRECATIONS.md). OpenAPI: /api/v1/openapi.json.

Повторное использование публичного каталога

Сторонние каталоги могут использовать публичные конечные точки чтения, чтобы перечислять или искать ClawHub skills. Кэшируйте результаты, соблюдайте 429/Retry-After, возвращайте пользователей к каноническому списку ClawHub (https://clawhub.ai/<owner>/skills/<slug>) и не создавайте впечатление, что ClawHub одобряет сторонний сайт. Не пытайтесь зеркалировать скрытый, приватный или заблокированный модерацией контент вне публичной поверхности API.

Сокращения веб-slug разрешаются между семействами реестра, но клиенты API должны использовать канонические URL, возвращаемые конечными точками чтения, вместо самостоятельного восстановления приоритета маршрутов.

Ограничения частоты запросов

Модель применения:

• Анонимные запросы: применяются по IP.

• Аутентифицированные запросы (действительный Bearer-токен): применяются по пользовательскому bucket.

• Если токен отсутствует или недействителен, поведение откатывается к применению по IP.

• Аутентифицированные конечные точки записи не должны возвращать простой Unauthorized, когда сервер знает причину. Отсутствующие токены, недействительные/отозванные токены и удаленные/заблокированные/отключенные учетные записи должны получать действенный текст, чтобы CLI клиенты могли сообщить пользователям, что их заблокировало.

• Чтение: 3000/мин на IP, 12000/мин на ключ

• Запись: 300/мин на IP, 3000/мин на ключ

• Скачивание: 1200/мин на IP, 6000/мин на ключ (конечные точки скачивания)

Заголовки:

• Совместимость с устаревшим форматом: X-RateLimit-Limit, X-RateLimit-Reset
• Стандартизованные: RateLimit-Limit, RateLimit-Reset
• При 429: X-RateLimit-Remaining: 0 и RateLimit-Remaining: 0
• При 429: Retry-After

Семантика заголовков:

• X-RateLimit-Reset: абсолютное время Unix epoch в секундах
• RateLimit-Reset: секунд до сброса (задержка)
• X-RateLimit-Remaining / RateLimit-Remaining: точный оставшийся бюджет, если присутствует. Сегментированные успешные запросы опускают этот заголовок вместо возврата приблизительного глобального значения.
• Retry-After: сколько секунд ждать перед повторной попыткой (задержка) при 429

Пример ответа 429:

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 Rate limit exceeded

Рекомендации для клиентов:

• Если Retry-After существует, подождите указанное число секунд перед повторной попыткой.
• Используйте backoff с jitter, чтобы избежать синхронизированных повторных попыток.
• Если Retry-After отсутствует, используйте RateLimit-Reset (или вычислите из X-RateLimit-Reset).

Источник IP:

• Использует доверенные заголовки IP клиента, включая cf-connecting-ip, только когда развертывание явно включает доверенные пересылаемые заголовки.
• ClawHub использует доверенные пересылаемые заголовки, чтобы определять IP клиентов на edge.
• Если доверенный IP клиента недоступен, анонимные запросы используют резервные buckets, ограниченные только типом rate-limit. Эти резервные buckets не включают предоставленные вызывающим пути, slugs, имена пакетов, версии, строки запроса или другие параметры артефактов.

Ответы с ошибками

Публичные ответы об ошибках v1 являются обычным текстом с content-type: text/plain; charset=utf-8. Это включает ошибки валидации (400), отсутствующие публичные ресурсы (404), ошибки аутентификации и разрешений (401/403), ограничения частоты (429) и заблокированные скачивания. Клиенты должны читать тело ответа как человекочитаемую строку. Неизвестные параметры запроса игнорируются для совместимости, но распознанные параметры запроса с недействительными значениями возвращают 400.

Публичные конечные точки (без аутентификации)

GET /api/v1/search

Параметры запроса:

• q (обязательно): строка запроса
• limit (необязательно): целое число
• highlightedOnly (необязательно): true, чтобы отфильтровать до выделенных skills
• nonSuspiciousOnly (необязательно): true, чтобы скрыть подозрительные (flagged.suspicious) skills
• nonSuspicious (необязательно): устаревший псевдоним для nonSuspiciousOnly

Ответ:

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

Примечания:

• Результаты возвращаются в порядке релевантности (сходство embeddings + повышения для точных токенов slug/имени + небольшой prior популярности).
• Релевантность сильнее популярности. Точный slug или совпадение токена отображаемого имени может ранжироваться выше более свободного совпадения с гораздо более сильной вовлеченностью.
• ASCII-текст токенизируется по границам слов и пунктуации. Например, personal-map содержит отдельный токен map, тогда как amap-jsapi-skill содержит amap, jsapi и skill; поэтому поиск map дает personal-map более сильное лексическое совпадение, чем amap-jsapi-skill.
• Популярность логарифмически масштабируется и ограничивается. Skills с высокой вовлеченностью могут ранжироваться ниже, когда текст запроса совпадает слабее.
• Подозрительное или скрытое состояние модерации может удалить skill из публичного поиска в зависимости от фильтров вызывающего и текущего статуса модерации.

Рекомендации по обнаруживаемости для издателей:

• Поместите термины, которые пользователи будут буквально искать, в отображаемое имя, сводку и теги. Используйте отдельный токен slug только тогда, когда это также стабильная идентичность, которую вы хотите сохранить.
• Не переименовывайте slug только ради одного запроса, если новый slug не является более подходящим долгосрочным каноническим именем. Старые slugs становятся перенаправляющими псевдонимами, но канонический URL, отображаемый slug и будущие поисковые дайджесты используют новый slug.
• Псевдонимы переименования сохраняют разрешение для старых URL и установок, которые разрешаются через реестр, но поисковое ранжирование основано на канонических метаданных skill после индексации переименования. Существующая статистика остается со skill.
• Если skill неожиданно невидим, сначала проверьте состояние модерации с помощью clawhub inspect @owner/slug, войдя в систему, прежде чем менять метаданные, связанные с ранжированием.

GET /api/v1/skills

Параметры запроса:

• limit (необязательно): целое число (1–200)
• cursor (необязательно): курсор пагинации для любой сортировки, кроме trending
• sort (необязательно): updated (по умолчанию), recommended (псевдоним: default), createdAt (псевдоним: newest), downloads, stars (псевдоним: rating), устаревшие псевдонимы установок installsCurrent/installs/installsAllTime сопоставляются с downloads, trending
• nonSuspiciousOnly (необязательно): true, чтобы скрыть подозрительные (flagged.suspicious) skills
• nonSuspicious (необязательно): устаревший псевдоним для nonSuspiciousOnly

Недействительные значения sort возвращают 400.

Примечания:

• recommended использует сигналы вовлеченности и свежести.
• trending ранжирует по установкам за последние 7 дней (на основе телеметрии).
• createdAt стабилен для обходов новых skills; updated изменяется, когда существующие skills публикуются повторно.
• Когда nonSuspiciousOnly=true, сортировки на основе курсора могут возвращать меньше элементов, чем limit, на странице, потому что подозрительные skills фильтруются после получения страницы.
• Используйте nextCursor, чтобы продолжить пагинацию, когда он присутствует. Короткая страница сама по себе не означает конец результатов.

Ответ:

{  "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}

Ответ:

{  "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  }}

Примечания:

• Старые slugs, созданные потоками переименования/слияния владельца, разрешаются в канонический skill.
• metadata.os: ограничения ОС, объявленные во frontmatter skill (например, ["macos"], ["linux"]). null, если не объявлено.
• metadata.systems: целевые системы Nix (например, ["aarch64-darwin", "x86_64-linux"]). null, если не объявлено.
• metadata равно null, если у skill нет метаданных платформы.
• moderation включается только когда skill помечен или владелец просматривает его.

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

Возвращает структурированное состояние модерации.

Ответ:

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

Примечания:

• Владельцы и модераторы могут получить доступ к деталям модерации для скрытых skills.
• Публичные вызывающие получают 200 только для уже помеченных видимых skills.
• Доказательства редактируются для публичных вызывающих и включают исходные фрагменты только для владельцев/модераторов.

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

Сообщить о skill для проверки модератором. Жалобы относятся к уровню skill, необязательно связаны с версией и попадают в очередь жалоб на skill.

Аутентификация:

• Требуется API-токен.

Запрос:

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

Ответ:

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

GET /api/v1/skills/-/reports

Конечная точка модератора/администратора для приема жалоб на skills.

Параметры запроса:

• status (необязательно): open (по умолчанию), confirmed, dismissed или all
• limit (необязательно): целое число (1-200)
• cursor (необязательно): курсор пагинации

Ответ:

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

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

Конечная точка модератора/администратора для разрешения или повторного открытия жалоб на skills.

Запрос:

{ "status": "confirmed", "note": "Reviewed and hid affected version.", "finalAction": "hide" }

note требуется для confirmed и dismissed; его можно опустить при возврате status к open. Передайте finalAction: "hide" с триажированной жалобой, чтобы скрыть skill в том же проверяемом workflow.

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

Параметры запроса:

• limit (необязательно): целое число
• cursor (необязательно): курсор пагинации

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

Возвращает метаданные версии + список файлов.

• version.security включает нормализованный статус проверки сканирования и сведения о сканере (VirusTotal + LLM), когда они доступны.

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

Возвращает сведения проверки сканирования безопасности для версии skill.

Параметры запроса:

• version (необязательно): строка конкретной версии.
• tag (необязательно): разрешить помеченную тегом версию (например, latest).

Примечания:

• Если не указан ни version, ни tag, используется последняя версия.
• Включает нормализованный статус проверки и детали, относящиеся к конкретным сканерам.
• security.hasScanResult равно true только когда сканер выдал определенный вердикт (clean, suspicious или malicious).
• moderation — текущий снимок модерации на уровне навыка, полученный из последней версии.
• При запросе исторической версии проверьте moderation.matchesRequestedVersion и moderation.sourceVersion, прежде чем считать moderation и security относящимися к одному и тому же контексту версии.

POST /api/v1/skills/-/scan

Аутентифицированная конечная точка отправки для новых заданий ClawScan.

Сканирования локальных загрузок больше не поддерживаются. Запросы с multipart/form-data или { "source": { "kind": "upload" } } возвращают 410.

Опубликованные сканирования используют JSON:

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

Примечания:

• Полезные нагрузки запросов сканирования и загружаемые отчеты удаляются из хранилища запросов сканирования после окна хранения.
• Опубликованные сканирования требуют доступа к управлению владельца/издателя либо полномочий модератора/администратора платформы.
• Опубликованные сканирования записываются обратно только когда update: true и сканирование успешно завершено.
• Ответ — 202 с { "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." } }.
• Задания сканирования асинхронны. Ручные запросы сканирования имеют приоритет над обычной работой публикации/обратного заполнения, но завершение все равно зависит от доступности воркеров.

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

Аутентифицированная конечная точка опроса для отправленного сканирования.

• Возвращает статус в очереди/выполняется/успешно/неудачно.
• Возвращает queue.queuedAhead и queue.position, пока задание находится в очереди, чтобы клиенты могли показать, сколько приоритетных ручных сканирований находится перед запросом. Очень большие очереди ограничиваются и отображаются с queuedAheadIsEstimate: true.
• Когда доступно, report содержит разделы clawscan, skillspector, staticAnalysis и virustotal.
• Неудачные задания сканирования возвращают status: "failed" с lastError.

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

Аутентифицированная конечная точка архива отчета.

• Требует успешно завершенного сканирования; незавершенные сканирования возвращают 409.
• Возвращает ZIP с manifest.json, clawscan.json, skillspector.json, static-analysis.json, virustotal.json и README.md.

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

Аутентифицированная конечная точка архива сохраненного отчета для отправленных версий.

• Требует доступа к управлению владельца/издателя для навыка или Plugin либо полномочий модератора/администратора платформы.
• Возвращает сохраненные результаты сканирования для точной отправленной версии, включая заблокированные или скрытые версии.
• kind по умолчанию равно skill; используйте kind=plugin для сканирований Plugin/пакета.
• Возвращает такую же структуру ZIP, как загрузки запросов сканирования.

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

Канонический маршрут пакетного повторного сканирования только для администраторов. Он принимает ту же форму полезной нагрузки, что и устаревший POST /api/v1/skills/-/rescan-batch.

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

Канонический маршрут статуса пакета только для администраторов. Он принимает { "jobIds": ["..."] } и возвращает те же агрегированные счетчики, что и устаревший POST /api/v1/skills/-/rescan-batch/status.

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

Возвращает конверт проверки Skill Card, используемый clawhub skill verify.

Параметры запроса:

• version (необязательно): конкретная строка версии.
• tag (необязательно): разрешить помеченную тегом версию (например, latest).

Примечания:

• ok равно true только когда выбранная версия имеет сгенерированную Skill Card, не заблокирована модерацией как вредоносная и проверка ClawScan чистая.
• Идентификатор навыка, идентификатор издателя и метаданные выбранной версии являются полями верхнего уровня конверта (slug, displayName, publisherHandle, version, resolvedFrom, tag, createdAt), чтобы shell-автоматизация могла читать их без распаковки вложенных оберток.
• security — вердикт ClawScan/безопасности верхнего уровня. Автоматизация должна опираться на ok, decision, reasons и security.status.
• security.signals содержит вспомогательные доказательства сканеров, такие как staticScan, virusTotal и skillSpector.
• security.signals.dependencyRegistry сохранен для совместимости ответов v1, но сканер существования реестра зависимостей выведен из эксплуатации, и этот ключ всегда равен null.
• provenance равно server-resolved-github-import только когда ClawHub разрешил и сохранил GitHub repo/ref/commit/path во время публикации или импорта; в остальных случаях оно равно unavailable.

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

Возвращает текущие компактные вердикты безопасности для точных версий навыков. Эта конечная точка коллекции предназначена для клиентов, которые уже знают, какие установленные версии навыков ClawHub им нужно отобразить, например OpenClaw Control UI.

Запрос:

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

Примечания:

• items должен содержать 1-100 уникальных пар { slug, version }.
• Результаты возвращаются по каждому элементу; один отсутствующий навык или версия не приводит к сбою всего ответа.
• Ответ содержит только данные безопасности. Он не включает данные Skill Card, статус сгенерированной карточки, списки файлов артефактов или подробные полезные нагрузки сканеров.
• security.signals содержит только вспомогательные доказательства на уровне статуса; используйте /scan или страницу аудита безопасности ClawHub для полных деталей сканера.
• security.signals.dependencyRegistry сохранен для совместимости ответов v1, но сканер существования реестра зависимостей выведен из эксплуатации, и этот ключ всегда равен null.
• Отсутствие Skill Card не влияет на ok, decision или reasons этой конечной точки; клиенты должны читать установленный skill-card.md локально, когда им нужно содержимое карточки.
• Используйте /verify, когда нужен конверт проверки Skill Card для одного навыка, /card, когда нужен сгенерированный Markdown карточки, и /scan, когда нужны подробные данные сканеров.

Ответ:

{  "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": "Version not found" },      "security": null    }  ]}

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

Возвращает необработанное текстовое содержимое.

Параметры запроса:

• path (обязательный)
• version (необязательный)
• tag (необязательный)

Примечания:

• По умолчанию используется последняя версия.
• Ограничение размера файла: 200KB.

GET /api/v1/packages

Единая конечная точка каталога для:

• Skills
• кодовых плагинов
• пакетных плагинов

Параметры запроса:

• limit (необязательный): целое число (1–100)
• cursor (необязательный): курсор пагинации
• family (необязательный): skill, code-plugin или bundle-plugin
• channel (необязательный): official, community или private
• isOfficial (необязательный): true или false
• sort (необязательный): updated (по умолчанию), recommended, trending, downloads, устаревший псевдоним installs
• category (необязательный): фильтр категории плагинов. Поддерживается только когда запрос ограничен пакетами плагинов (/api/v1/plugins, /api/v1/code-plugins, /api/v1/bundle-plugins или конечными точками пакетов с family=code-plugin/family=bundle-plugin). Управляемые категории и устаревшие псевдонимы фильтров v1 документированы в разделе GET /api/v1/plugins.

Примечания:

• Недопустимые значения для family, channel, isOfficial, featured, highlightedOnly или sort возвращают 400. Неизвестные параметры запроса игнорируются.
• GET /api/v1/code-plugins и GET /api/v1/bundle-plugins остаются псевдонимами с фиксированным семейством.
• Записи Skills по-прежнему основаны на реестре Skills и могут публиковаться только через POST /api/v1/skills.
• POST /api/v1/packages по-прежнему предназначен только для выпусков code-plugin и bundle-plugin.
• Анонимные вызывающие стороны видят только публичные каналы пакетов.
• Аутентифицированные вызывающие стороны могут видеть приватные пакеты издателей, к которым они относятся, в результатах списка и поиска.
• channel=private возвращает только пакеты, которые аутентифицированная вызывающая сторона может читать.

GET /api/v1/packages/search

Единый поиск по каталогу среди Skills и пакетов плагинов.

Параметры запроса:

• q (обязательный): строка запроса
• limit (необязательный): целое число (1–100)
• family (необязательный): skill, code-plugin или bundle-plugin
• channel (необязательный): official, community или private
• isOfficial (необязательный): true или false
• category (необязательный): фильтр категории плагинов. Поддерживается только когда запрос ограничен пакетами плагинов. Управляемые категории и устаревшие псевдонимы фильтров v1 документированы в разделе GET /api/v1/plugins.

Примечания:

• Недопустимые значения для family, channel, isOfficial, featured или highlightedOnly возвращают 400. Неизвестные параметры запроса игнорируются.
• Анонимные вызывающие стороны видят только публичные каналы пакетов.
• Аутентифицированные вызывающие стороны могут искать приватные пакеты издателей, к которым они относятся.
• channel=private возвращает только пакеты, которые аутентифицированная вызывающая сторона может читать.

GET /api/v1/plugins

Просмотр каталога только плагинов среди пакетов code-plugin и bundle-plugin.

Параметры запроса:

• limit (необязательный): целое число (1-100)
• cursor (необязательный): курсор пагинации
• isOfficial (необязательный): true или false
• sort (необязательный): recommended (по умолчанию), trending, downloads, updated, устаревший псевдоним installs
• category (необязательный): фильтр категории плагинов. Текущие значения: channels, models, memory, context, voice, media, web, tools, runtime, gateway, security, other.

Устаревшие псевдонимы фильтров v1 по-прежнему принимаются на конечных точках чтения:

• mcp-tooling, data и automation разрешаются в tools.
• observability и deployment разрешаются в gateway.
• dev-tools разрешается в runtime.

trending — это семидневная таблица лидеров по установкам/загрузкам, не использующая суммарные показатели за всё время. На единой конечной точке /api/v1/packages она доступна только для плагинов; используйте /api/v1/skills?sort=trending для каталога Skills.

Устаревшие псевдонимы не принимаются как сохранённые или объявленные автором значения категорий.

GET /api/v1/skills/export

Массовый экспорт последних публичных Skills для офлайн-анализа.

Аутентификация:

• Требуется токен API.

Параметры запроса:

• startDate (обязательный): нижняя граница Unix в миллисекундах для updatedAt Skills.
• endDate (обязательный): верхняя граница Unix в миллисекундах для updatedAt Skills.
• limit (необязательный): целое число (1-250), по умолчанию 250.
• cursor (необязательный): курсор пагинации из предыдущего ответа.

Ответ:

• Тело: ZIP-архив.
• Каждый экспортированный Skill размещается в корне {publisher}/{slug}/.
• Размещённые Skills включают файлы последней сохранённой версии и перечислены в _manifest.json с sourceRef: "public-clawhub".
• Текущие Skills, основанные на GitHub, со сканированием clean или suspicious включают _source_handoff.json с sourceRef: "public-github", репозиторием, коммитом, путём, хэшем содержимого и URL архива. Они не включают исходные файлы, размещённые в ClawHub.
• Каждый Skill включает _export_skill_meta.json.
• _manifest.json всегда включается в корень ZIP.
• _errors.json включается, когда отдельные Skills или файлы не удалось экспортировать.

Заголовки:

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

GET /api/v1/plugins/export

Массовый экспорт последних публичных релизов плагинов для офлайн-анализа.

Аутентификация:

• Требуется токен API.

Параметры запроса:

• startDate (обязательно): нижняя граница updatedAt плагина в миллисекундах Unix.
• endDate (обязательно): верхняя граница updatedAt плагина в миллисекундах Unix.
• limit (необязательно): целое число (1-250), по умолчанию 250.
• cursor (необязательно): курсор пагинации из предыдущего ответа.
• family (необязательно): code-plugin или bundle-plugin. Если опущено, используются оба семейства плагинов.

Ответ:

• Тело: ZIP-архив.
• Каждый экспортированный плагин размещается в корне {family}/{packageName}/.
• Каждый экспортированный плагин включает сохраненные файлы последнего релиза.
• Метаданные экспорта для каждого плагина сохраняются в __clawhub_export/{family}/{packageName}/plugin_meta.json.
• _manifest.json всегда включается в корень ZIP.
• _errors.json включается, когда отдельные плагины или файлы не удалось экспортировать.

Заголовки:

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

GET /api/v1/plugins/search

Поиск только по плагинам среди пакетов code-plugin и bundle-plugin.

Параметры запроса:

• q (обязательно): строка запроса
• limit (необязательно): целое число (1-100)
• isOfficial (необязательно): true или false
• category (необязательно): фильтр категории плагинов. Текущие значения: channels, models, memory, context, voice, media, web, tools, runtime, gateway, security, other.

Примечания:

• Устаревшие псевдонимы фильтров v1, задокументированные в GET /api/v1/plugins, также принимаются.
• Фильтрация по категории — это реальный фильтр API, основанный на строках дайджеста категорий плагинов, а не переписывание поискового запроса.
• Результаты возвращаются в порядке релевантности и сейчас не поддерживают пагинацию.
• Элементы управления сортировкой в браузерном UI для поиска плагинов переупорядочивают загруженные результаты по релевантности, совпадая с текущим поведением просмотра /skills.

GET /api/v1/packages/{name}

Возвращает подробные метаданные пакета.

Примечания:

• Skills также могут разрешаться через этот маршрут в унифицированном каталоге.
• Приватные пакеты возвращают 404, если вызывающий не может читать владельца-публикатора.

DELETE /api/v1/packages/{name}

Выполняет мягкое удаление пакета и всех релизов.

Примечания:

• Требует токен API владельца пакета, владельца/администратора org-публикатора, модератора платформы или администратора платформы.

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

Возвращает историю версий.

Параметры запроса:

• limit (необязательно): целое число (1–100)
• cursor (необязательно): курсор пагинации

Примечания:

• Приватные пакеты возвращают 404, если вызывающий не может читать владельца-публикатора.

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

Возвращает одну версию пакета, включая метаданные файлов, совместимость, верификацию, метаданные артефакта и данные сканирования.

Примечания:

• version.artifact.kind имеет значение legacy-zip для архивов пакетов старого мира или npm-pack для релизов на базе ClawPack.
• Релизы ClawPack включают npm-совместимые поля npmIntegrity, npmShasum и npmTarballName.
• version.sha256hash — устаревшие метаданные совместимости для старых клиентов. Они хешируют точные байты ZIP, возвращаемые /api/v1/packages/{name}/download. Современным клиентам следует использовать version.artifact.sha256, который идентифицирует канонический артефакт релиза.
• version.vtAnalysis, version.llmAnalysis и version.staticScan включаются, когда существуют данные сканирования.
• Приватные пакеты возвращают 404, если вызывающий не может читать владельца-публикатора.

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

Возвращает точную сводку безопасности и доверия для релиза пакета для клиентов установки. Это публичная поверхность потребления OpenClaw для принятия решения, можно ли установить разрешенный релиз.

Аутентификация:

• Публичная конечная точка чтения. Токен владельца, публикатора, модератора или администратора не требуется.

Ответ:

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

Поля ответа:

• package.name, package.displayName и package.family идентифицируют разрешенный пакет реестра.
• release.releaseId, release.version и release.createdAt идентифицируют точный релиз, который был оценен.
• release.artifactKind, release.artifactSha256, release.npmIntegrity, release.npmShasum и release.npmTarballName присутствуют, когда известны для артефакта релиза.
• trust.scanStatus — эффективный статус доверия, полученный из входных данных сканера и ручной модерации релиза.
• trust.moderationState допускает null. Он равен null, когда ручная модерация релиза отсутствует.
• trust.blockedFromDownload — сигнал блокировки установки. OpenClaw и другие клиенты установки должны блокировать установку, когда это значение равно true, вместо повторного вывода правил блокировки из полей сканера или модерации.
• trust.reasons — пользовательский и аудиторский список объяснений. Коды причин являются стабильными компактными строками, такими как manual:quarantined, scan:malicious и package:malicious.
• trust.pending означает, что один или несколько входных сигналов доверия все еще ожидают завершения.
• trust.stale означает, что сводка доверия была вычислена из устаревших входных данных и должна рассматриваться как требующая обновления перед решением о разрешении с высокой уверенностью.

Примечания:

• Эта конечная точка точна для версии. Клиентам следует вызывать ее после разрешения версии пакета, которую они намерены установить, а не просто после чтения последних метаданных пакета.
• Приватные пакеты возвращают 404, если вызывающий не может читать владельца-публикатора.
• Эта конечная точка намеренно уже, чем конечные точки модерации владельца/модератора. Она раскрывает решение об установке и публичное объяснение, а не личности отправителей отчетов, тела отчетов, приватные доказательства или внутренние графики ревью.

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

Возвращает явные метаданные resolver артефакта для версии пакета.

Примечания:

• Устаревшие версии пакетов возвращают артефакт legacy-zip и устаревший ZIP downloadUrl.
• Версии ClawPack возвращают артефакт npm-pack, поля целостности npm, tarballUrl и устаревший URL совместимости ZIP.
• Это поверхность resolver OpenClaw; она избегает угадывания формата архива по общему URL.

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

Скачивает артефакт версии через явный путь resolver.

Примечания:

• Версии ClawPack отдают потоком точные загруженные байты npm-pack .tgz.
• Устаревшие ZIP-версии перенаправляют на /api/v1/packages/{name}/download?version=.
• Использует bucket лимита скорости скачивания.

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

Возвращает вычисленную готовность для будущего потребления OpenClaw.

Проверки готовности охватывают:

• статус официального канала
• доступность последней версии
• доступность артефакта ClawPack npm-pack
• дайджест артефакта
• исходный репозиторий и происхождение коммита
• метаданные совместимости OpenClaw
• целевые хосты
• состояние сканирования

Ответ:

{  "package": {    "name": "@openclaw/example-plugin",    "displayName": "Example Plugin",    "family": "code-plugin",    "isOfficial": true,    "latestVersion": "1.2.3"  },  "ready": false,  "checks": [    {      "id": "clawpack",      "label": "ClawPack artifact",      "status": "fail",      "message": "Latest version is legacy ZIP-only."    }  ],  "blockers": ["clawpack"]}

GET /api/v1/packages/migrations

Конечная точка модератора для перечисления строк миграции официальных плагинов OpenClaw.

Аутентификация:

• Требует токен API пользователя-модератора или администратора.

Параметры запроса:

• phase (необязательно): planned, published, clawpack-ready, legacy-zip-only, metadata-ready, blocked, ready-for-openclaw или all (по умолчанию).
• limit (необязательно): целое число (1-100)
• cursor (необязательно): курсор пагинации

Ответ:

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

POST /api/v1/packages/migrations

Административная конечная точка для создания или обновления строки миграции официального плагина.

Аутентификация:

• Требует токен API пользователя-администратора.

Тело запроса:

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

Примечания:

• bundledPluginId нормализуется в нижний регистр и является стабильным ключом upsert.
• packageName нормализуется как npm-имя; пакет может отсутствовать для запланированных миграций.
• Это отслеживает только готовность миграции. Оно не изменяет OpenClaw и не генерирует ClawPacks.

GET /api/v1/packages/moderation/queue

Конечная точка модератора/администратора для очередей ревью релизов пакетов.

Аутентификация:

• Требует токен API пользователя-модератора или администратора.

Параметры запроса:

• status (необязательно): open (по умолчанию), blocked, manual или all
• limit (необязательно): целое число (1-100)
• cursor (необязательно): курсор пагинации

Значения статусов:

• open: подозрительные, вредоносные, ожидающие, помещенные в карантин, отозванные релизы или релизы с отчетами.
• blocked: помещенные в карантин, отозванные или вредоносные релизы.
• manual: любой релиз с ручным переопределением модерации.
• all: любой релиз с ручным переопределением, состоянием сканирования не clean или отчетом о пакете.

Ответ:

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

Отправляет отчет о пакете на ревью модератору. Отчеты относятся к уровню пакета и опционально связываются с версией. Они попадают в очередь модерации, но сами по себе не скрывают автоматически и не блокируют скачивания; модераторы должны использовать модерацию релиза, чтобы одобрять, помещать в карантин или отзывать артефакты.

Аутентификация:

• Требует токен API.

Запрос:

{ "reason": "Suspicious native binary", "version": "1.2.3" }

Ответ:

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

GET /api/v1/packages/reports

Модераторская/административная конечная точка для приема отчетов о пакетах.

Аутентификация:

• Требуется API-токен пользователя-модератора или администратора.

Параметры запроса:

• status (необязательно): open (по умолчанию), confirmed, dismissed или all
• limit (необязательно): целое число (1-100)
• cursor (необязательно): курсор пагинации

Ответ:

{  "items": [    {      "reportId": "packageReports:...",      "packageId": "packages:...",      "releaseId": "packageReleases:...",      "name": "@openclaw/example-plugin",      "displayName": "Example Plugin",      "family": "code-plugin",      "version": "1.2.3",      "reason": "Suspicious native binary",      "status": "open",      "createdAt": 1730000000000,      "reporter": {        "userId": "users:...",        "handle": "reporter",        "displayName": "Reporter"      },      "triagedAt": null,      "triagedBy": null,      "triageNote": null    }  ],  "nextCursor": null,  "done": true}

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

Конечная точка для владельца/модератора, предоставляющая видимость модерации пакета.

Аутентификация:

• Требуется API-токен владельца пакета, участника издателя, модератора или администратора.

Ответ:

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

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

Модераторская/административная конечная точка для разрешения или повторного открытия отчетов о пакетах.

Запрос:

{  "status": "confirmed",  "note": "Reviewed and quarantined affected release.",  "finalAction": "quarantine"}

note обязателен для confirmed и dismissed; его можно опустить при возврате status к open. Передайте finalAction: "quarantine" или finalAction: "revoke" с подтвержденным отчетом, чтобы применить модерацию релиза в том же аудируемом рабочем процессе.

Ответ:

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

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

Модераторская/административная конечная точка для проверки релиза пакета.

Запрос:

{ "state": "quarantined", "reason": "Suspicious native payload." }

Поддерживаемые состояния:

• approved: вручную проверен и разрешен.
• quarantined: заблокирован до последующих действий.
• revoked: заблокирован после того, как релиз ранее считался доверенным.

Релизы в состояниях quarantined и revoked возвращают 403 из маршрутов загрузки артефактов. Каждое изменение записывает запись в журнал аудита.

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

Возвращает необработанное текстовое содержимое файла пакета.

Параметры запроса:

• path (обязательно)
• version (необязательно)
• tag (необязательно)

Примечания:

• По умолчанию используется последний релиз.
• Использует квоту скорости чтения, а не квоту загрузок.
• Двоичные файлы возвращают 415.
• Ограничение размера файла: 200 КБ.
• Ожидающие сканирования VirusTotal не блокируют чтение; вредоносные релизы все еще могут удерживаться в других местах.
• Приватные пакеты возвращают 404, если вызывающая сторона не может читать данные владеющего издателя.

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

Загружает устаревший детерминированный ZIP-архив для релиза пакета.

Параметры запроса:

• version (необязательно)
• tag (необязательно)

Примечания:

• По умолчанию используется последний релиз.
• Skills перенаправляются на GET /api/v1/download.
• Архивы Plugin/пакетов являются zip-файлами с корнем package/, чтобы старые клиенты OpenClaw продолжали работать.
• Этот маршрут остается только ZIP. Он не передает потоково файлы ClawPack .tgz.
• Ответы включают заголовки ETag, Digest, X-ClawHub-Artifact-Type и X-ClawHub-Artifact-Sha256 для проверок целостности резолвером.
• Метаданные только из реестра не внедряются в загруженный архив.
• Ожидающие сканирования VirusTotal не блокируют загрузки; вредоносные релизы возвращают 403.
• Приватные пакеты возвращают 404, если вызывающая сторона не является владельцем.

GET /api/npm/{package}

Возвращает совместимый с npm пакетный манифест для версий пакетов на базе ClawPack.

Примечания:

• Перечисляются только версии с загруженными tarball-архивами ClawPack npm-pack.
• Устаревшие версии только с ZIP намеренно опущены.
• dist.tarball, dist.integrity и dist.shasum используют совместимые с npm поля, чтобы пользователи могли указать npm на зеркало, если захотят.
• Пакетные манифесты scoped-пакетов поддерживают как /api/npm/@scope/name, так и закодированный npm путь запроса /api/npm/@scope%2Fname.

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

Передает потоково точные байты загруженного tarball-архива ClawPack для клиентов npm-зеркала.

Примечания:

• Использует корзину лимита скорости загрузки.
• Заголовки загрузки включают SHA-256 ClawHub, а также метаданные npm integrity/shasum.
• Проверки модерации и доступа к приватным пакетам по-прежнему применяются.

GET /api/v1/resolve

Используется CLI для сопоставления локального отпечатка с известной версией.

Параметры запроса:

• slug (обязательный)
• hash (обязательный): 64-символьный hex sha256 отпечатка бандла

Ответ:

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

GET /api/v1/download

Загружает ZIP размещенной версии skill или возвращает передачу управления исходнику GitHub для текущего skill на базе GitHub со сканированием clean или suspicious и без размещенной версии.

Параметры запроса:

• slug (обязательный)
• version (необязательный): semver-строка
• tag (необязательный): имя тега (например, latest)

Примечания:

• Если не указаны ни version, ни tag, используется последняя версия.
• Версии с мягким удалением возвращают 410.
• Передачи управления для skills на базе GitHub не проксируют и не зеркалируют байты. JSON-ответ включает sourceRef: "public-github", repo, commit, path, contentHash и archiveUrl; состояние сканирования/актуальности является условием допуска и не включается как метаданные успешной полезной нагрузки.
• Статистика загрузок считается по уникальным идентичностям за день UTC (userId, когда API-токен действителен, иначе IP).

Эндпоинты аутентификации (токен Bearer)

Все эндпоинты требуют:

Authorization: Bearer clh_...

GET /api/v1/whoami

Проверяет токен и возвращает handle пользователя.

POST /api/v1/skills

Публикует новую версию.

• Предпочтительно: multipart/form-data с JSON payload + blob-объектами files[].
• Также принимается JSON-тело с files (на основе storageId).
• Необязательное поле payload: ownerHandle. Если оно присутствует, API разрешает этого издателя на стороне сервера и требует, чтобы у действующего пользователя был доступ издателя.
• Необязательное поле payload: migrateOwner. Когда равно true вместе с ownerHandle, существующий skill может быть перемещен к этому владельцу, если действующий пользователь является admin/owner и у текущего, и у целевого издателя. Без этого явного согласия изменения владельца отклоняются.

POST /api/v1/packages

Публикует релиз code-plugin или bundle-plugin.

• Требует аутентификацию токеном Bearer.
• Требует multipart/form-data.
• Разрешенные поля формы: payload, повторяющиеся blob-объекты files или одна ссылка на tarball clawpack. clawpack может быть blob-объектом .tgz или storage id, возвращенным потоком upload-url. Публикации с подготовленным storage-id также должны включать clawpackUploadTicket, возвращенный с этим URL загрузки.
• Используйте либо files, либо clawpack, но никогда оба в одном запросе.
• JSON-тела и предоставленные вызывающей стороной метаданные payload.files / payload.artifact отклоняются.
• Прямые multipart-запросы публикации ограничены 18MB. Tarball-файлы ClawPack могут использовать поток upload-url до лимита tarball 120MB.
• Необязательное поле payload: ownerHandle. Если оно присутствует, только администраторы могут публиковать от имени этого владельца.

Основные моменты валидации:

• family должно быть code-plugin или bundle-plugin.
• Пакеты Plugin требуют openclaw.plugin.json. Загрузки ClawPack .tgz должны содержать его в package/openclaw.plugin.json.
• Code plugins требуют package.json, метаданные исходного репозитория, метаданные исходного коммита, метаданные схемы конфигурации, openclaw.compat.pluginApi и openclaw.build.openclawVersion.
• openclaw.hostTargets и openclaw.environment являются необязательными метаданными.
• Только издатель организации openclaw и личные издатели текущих участников организации openclaw могут публиковать в канал official.
• Публикации от имени другого владельца по-прежнему проверяют право на канал official по целевой учетной записи владельца.

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

Мягко удаляет / восстанавливает skill (владелец, модератор или администратор).

Необязательное JSON-тело:

{ "reason": "Held for moderation pending legal review." }

Если присутствует, reason сохраняется как модерационная заметка skill и копируется в журнал аудита. Мягкие удаления, инициированные владельцем, резервируют slug на 30 дней, после чего slug может быть занят другим издателем. Ответ удаления включает slugReservedUntil, когда применяется этот срок истечения. Скрытия модератором/администратором и удаления по соображениям безопасности таким образом не истекают.

Ответ удаления:

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

Коды статуса:

• 200: ok
• 401: не авторизован
• 403: запрещено
• 404: skill/пользователь не найден
• 500: внутренняя ошибка сервера

POST /api/v1/users/publisher

Только для администраторов. Гарантирует, что для handle существует издатель организации. Если handle все еще указывает на legacy общего пользователя/личного издателя, эндпоинт сначала мигрирует его в издателя организации. Для вновь созданной организации укажите memberHandle; действующий администратор не добавляется как участник. memberRole по умолчанию равен owner.

• Тело: { "handle": "openclaw", "displayName": "OpenClaw", "memberHandle": "alice", "memberRole": "owner", "trusted": true }
• Ответ: { "ok": true, "publisherId": "...", "handle": "openclaw", "created": true, "migrated": false, "trusted": true, "member": { "userId": "...", "handle": "alice", "role": "owner" } }

POST /api/v1/publishers

Аутентифицированное самостоятельное создание издателя организации. Создает нового издателя организации и добавляет вызывающую сторону как владельца. Этот эндпоинт не мигрирует существующие пользовательские/личные handles и не помечает издателя как trusted/official.

• Тело: { "handle": "opik", "displayName": "Opik" }
• Ответ: { "ok": true, "publisherId": "...", "handle": "opik", "created": true, "trusted": false }
• Возвращает 409, когда handle уже используется издателем, пользователем или личным издателем.

POST /api/v1/users/reserve

Только для администраторов. Резервирует корневые slugs и имена пакетов для законного владельца без публикации релиза. Имена пакетов становятся приватными пакетами-заполнителями без строк релизов, поэтому тот же владелец может позже опубликовать настоящий релиз code-plugin или bundle-plugin под этим именем.

• Тело: { "handle": "openclaw", "slugs": ["diffs"], "packageNames": ["@openclaw/diffs"], "reason": "reserved for official OpenClaw plugin" }
• Ответ: { "ok": true, "succeeded": 2, "failed": 0, "results": [{ "kind": "slug", "name": "diffs", "ok": true, "action": "reserved" }] }

POST /api/v1/users/publisher-recovery

Только для администраторов. Восстанавливает личного издателя для проверенного заменяющего principal GitHub OAuth без редактирования строк учетных записей Convex Auth. Запрос должен указывать оба неизменяемых id учетных записей провайдера GitHub; изменяемые handles используются только как операторская проверка.

Эндпоинт по умолчанию работает в режиме пробного запуска. Для применения восстановления требуется dryRun: false и confirmIdentityVerified: true после того, как сотрудники независимо подтвердят непрерывность между обоими GitHub принципалами. Восстановление завершается закрытым отказом, если у текущего личного издателя пользователя назначения есть skills, packages или источники GitHub skills. Восстановление также мигрирует устаревшие поля ownerUserId для skills восстановленного издателя, псевдонимов слагов skill, packages, предупреждений инспектора packages и производных строк поискового дайджеста, чтобы пути прямого владельца соответствовали новым полномочиям издателя. Активное резервирование защищенного handle для восстановленного handle также переназначается пользователю-замене, чтобы последующая синхронизация профиля не могла восстановить конкурирующие полномочия прежнего пользователя. Каждая основная таблица ограничена 100 строками на транзакцию применения; для более крупных восстановлений сначала необходимо использовать возобновляемую миграцию владельца. Источники GitHub skill имеют область действия издателя и сообщаются как проверенные, а не переписываются.

• Тело: { "handle": "gingiris", "nextUserHandle": "gingiris-1031", "previousGitHubProviderAccountId": "123", "nextGitHubProviderAccountId": "456", "reason": "Подтверждена непрерывность учетной записи для issue #2555", "confirmIdentityVerified": true, "dryRun": false }
• Ответ: { "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": "Подтверждена непрерывность учетной записи для issue #2555" }

Эндпоинты управления слагами владельца

• POST /api/v1/skills/{slug}/rename
  • Тело: { "newSlug": "new-canonical-slug" }
  • Ответ: { "ok": true, "slug": "new-canonical-slug", "previousSlug": "old-slug" }
• POST /api/v1/skills/{slug}/merge
  • Тело: { "targetSlug": "canonical-target-slug" }
  • Ответ: { "ok": true, "sourceSlug": "old-slug", "targetSlug": "canonical-target-slug" }

Примечания:

• Оба эндпоинта требуют аутентификации API-токеном и работают только для владельца skill.
• rename сохраняет предыдущий слаг как псевдоним перенаправления.
• merge скрывает исходную запись в каталоге и перенаправляет исходный слаг на целевую запись.

Эндпоинты передачи владения

• POST /api/v1/skills/{slug}/transfer
  • Тело: { "toUserHandle": "target_handle", "message": "optional" }
  • Ответ: { "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
  • Ответ (accept/reject/cancel): { "ok": true, "skillSlug": "demo-skill?" }
• GET /api/v1/transfers/incoming
• GET /api/v1/transfers/outgoing
  • Форма ответа: { "transfers": [{ "_id": "...", "skill": { "slug": "demo", "displayName": "Demo" }, "fromUser"|"toUser": { "handle": "..." }, "message": "...", "requestedAt": 0, "expiresAt": 0 }] }

POST /api/v1/users/ban

Заблокировать пользователя и безвозвратно удалить принадлежащие ему skills (только для модератора/администратора).

Тело:

{ "handle": "user_handle", "reason": "optional ban reason" }

или

{ "userId": "users_...", "reason": "optional ban reason" }

Ответ:

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

POST /api/v1/users/unban

Разблокировать пользователя и восстановить подходящие skills (только для администратора).

Тело:

{ "handle": "user_handle", "reason": "optional unban reason" }

или

{ "userId": "users_...", "reason": "optional unban reason" }

Ответ:

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

POST /api/v1/users/reclassify-ban

Изменить сохраненную причину существующей блокировки без разблокировки или восстановления контента (только для администратора). По умолчанию используется пробный запуск, если dryRun не равно false.

Тело:

{ "handle": "user_handle", "reason": "bulk publishing spam", "dryRun": true }

или

{ "userId": "users_...", "reason": "bulk publishing spam", "dryRun": false }

Ответ:

{  "ok": true,  "dryRun": false,  "userId": "users_...",  "handle": "user_handle",  "previousReason": "malware auto-ban",  "nextReason": "bulk publishing spam",  "changed": true}

POST /api/v1/users/role

Изменить роль пользователя (только для администратора).

Тело:

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

или

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

Ответ:

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

GET /api/v1/users

Вывести список пользователей или выполнить поиск пользователей (только для администратора).

Параметры запроса:

• q (необязательно): поисковый запрос
• query (необязательно): псевдоним для q
• limit (необязательно): максимальное количество результатов (по умолчанию 20, максимум 200)

Ответ:

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

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

Добавить/удалить звезду (выделение). Оба эндпоинта идемпотентны.

Ответы:

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

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

Устаревшие эндпоинты CLI (устарели)

Все еще поддерживаются для старых версий CLI:

• 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

План удаления см. в DEPRECATIONS.md.

POST /api/cli/upload-url возвращает uploadUrl и uploadTicket. Публикации package, которые подготавливают tarball ClawPack, должны отправлять полученный идентификатор хранилища как clawpack, а возвращенный ticket — как clawpackUploadTicket.

Обнаружение реестра (/.well-known/clawhub.json)

CLI может обнаруживать настройки реестра/аутентификации с сайта:

• /.well-known/clawhub.json (JSON, предпочтительно)
• /.well-known/clawdhub.json (устаревшее)

Схема:

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

Если вы размещаете сервис самостоятельно, отдавайте этот файл (или задайте CLAWHUB_REGISTRY явно; устаревшее CLAWDHUB_REGISTRY).