Skip to content

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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.json
index 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 file
diff --git a/packages/open-api/lib/feeds.ts b/packages/open-api/lib/feeds.ts
new file mode 100644
index 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,
+ },
+ },
+ },
+ },
+});