A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search
feat(api): expose feed subscriptions via REST API (#2635)
Lars Wallenborn25ff6a79a9a0
diff --git a/packages/api/index.ts b/packages/api/index.tsindex ac31c977..1fa97b07 100644--- a/packages/api/index.ts+++ b/packages/api/index.ts@@ -14,6 +14,7 @@ import admin from "./routes/admin";import assets from "./routes/assets";import backups from "./routes/backups";import bookmarks from "./routes/bookmarks";+import feeds from "./routes/feeds";import health from "./routes/health";import highlights from "./routes/highlights";import lists from "./routes/lists";@@ -41,7 +42,8 @@ const v1 = new Hono<{.route("/assets", assets).route("/admin", admin).route("/rss", rss)- .route("/backups", backups);+ .route("/backups", backups)+ .route("/feeds", feeds);const app = new Hono<{Variables: {diff --git a/packages/api/routes/feeds.ts b/packages/api/routes/feeds.tsnew file mode 100644index 00000000..fe6f5d69--- /dev/null+++ b/packages/api/routes/feeds.ts@@ -0,0 +1,60 @@+import { zValidator } from "@hono/zod-validator";+import { Hono } from "hono";++import {+ zNewFeedSchema,+ zUpdateFeedSchema,+} from "@karakeep/shared/types/feeds";++import { authMiddleware } from "../middlewares/auth";++const app = new Hono()+ .use(authMiddleware)++ // GET /feeds+ .get("/", async (c) => {+ const feeds = await c.var.api.feeds.list();+ return c.json(feeds, 200);+ })++ // POST /feeds+ .post("/", zValidator("json", zNewFeedSchema), async (c) => {+ const body = c.req.valid("json");+ const feed = await c.var.api.feeds.create(body);+ return c.json(feed, 201);+ })++ // GET /feeds/:feedId+ .get("/:feedId", async (c) => {+ const feedId = c.req.param("feedId");+ const feed = await c.var.api.feeds.get({ feedId });+ return c.json(feed, 200);+ })++ // PATCH /feeds/:feedId+ .patch(+ "/:feedId",+ zValidator("json", zUpdateFeedSchema.omit({ feedId: true })),+ async (c) => {+ const feedId = c.req.param("feedId");+ const body = c.req.valid("json");+ const feed = await c.var.api.feeds.update({ feedId, ...body });+ return c.json(feed, 200);+ },+ )++ // DELETE /feeds/:feedId+ .delete("/:feedId", async (c) => {+ const feedId = c.req.param("feedId");+ await c.var.api.feeds.delete({ feedId });+ return c.body(null, 204);+ })++ // PUT /feeds/:feedId/fetch+ .put("/:feedId/fetch", async (c) => {+ const feedId = c.req.param("feedId");+ await c.var.api.feeds.fetchNow({ feedId });+ return c.body(null, 204);+ });++export default app;diff --git a/packages/open-api/index.ts b/packages/open-api/index.tsindex 0b8e3361..f8e5c7e5 100644--- a/packages/open-api/index.ts+++ b/packages/open-api/index.ts@@ -10,6 +10,7 @@ import { registry as assetsRegistry } from "./lib/assets";import { registry as backupsRegistry } from "./lib/backups";import { registry as bookmarksRegistry } from "./lib/bookmarks";import { registry as commonRegistry } from "./lib/common";+import { registry as feedsRegistry } from "./lib/feeds";import { registry as highlightsRegistry } from "./lib/highlights";import { registry as listsRegistry } from "./lib/lists";import { registry as tagsRegistry } from "./lib/tags";@@ -26,6 +27,7 @@ function getOpenApiDocumentation() {assetsRegistry,adminRegistry,backupsRegistry,+ feedsRegistry,]);const generator = new OpenApiGeneratorV3(registry.definitions);@@ -37,7 +39,7 @@ function getOpenApiDocumentation() {title: "Karakeep API",description:"Karakeep is a self-hostable bookmarking and read-it-later service. " +- "This API allows you to manage bookmarks, lists, tags, highlights, assets, and backups programmatically.\n\n" ++ "This API allows you to manage bookmarks, lists, tags, highlights, feeds, assets, and backups programmatically.\n\n" +"## Authentication\n\n" +"All endpoints require a Bearer token passed in the `Authorization` header. " +"You can generate an API key from the Karakeep web UI under **Settings > API Keys**.\n\n" +@@ -93,6 +95,11 @@ function getOpenApiDocumentation() {description:"Create and manage full account backups as downloadable zip archives.",},+ {+ name: "Feeds",+ description:+ "Manage RSS feed subscriptions. Create, update, delete, and trigger fetches for RSS feeds that automatically import bookmarks.",+ },],servers: [{diff --git a/packages/open-api/karakeep-openapi-spec.json b/packages/open-api/karakeep-openapi-spec.jsonindex 840306b4..c121fdef 100644--- a/packages/open-api/karakeep-openapi-spec.json+++ b/packages/open-api/karakeep-openapi-spec.json@@ -3,7 +3,7 @@"info": {"version": "1.0.0","title": "Karakeep API",- "description": "Karakeep is a self-hostable bookmarking and read-it-later service. This API allows you to manage bookmarks, lists, tags, highlights, assets, and backups programmatically.\n\n## Authentication\n\nAll endpoints require a Bearer token passed in the `Authorization` header. You can generate an API key from the Karakeep web UI under **Settings > API Keys**.\n\n## Pagination\n\nList endpoints support cursor-based pagination via `cursor` and `limit` query parameters. The response includes a `nextCursor` field — pass it as the `cursor` parameter to fetch the next page. A `null` value for `nextCursor` indicates there are no more results.\n\n## Bookmark Types\n\nBookmarks can be one of three types:\n- **link** — A URL bookmark with optional crawled metadata.\n- **text** — A plain text note.\n- **asset** — An uploaded file (image or PDF).\n\n## Rate Limiting\n\nWhen rate limiting is enabled, the API enforces per-IP request limits. If you exceed the allowed number of requests within the time window, the API returns a `429 Too Many Requests` response with a message indicating how many seconds to wait before retrying."+ "description": "Karakeep is a self-hostable bookmarking and read-it-later service. This API allows you to manage bookmarks, lists, tags, highlights, feeds, assets, and backups programmatically.\n\n## Authentication\n\nAll endpoints require a Bearer token passed in the `Authorization` header. You can generate an API key from the Karakeep web UI under **Settings > API Keys**.\n\n## Pagination\n\nList endpoints support cursor-based pagination via `cursor` and `limit` query parameters. The response includes a `nextCursor` field — pass it as the `cursor` parameter to fetch the next page. A `null` value for `nextCursor` indicates there are no more results.\n\n## Bookmark Types\n\nBookmarks can be one of three types:\n- **link** — A URL bookmark with optional crawled metadata.\n- **text** — A plain text note.\n- **asset** — An uploaded file (image or PDF).\n\n## Rate Limiting\n\nWhen rate limiting is enabled, the API enforces per-IP request limits. If you exceed the allowed number of requests within the time window, the API returns a `429 Too Many Requests` response with a message indicating how many seconds to wait before retrying."},"tags": [{@@ -37,6 +37,10 @@{"name": "Backups","description": "Create and manage full account backups as downloadable zip archives."+ },+ {+ "name": "Feeds",+ "description": "Manage RSS feed subscriptions. Create, update, delete, and trigger fetches for RSS feeds that automatically import bookmarks."}],"servers": [@@ -89,6 +93,11 @@"description": "The unique identifier of the backup.","example": "ieidlxygmwj87oxz5hxttoc8"},+ "FeedId": {+ "type": "string",+ "description": "The unique identifier of the feed.",+ "example": "ieidlxygmwj87oxz5hxttoc8"+ },"Bookmark": {"type": "object","properties": {@@ -637,7 +646,54 @@"fileName"]},- "File to be uploaded": {}+ "File to be uploaded": {},+ "Feed": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 100+ },+ "url": {+ "type": "string",+ "format": "uri"+ },+ "enabled": {+ "type": "boolean"+ },+ "importTags": {+ "type": "boolean"+ },+ "lastFetchedStatus": {+ "type": "string",+ "nullable": true,+ "enum": [+ "success",+ "failure",+ "pending"+ ]+ },+ "lastFetchedAt": {+ "type": "string",+ "nullable": true,+ "description": "ISO 8601 timestamp of the last fetch attempt, or null if never fetched.",+ "example": "2025-01-15T12:00:00.000Z"+ }+ },+ "required": [+ "id",+ "name",+ "url",+ "enabled",+ "importTags",+ "lastFetchedStatus",+ "lastFetchedAt"+ ]+ }},"parameters": {"BookmarkId": {@@ -687,6 +743,14 @@"required": true,"name": "backupId","in": "path"+ },+ "FeedId": {+ "schema": {+ "$ref": "#/components/schemas/FeedId"+ },+ "required": true,+ "name": "feedId",+ "in": "path"}}},@@ -4600,6 +4664,357 @@}}}+ },+ "/feeds": {+ "get": {+ "operationId": "listFeeds",+ "description": "Retrieve all RSS feed subscriptions for the authenticated user.",+ "summary": "Get all feeds",+ "tags": [+ "Feeds"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "A list of all feeds.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "feeds": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/Feed"+ }+ }+ },+ "required": [+ "feeds"+ ]+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized — the Bearer token is missing, invalid, or expired.",+ "content": {+ "text/plain": {+ "schema": {+ "type": "string",+ "example": "Unauthorized"+ }+ }+ }+ }+ }+ },+ "post": {+ "operationId": "createFeed",+ "description": "Create a new RSS feed subscription. The feed will be periodically fetched and matching items will be imported as bookmarks.",+ "summary": "Create a new feed",+ "tags": [+ "Feeds"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "description": "The feed to create.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 100+ },+ "url": {+ "type": "string",+ "maxLength": 2000,+ "format": "uri"+ },+ "enabled": {+ "type": "boolean"+ },+ "importTags": {+ "type": "boolean",+ "default": false+ }+ },+ "required": [+ "name",+ "url",+ "enabled"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "The created feed.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Feed"+ }+ }+ }+ },+ "400": {+ "description": "Bad request — e.g. the maximum number of RSS feeds per user has been reached.",+ "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"+ }+ }+ }+ }+ }+ }+ },+ "/feeds/{feedId}": {+ "get": {+ "operationId": "getFeed",+ "description": "Retrieve a single RSS feed subscription by its ID.",+ "summary": "Get a single feed",+ "tags": [+ "Feeds"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "$ref": "#/components/parameters/FeedId"+ }+ ],+ "responses": {+ "200": {+ "description": "The requested feed.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Feed"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized — the Bearer token is missing, invalid, or expired.",+ "content": {+ "text/plain": {+ "schema": {+ "type": "string",+ "example": "Unauthorized"+ }+ }+ }+ },+ "404": {+ "description": "Feed not found.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ }+ },+ "patch": {+ "operationId": "updateFeed",+ "description": "Update an RSS feed subscription. Only provided fields will be changed.",+ "summary": "Update a feed",+ "tags": [+ "Feeds"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "$ref": "#/components/parameters/FeedId"+ }+ ],+ "requestBody": {+ "description": "The fields to update.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 100+ },+ "url": {+ "type": "string",+ "maxLength": 2000,+ "format": "uri"+ },+ "enabled": {+ "type": "boolean"+ },+ "importTags": {+ "type": "boolean"+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "The updated feed.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Feed"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized — the Bearer token is missing, invalid, or expired.",+ "content": {+ "text/plain": {+ "schema": {+ "type": "string",+ "example": "Unauthorized"+ }+ }+ }+ },+ "404": {+ "description": "Feed not found.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ }+ },+ "delete": {+ "operationId": "deleteFeed",+ "description": "Delete an RSS feed subscription. Previously imported bookmarks are not affected.",+ "summary": "Delete a feed",+ "tags": [+ "Feeds"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "$ref": "#/components/parameters/FeedId"+ }+ ],+ "responses": {+ "204": {+ "description": "No content — the feed was deleted successfully."+ },+ "401": {+ "description": "Unauthorized — the Bearer token is missing, invalid, or expired.",+ "content": {+ "text/plain": {+ "schema": {+ "type": "string",+ "example": "Unauthorized"+ }+ }+ }+ },+ "404": {+ "description": "Feed not found.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ }+ }+ },+ "/feeds/{feedId}/fetch": {+ "put": {+ "operationId": "fetchFeedNow",+ "description": "Trigger an immediate fetch of the RSS feed. The fetch is enqueued and processed asynchronously.",+ "summary": "Trigger a feed fetch",+ "tags": [+ "Feeds"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "$ref": "#/components/parameters/FeedId"+ }+ ],+ "responses": {+ "204": {+ "description": "No content — the fetch has been enqueued."+ },+ "401": {+ "description": "Unauthorized — the Bearer token is missing, invalid, or expired.",+ "content": {+ "text/plain": {+ "schema": {+ "type": "string",+ "example": "Unauthorized"+ }+ }+ }+ },+ "404": {+ "description": "Feed not found.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ }+ }}}}\ No newline at end of filediff --git a/packages/open-api/lib/feeds.ts b/packages/open-api/lib/feeds.tsnew file mode 100644index 00000000..ef4e04e0--- /dev/null+++ b/packages/open-api/lib/feeds.ts@@ -0,0 +1,234 @@+import {+ extendZodWithOpenApi,+ OpenAPIRegistry,+} from "@asteasolutions/zod-to-openapi";+import { z } from "zod";++import {+ zFeedSchema,+ zNewFeedSchema,+ zUpdateFeedSchema,+} from "@karakeep/shared/types/feeds";++import { BearerAuth } from "./common";+import { ErrorSchema, UnauthorizedResponse } from "./errors";++export const registry = new OpenAPIRegistry();+extendZodWithOpenApi(z);++const FeedSchema = zFeedSchema+ .extend({+ lastFetchedAt: z.string().nullable().openapi({+ description:+ "ISO 8601 timestamp of the last fetch attempt, or null if never fetched.",+ example: "2025-01-15T12:00:00.000Z",+ }),+ })+ .openapi("Feed");++export const FeedIdSchema = registry.registerParameter(+ "FeedId",+ z.string().openapi({+ param: {+ name: "feedId",+ in: "path",+ },+ description: "The unique identifier of the feed.",+ example: "ieidlxygmwj87oxz5hxttoc8",+ }),+);++registry.registerPath({+ operationId: "listFeeds",+ method: "get",+ path: "/feeds",+ description:+ "Retrieve all RSS feed subscriptions for the authenticated user.",+ summary: "Get all feeds",+ tags: ["Feeds"],+ security: [{ [BearerAuth.name]: [] }],+ request: {},+ responses: {+ 200: {+ description: "A list of all feeds.",+ content: {+ "application/json": {+ schema: z.object({+ feeds: z.array(FeedSchema),+ }),+ },+ },+ },+ 401: UnauthorizedResponse,+ },+});++registry.registerPath({+ operationId: "createFeed",+ method: "post",+ path: "/feeds",+ description:+ "Create a new RSS feed subscription. The feed will be periodically fetched and matching items will be imported as bookmarks.",+ summary: "Create a new feed",+ tags: ["Feeds"],+ security: [{ [BearerAuth.name]: [] }],+ request: {+ body: {+ description: "The feed to create.",+ content: {+ "application/json": {+ schema: zNewFeedSchema,+ },+ },+ },+ },+ responses: {+ 201: {+ description: "The created feed.",+ content: {+ "application/json": {+ schema: FeedSchema,+ },+ },+ },+ 400: {+ description:+ "Bad request — e.g. the maximum number of RSS feeds per user has been reached.",+ content: {+ "application/json": {+ schema: ErrorSchema,+ },+ },+ },+ 401: UnauthorizedResponse,+ },+});++registry.registerPath({+ operationId: "getFeed",+ method: "get",+ path: "/feeds/{feedId}",+ description: "Retrieve a single RSS feed subscription by its ID.",+ summary: "Get a single feed",+ tags: ["Feeds"],+ security: [{ [BearerAuth.name]: [] }],+ request: {+ params: z.object({ feedId: FeedIdSchema }),+ },+ responses: {+ 200: {+ description: "The requested feed.",+ content: {+ "application/json": {+ schema: FeedSchema,+ },+ },+ },+ 401: UnauthorizedResponse,+ 404: {+ description: "Feed not found.",+ content: {+ "application/json": {+ schema: ErrorSchema,+ },+ },+ },+ },+});++registry.registerPath({+ operationId: "updateFeed",+ method: "patch",+ path: "/feeds/{feedId}",+ description:+ "Update an RSS feed subscription. Only provided fields will be changed.",+ summary: "Update a feed",+ tags: ["Feeds"],+ security: [{ [BearerAuth.name]: [] }],+ request: {+ params: z.object({ feedId: FeedIdSchema }),+ body: {+ description: "The fields to update.",+ content: {+ "application/json": {+ schema: zUpdateFeedSchema.omit({ feedId: true }),+ },+ },+ },+ },+ responses: {+ 200: {+ description: "The updated feed.",+ content: {+ "application/json": {+ schema: FeedSchema,+ },+ },+ },+ 401: UnauthorizedResponse,+ 404: {+ description: "Feed not found.",+ content: {+ "application/json": {+ schema: ErrorSchema,+ },+ },+ },+ },+});++registry.registerPath({+ operationId: "deleteFeed",+ method: "delete",+ path: "/feeds/{feedId}",+ description:+ "Delete an RSS feed subscription. Previously imported bookmarks are not affected.",+ summary: "Delete a feed",+ tags: ["Feeds"],+ security: [{ [BearerAuth.name]: [] }],+ request: {+ params: z.object({ feedId: FeedIdSchema }),+ },+ responses: {+ 204: {+ description: "No content — the feed was deleted successfully.",+ },+ 401: UnauthorizedResponse,+ 404: {+ description: "Feed not found.",+ content: {+ "application/json": {+ schema: ErrorSchema,+ },+ },+ },+ },+});++registry.registerPath({+ operationId: "fetchFeedNow",+ method: "put",+ path: "/feeds/{feedId}/fetch",+ description:+ "Trigger an immediate fetch of the RSS feed. The fetch is enqueued and processed asynchronously.",+ summary: "Trigger a feed fetch",+ tags: ["Feeds"],+ security: [{ [BearerAuth.name]: [] }],+ request: {+ params: z.object({ feedId: FeedIdSchema }),+ },+ responses: {+ 204: {+ description: "No content — the fetch has been enqueued.",+ },+ 401: UnauthorizedResponse,+ 404: {+ description: "Feed not found.",+ content: {+ "application/json": {+ schema: ErrorSchema,+ },+ },+ },+ },+});