API v1

База: https://clawhub.ai

OpenAPI: /api/v1/openapi.json

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

Вы можете создать сторонний каталог, директорию или поисковую поверхность поверх публичных API чтения ClawHub. Публичные метаданные Skills и файлы Skills публикуются по правилам лицензии Skills ClawHub, а сам API имеет ограничения частоты запросов и должен использоваться ответственно.

Рекомендации:

• Используйте публичные конечные точки чтения, такие как GET /api/v1/skills, GET /api/v1/search и GET /api/v1/skills/{slug}, для списков каталога.
• Кэшируйте ответы и учитывайте 429, Retry-After и заголовки ограничения частоты запросов вместо агрессивного опроса.
• При отображении списков добавляйте ссылку на канонический URL Skills ClawHub, чтобы пользователи могли проверить исходную запись реестра.
• Используйте канонические URL страниц в форме https://clawhub.ai/<owner>/skills/<slug>.
• Не создавайте впечатление, что ClawHub одобряет, проверяет или управляет сторонним сайтом.
• Не зеркалируйте скрытый, приватный или заблокированный модерацией контент, обходя публичные фильтры API или границы авторизации.

Авторизация

• Публичное чтение: токен не требуется.
• Запись + аккаунт: Authorization: Bearer clh_....

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

Применение с учетом авторизации:

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

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

• Отсутствующий/недействительный токен приводит к применению ограничения по IP.

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

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

• Загрузка: 1200/мин на IP, 6000/мин на ключ

Заголовки: X-RateLimit-Limit, X-RateLimit-Reset, RateLimit-Limit, RateLimit-Reset; X-RateLimit-Remaining, RateLimit-Remaining и Retry-After включаются при 429.

Семантика:

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

Пример 429:

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

Обработка клиентом:

• Предпочитайте Retry-After, если он присутствует.
• Иначе используйте RateLimit-Reset или вычисляйте задержку из X-RateLimit-Reset.
• Добавляйте джиттер к повторным попыткам.

Ошибки

• Ошибки v1 являются обычным текстом (text/plain; charset=utf-8), включая 400, 401, 403, 404, 429 и ответы заблокированных загрузок.
• Неизвестные параметры запроса игнорируются для совместимости.
• Известные параметры запроса с недопустимыми значениями возвращают 400.

Конечные точки

Публичное чтение:

• GET /api/v1/search?q=...
  • Необязательные фильтры: highlightedOnly=true, nonSuspiciousOnly=true
  • Устаревший псевдоним: nonSuspicious=true
• GET /api/v1/skills?limit=&cursor=&sort=
  • sort: updated (по умолчанию), recommended (default), createdAt (newest), downloads, stars (rating), устаревшие псевдонимы установки installsCurrent/installs/installsAllTime сопоставляются с downloads, trending
  • Недопустимые значения sort возвращают 400
  • cursor применяется к сортировкам, кроме trending
  • Необязательный фильтр: nonSuspiciousOnly=true
  • Устаревший псевдоним: nonSuspicious=true
  • С nonSuspiciousOnly=true страницы на основе курсора могут содержать меньше элементов, чем limit; используйте nextCursor, чтобы продолжить.
  • recommended использует сигналы вовлеченности и новизны.
• GET /api/v1/skills/{slug}
• GET /api/v1/skills/{slug}/moderation
• GET /api/v1/skills/{slug}/versions?limit=&cursor=
• GET /api/v1/skills/{slug}/versions/{version}
• GET /api/v1/skills/{slug}/scan?version=&tag=
• GET /api/v1/skills/{slug}/file?path=&version=&tag=
• GET /api/v1/resolve?slug=&hash=
• GET /api/v1/download?slug=&version=&tag=
  • Размещенные Skills возвращают детерминированные ZIP-байты.
  • Текущие Skills на базе GitHub со сканированием clean или suspicious возвращают JSON-дескриптор передачи public-github вместо байтов ClawHub.
• GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
  • Размещенные Skills экспортируются как сохраненные файлы.
  • Текущие Skills на базе GitHub со сканированием clean или suspicious экспортируются как дескрипторы передачи public-github.
• GET /api/v1/packages?limit=&cursor=&sort=
  • sort: updated (по умолчанию), recommended, downloads, устаревший псевдоним installs
  • Недопустимые значения sort возвращают 400
• GET /api/v1/plugins?limit=&cursor=&sort=
  • sort: recommended (по умолчанию), downloads, updated, устаревший псевдоним installs
• GET /api/v1/plugins/search?q=...
• GET /api/v1/packages/{name}/versions/{version}/artifact
• GET /api/v1/packages/{name}/versions/{version}/security
• GET /api/v1/packages/{name}/versions/{version}/artifact/download
• GET /api/npm/{package}
• GET /api/npm/{package}/-/{tarball}.tgz

Требуется авторизация:

• POST /api/v1/skills (публикация, multipart предпочтителен)
• DELETE /api/v1/skills/{slug}
• DELETE /api/v1/packages/{name}
• POST /api/v1/skills/{slug}/undelete
• POST /api/v1/packages/{name}/undelete
• POST /api/v1/skills/{slug}/rename
• POST /api/v1/skills/{slug}/merge
• POST /api/v1/skills/{slug}/transfer
• POST /api/v1/packages/{name}/transfer
• POST /api/v1/skills/{slug}/transfer/accept
• POST /api/v1/skills/{slug}/transfer/reject
• POST /api/v1/skills/{slug}/transfer/cancel
• GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
• GET /api/v1/plugins/export?startDate=&endDate=&limit=&cursor=&family=
• GET /api/v1/transfers/incoming
• GET /api/v1/transfers/outgoing
• GET /api/v1/whoami

Только администратор:

• POST /api/v1/users/reserve резервирует корневые slugs и приватные заглушки пакетов без выпусков для handle владельца.

Устаревшее

Устаревшие /api/* и /api/cli/* всё еще доступны. См. DEPRECATIONS.md.