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.tsindex 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.jsonindex 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.tsindex 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,},});