Skip to content

A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search

feat(api): add admin REST endpoints to trigger background jobs (#2564)

Mohamed Bassem4974ce5819cc
diff --git a/packages/api/routes/admin.ts b/packages/api/routes/admin.ts
index 4b5438d6..523c0e5b 100644
--- a/packages/api/routes/admin.ts
+++ b/packages/api/routes/admin.ts
@@ -1,5 +1,6 @@
import { zValidator } from "@hono/zod-validator";
import { Hono } from "hono";
+import { z } from "zod";
import { updateUserSchema } from "@karakeep/shared/types/admin";
@@ -19,6 +20,48 @@ const app = new Hono()
await c.var.api.admin.updateUser(input);
return c.json({ success: true }, 200);
- });
+ })
+
+ // POST /admin/jobs/trigger/recrawl
+ .post(
+ "/jobs/trigger/recrawl",
+ zValidator(
+ "json",
+ z.object({
+ crawlStatus: z
+ .enum(["success", "failure", "pending", "all"])
+ .default("all"),
+ runInference: z.boolean().default(false),
+ }),
+ ),
+ async (c) => {
+ const body = c.req.valid("json");
+ await c.var.api.admin.recrawlLinks(body);
+ return c.json({ success: true }, 200);
+ },
+ )
+
+ // POST /admin/jobs/trigger/reindex
+ .post("/jobs/trigger/reindex", async (c) => {
+ await c.var.api.admin.reindexAllBookmarks();
+ return c.json({ success: true }, 200);
+ })
+
+ // POST /admin/jobs/trigger/inference
+ .post(
+ "/jobs/trigger/inference",
+ zValidator(
+ "json",
+ z.object({
+ type: z.enum(["tag", "summarize"]),
+ status: z.enum(["success", "failure", "pending", "all"]).default("all"),
+ }),
+ ),
+ async (c) => {
+ const body = c.req.valid("json");
+ await c.var.api.admin.reRunInferenceOnAllBookmarks(body);
+ return c.json({ success: true }, 200);
+ },
+ );
export default app;
diff --git a/packages/open-api/karakeep-openapi-spec.json b/packages/open-api/karakeep-openapi-spec.json
index b811fbe7..f8864f34 100644
--- a/packages/open-api/karakeep-openapi-spec.json
+++ b/packages/open-api/karakeep-openapi-spec.json
@@ -3980,6 +3980,268 @@
}
}
},
+ "/admin/jobs/trigger/recrawl": {
+ "post": {
+ "operationId": "adminTriggerRecrawl",
+ "description": "Trigger a recrawl of link bookmarks. You can filter by crawl status to target specific bookmarks (e.g., only failed ones). Optionally run AI inference after crawling. Requires admin role.",
+ "summary": "Trigger recrawl of links (admin)",
+ "tags": [
+ "Admin"
+ ],
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ],
+ "requestBody": {
+ "description": "Options for the recrawl job.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "crawlStatus": {
+ "type": "string",
+ "enum": [
+ "success",
+ "failure",
+ "pending",
+ "all"
+ ],
+ "default": "all",
+ "description": "Filter bookmarks by their crawl status. Use 'failure' to retry only failed crawls."
+ },
+ "runInference": {
+ "type": "boolean",
+ "default": false,
+ "description": "Whether to run AI inference after crawling."
+ }
+ },
+ "example": {
+ "crawlStatus": "failure",
+ "runInference": false
+ }
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Recrawl jobs triggered successfully.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "success": {
+ "type": "boolean",
+ "description": "Whether the job was triggered successfully."
+ }
+ },
+ "required": [
+ "success"
+ ]
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad request — invalid input data.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Unauthorized — the Bearer token is missing, invalid, or expired.",
+ "content": {
+ "text/plain": {
+ "schema": {
+ "type": "string",
+ "example": "Unauthorized"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden — admin access required.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/admin/jobs/trigger/reindex": {
+ "post": {
+ "operationId": "adminTriggerReindex",
+ "description": "Trigger a reindex of all bookmarks in the search engine. This clears the existing index and re-queues all bookmarks for indexing. Requires admin role.",
+ "summary": "Trigger reindex of all bookmarks (admin)",
+ "tags": [
+ "Admin"
+ ],
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Reindex jobs triggered successfully.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "success": {
+ "type": "boolean",
+ "description": "Whether the job was triggered successfully."
+ }
+ },
+ "required": [
+ "success"
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Unauthorized — the Bearer token is missing, invalid, or expired.",
+ "content": {
+ "text/plain": {
+ "schema": {
+ "type": "string",
+ "example": "Unauthorized"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden — admin access required.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/admin/jobs/trigger/inference": {
+ "post": {
+ "operationId": "adminTriggerInference",
+ "description": "Trigger AI inference (tagging or summarization) on bookmarks. You can filter by status to target specific bookmarks (e.g., only failed ones). Requires admin role.",
+ "summary": "Trigger AI inference on bookmarks (admin)",
+ "tags": [
+ "Admin"
+ ],
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ],
+ "requestBody": {
+ "description": "Options for the inference job.",
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "tag",
+ "summarize"
+ ],
+ "description": "The type of inference to run: 'tag' for AI tagging, 'summarize' for AI summarization."
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "success",
+ "failure",
+ "pending",
+ "all"
+ ],
+ "default": "all",
+ "description": "Filter bookmarks by their inference status. Use 'failure' to retry only failed ones."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "example": {
+ "type": "tag",
+ "status": "failure"
+ }
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Inference jobs triggered successfully.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "success": {
+ "type": "boolean",
+ "description": "Whether the job was triggered successfully."
+ }
+ },
+ "required": [
+ "success"
+ ]
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Bad request — invalid input data.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Unauthorized — the Bearer token is missing, invalid, or expired.",
+ "content": {
+ "text/plain": {
+ "schema": {
+ "type": "string",
+ "example": "Unauthorized"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Forbidden — admin access required.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
"/backups": {
"get": {
"operationId": "listBackups",
diff --git a/packages/open-api/lib/admin.ts b/packages/open-api/lib/admin.ts
index fbc649f0..fc0f65d0 100644
--- a/packages/open-api/lib/admin.ts
+++ b/packages/open-api/lib/admin.ts
@@ -18,6 +18,19 @@ const updateUserResponseSchema = z.object({
success: z.boolean().describe("Whether the update was successful."),
});
+const adminJobSuccessResponseSchema = z.object({
+ success: z.boolean().describe("Whether the job was triggered successfully."),
+});
+
+const adminForbiddenResponse = {
+ description: "Forbidden — admin access required.",
+ content: {
+ "application/json": {
+ schema: ErrorSchema,
+ },
+ },
+};
+
registry.registerPath({
operationId: "adminUpdateUser",
method: "put",
@@ -71,21 +84,160 @@ registry.registerPath({
},
},
401: UnauthorizedResponse,
- 403: {
- description: "Forbidden — admin access required.",
+ 403: adminForbiddenResponse,
+ 404: {
+ description: "User not found.",
content: {
"application/json": {
schema: ErrorSchema,
},
},
},
- 404: {
- description: "User not found.",
+ },
+});
+
+registry.registerPath({
+ operationId: "adminTriggerRecrawl",
+ method: "post",
+ path: "/admin/jobs/trigger/recrawl",
+ description:
+ "Trigger a recrawl of link bookmarks. You can filter by crawl status to target specific bookmarks " +
+ "(e.g., only failed ones). Optionally run AI inference after crawling. Requires admin role.",
+ summary: "Trigger recrawl of links (admin)",
+ tags: ["Admin"],
+ security: [{ [BearerAuth.name]: [] }],
+ request: {
+ body: {
+ description: "Options for the recrawl job.",
+ content: {
+ "application/json": {
+ schema: z
+ .object({
+ crawlStatus: z
+ .enum(["success", "failure", "pending", "all"])
+ .default("all")
+ .describe(
+ "Filter bookmarks by their crawl status. Use 'failure' to retry only failed crawls.",
+ ),
+ runInference: z
+ .boolean()
+ .default(false)
+ .describe("Whether to run AI inference after crawling."),
+ })
+ .openapi({
+ example: {
+ crawlStatus: "failure",
+ runInference: false,
+ },
+ }),
+ },
+ },
+ },
+ },
+ responses: {
+ 200: {
+ description: "Recrawl jobs triggered successfully.",
+ content: {
+ "application/json": {
+ schema: adminJobSuccessResponseSchema,
+ },
+ },
+ },
+ 400: {
+ description: "Bad request — invalid input data.",
+ content: {
+ "application/json": {
+ schema: ErrorSchema,
+ },
+ },
+ },
+ 401: UnauthorizedResponse,
+ 403: adminForbiddenResponse,
+ },
+});
+
+registry.registerPath({
+ operationId: "adminTriggerReindex",
+ method: "post",
+ path: "/admin/jobs/trigger/reindex",
+ description:
+ "Trigger a reindex of all bookmarks in the search engine. This clears the existing index and " +
+ "re-queues all bookmarks for indexing. Requires admin role.",
+ summary: "Trigger reindex of all bookmarks (admin)",
+ tags: ["Admin"],
+ security: [{ [BearerAuth.name]: [] }],
+ responses: {
+ 200: {
+ description: "Reindex jobs triggered successfully.",
+ content: {
+ "application/json": {
+ schema: adminJobSuccessResponseSchema,
+ },
+ },
+ },
+ 401: UnauthorizedResponse,
+ 403: adminForbiddenResponse,
+ },
+});
+
+registry.registerPath({
+ operationId: "adminTriggerInference",
+ method: "post",
+ path: "/admin/jobs/trigger/inference",
+ description:
+ "Trigger AI inference (tagging or summarization) on bookmarks. You can filter by status " +
+ "to target specific bookmarks (e.g., only failed ones). Requires admin role.",
+ summary: "Trigger AI inference on bookmarks (admin)",
+ tags: ["Admin"],
+ security: [{ [BearerAuth.name]: [] }],
+ request: {
+ body: {
+ description: "Options for the inference job.",
+ required: true,
+ content: {
+ "application/json": {
+ schema: z
+ .object({
+ type: z
+ .enum(["tag", "summarize"])
+ .describe(
+ "The type of inference to run: 'tag' for AI tagging, 'summarize' for AI summarization.",
+ ),
+ status: z
+ .enum(["success", "failure", "pending", "all"])
+ .default("all")
+ .describe(
+ "Filter bookmarks by their inference status. Use 'failure' to retry only failed ones.",
+ ),
+ })
+ .openapi({
+ example: {
+ type: "tag",
+ status: "failure",
+ },
+ }),
+ },
+ },
+ },
+ },
+ responses: {
+ 200: {
+ description: "Inference jobs triggered successfully.",
+ content: {
+ "application/json": {
+ schema: adminJobSuccessResponseSchema,
+ },
+ },
+ },
+ 400: {
+ description: "Bad request — invalid input data.",
content: {
"application/json": {
schema: ErrorSchema,
},
},
},
+ 401: UnauthorizedResponse,
+ 403: adminForbiddenResponse,
},
});