feat: add v1 public api

Author: steipete

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.0.6 - 2026-01-07
+
+### Added
+- API: v1 public REST endpoints with rate limits, raw file fetch, and OpenAPI spec.
+- Docs: `docs/api.md` and `DEPRECATIONS.md` for the v1 cutover plan.
+
+### Changed
+- CLI: publish now uses single multipart `POST /api/v1/skills`.
+- Registry: legacy `/api/*` + `/api/cli/*` marked for deprecation (kept for now).
+
 ## 0.0.5 - 2026-01-06
 
 ### Added

DEPRECATIONS.md

@@ -0,0 +1,7 @@
+# Deprecations
+
+## Legacy /api routes (pre-v1)
+
+- Deprecated: 2026-01-07
+- TODO: remove legacy `/api/*` and `/api/cli/*` routes after clients migrate to `/api/v1`.
+- Legacy handlers live in `convex/http.ts` and `convex/httpApi.ts`.

convex/_generated/api.d.ts

@@ -13,6 +13,7 @@ import type * as comments from "../comments.js";
 import type * as downloads from "../downloads.js";
 import type * as http from "../http.js";
 import type * as httpApi from "../httpApi.js";
+import type * as httpApiV1 from "../httpApiV1.js";
 import type * as lib_access from "../lib/access.js";
 import type * as lib_apiTokenAuth from "../lib/apiTokenAuth.js";
 import type * as lib_changelog from "../lib/changelog.js";
@@ -23,6 +24,7 @@ import type * as lib_skills from "../lib/skills.js";
 import type * as lib_tokens from "../lib/tokens.js";
 import type * as lib_webhooks from "../lib/webhooks.js";
 import type * as maintenance from "../maintenance.js";
+import type * as rateLimits from "../rateLimits.js";
 import type * as search from "../search.js";
 import type * as skills from "../skills.js";
 import type * as stars from "../stars.js";
@@ -44,6 +46,7 @@ declare const fullApi: ApiFromModules<{
   downloads: typeof downloads;
   http: typeof http;
   httpApi: typeof httpApi;
+  httpApiV1: typeof httpApiV1;
   "lib/access": typeof lib_access;
   "lib/apiTokenAuth": typeof lib_apiTokenAuth;
   "lib/changelog": typeof lib_changelog;
@@ -54,6 +57,7 @@ declare const fullApi: ApiFromModules<{
   "lib/tokens": typeof lib_tokens;
   "lib/webhooks": typeof lib_webhooks;
   maintenance: typeof maintenance;
+  rateLimits: typeof rateLimits;
   search: typeof search;
   skills: typeof skills;
   stars: typeof stars;

convex/http.ts

@@ -1,4 +1,4 @@
-import { ApiRoutes } from 'clawdhub-schema'
+import { ApiRoutes, LegacyApiRoutes } from 'clawdhub-schema'
 import { httpRouter } from 'convex/server'
 import { auth } from './auth'
 import { downloadZip } from './downloads'
@@ -13,6 +13,16 @@ import {
   resolveSkillVersionHttp,
   searchSkillsHttp,
 } from './httpApi'
+import {
+  listSkillsV1Http,
+  publishSkillV1Http,
+  resolveSkillVersionV1Http,
+  searchSkillsV1Http,
+  skillsDeleteRouterV1Http,
+  skillsGetRouterV1Http,
+  skillsPostRouterV1Http,
+  whoamiV1Http,
+} from './httpApiV1'
 
 const http = httpRouter()
 
@@ -27,53 +37,107 @@ http.route({
 http.route({
   path: ApiRoutes.search,
   method: 'GET',
+  handler: searchSkillsV1Http,
+})
+
+http.route({
+  path: ApiRoutes.resolve,
+  method: 'GET',
+  handler: resolveSkillVersionV1Http,
+})
+
+http.route({
+  path: ApiRoutes.skills,
+  method: 'GET',
+  handler: listSkillsV1Http,
+})
+
+http.route({
+  pathPrefix: `${ApiRoutes.skills}/`,
+  method: 'GET',
+  handler: skillsGetRouterV1Http,
+})
+
+http.route({
+  path: ApiRoutes.skills,
+  method: 'POST',
+  handler: publishSkillV1Http,
+})
+
+http.route({
+  pathPrefix: `${ApiRoutes.skills}/`,
+  method: 'POST',
+  handler: skillsPostRouterV1Http,
+})
+
+http.route({
+  pathPrefix: `${ApiRoutes.skills}/`,
+  method: 'DELETE',
+  handler: skillsDeleteRouterV1Http,
+})
+
+http.route({
+  path: ApiRoutes.whoami,
+  method: 'GET',
+  handler: whoamiV1Http,
+})
+
+// TODO: remove legacy /api routes after deprecation window.
+http.route({
+  path: LegacyApiRoutes.download,
+  method: 'GET',
+  handler: downloadZip,
+})
+http.route({
+  path: LegacyApiRoutes.search,
+  method: 'GET',
   handler: searchSkillsHttp,
 })
 
 http.route({
-  path: ApiRoutes.skill,
+  path: LegacyApiRoutes.skill,
   method: 'GET',
   handler: getSkillHttp,
 })
 
 http.route({
-  path: ApiRoutes.skillResolve,
+  path: LegacyApiRoutes.skillResolve,
   method: 'GET',
   handler: resolveSkillVersionHttp,
 })
 
 http.route({
-  path: ApiRoutes.cliWhoami,
+  path: LegacyApiRoutes.cliWhoami,
   method: 'GET',
   handler: cliWhoamiHttp,
 })
 
 http.route({
-  path: ApiRoutes.cliUploadUrl,
+  path: LegacyApiRoutes.cliUploadUrl,
   method: 'POST',
   handler: cliUploadUrlHttp,
 })
 
 http.route({
-  path: ApiRoutes.cliPublish,
+  path: LegacyApiRoutes.cliPublish,
   method: 'POST',
   handler: cliPublishHttp,
 })
 
 http.route({
-  path: ApiRoutes.cliTelemetrySync,
+  path: LegacyApiRoutes.cliTelemetrySync,
   method: 'POST',
   handler: cliTelemetrySyncHttp,
 })
 
 http.route({
-  path: ApiRoutes.cliSkillDelete,
+  path: LegacyApiRoutes.cliSkillDelete,
   method: 'POST',
   handler: cliSkillDeleteHttp,
 })
 
 http.route({
-  path: ApiRoutes.cliSkillUndelete,
+  path: LegacyApiRoutes.cliSkillUndelete,
   method: 'POST',
   handler: cliSkillUndeleteHttp,
 })