aboutsummaryrefslogtreecommitdiffstats
path: root/packages/open-api
diff options
context:
space:
mode:
Diffstat (limited to 'packages/open-api')
-rw-r--r--packages/open-api/index.ts2
-rw-r--r--packages/open-api/karakeep-openapi-spec.json347
-rw-r--r--packages/open-api/lib/backups.ts149
3 files changed, 498 insertions, 0 deletions
diff --git a/packages/open-api/index.ts b/packages/open-api/index.ts
index 6f14807d..18f3cf75 100644
--- a/packages/open-api/index.ts
+++ b/packages/open-api/index.ts
@@ -7,6 +7,7 @@ import {
import { registry as adminRegistry } from "./lib/admin";
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 highlightsRegistry } from "./lib/highlights";
@@ -24,6 +25,7 @@ function getOpenApiDocumentation() {
userRegistry,
assetsRegistry,
adminRegistry,
+ backupsRegistry,
]);
const generator = new OpenApiGeneratorV3(registry.definitions);
diff --git a/packages/open-api/karakeep-openapi-spec.json b/packages/open-api/karakeep-openapi-spec.json
index c151f42d..4532cd98 100644
--- a/packages/open-api/karakeep-openapi-spec.json
+++ b/packages/open-api/karakeep-openapi-spec.json
@@ -45,6 +45,10 @@
"type": "string",
"example": "ieidlxygmwj87oxz5hxttoc8"
},
+ "BackupId": {
+ "type": "string",
+ "example": "ieidlxygmwj87oxz5hxttoc8"
+ },
"Bookmark": {
"type": "object",
"properties": {
@@ -596,6 +600,14 @@
"required": true,
"name": "assetId",
"in": "path"
+ },
+ "BackupId": {
+ "schema": {
+ "$ref": "#/components/schemas/BackupId"
+ },
+ "required": true,
+ "name": "backupId",
+ "in": "path"
}
}
},
@@ -3703,6 +3715,341 @@
}
}
}
+ },
+ "/backups": {
+ "get": {
+ "description": "Get all backups",
+ "summary": "Get all backups",
+ "tags": [
+ "Backups"
+ ],
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Object with all backups data.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "backups": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "userId": {
+ "type": "string"
+ },
+ "assetId": {
+ "type": "string",
+ "nullable": true
+ },
+ "createdAt": {
+ "type": "string"
+ },
+ "size": {
+ "type": "number"
+ },
+ "bookmarkCount": {
+ "type": "number"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "pending",
+ "success",
+ "failure"
+ ]
+ },
+ "errorMessage": {
+ "type": "string",
+ "nullable": true
+ }
+ },
+ "required": [
+ "id",
+ "userId",
+ "assetId",
+ "createdAt",
+ "size",
+ "bookmarkCount",
+ "status"
+ ]
+ }
+ }
+ },
+ "required": [
+ "backups"
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "post": {
+ "description": "Trigger a new backup",
+ "summary": "Trigger a new backup",
+ "tags": [
+ "Backups"
+ ],
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ],
+ "responses": {
+ "201": {
+ "description": "Backup created successfully",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "userId": {
+ "type": "string"
+ },
+ "assetId": {
+ "type": "string",
+ "nullable": true
+ },
+ "createdAt": {
+ "type": "string"
+ },
+ "size": {
+ "type": "number"
+ },
+ "bookmarkCount": {
+ "type": "number"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "pending",
+ "success",
+ "failure"
+ ]
+ },
+ "errorMessage": {
+ "type": "string",
+ "nullable": true
+ }
+ },
+ "required": [
+ "id",
+ "userId",
+ "assetId",
+ "createdAt",
+ "size",
+ "bookmarkCount",
+ "status"
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/backups/{backupId}": {
+ "get": {
+ "description": "Get backup by its id",
+ "summary": "Get a single backup",
+ "tags": [
+ "Backups"
+ ],
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ],
+ "parameters": [
+ {
+ "$ref": "#/components/parameters/BackupId"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Object with backup data.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "userId": {
+ "type": "string"
+ },
+ "assetId": {
+ "type": "string",
+ "nullable": true
+ },
+ "createdAt": {
+ "type": "string"
+ },
+ "size": {
+ "type": "number"
+ },
+ "bookmarkCount": {
+ "type": "number"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "pending",
+ "success",
+ "failure"
+ ]
+ },
+ "errorMessage": {
+ "type": "string",
+ "nullable": true
+ }
+ },
+ "required": [
+ "id",
+ "userId",
+ "assetId",
+ "createdAt",
+ "size",
+ "bookmarkCount",
+ "status"
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Backup not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "string"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "delete": {
+ "description": "Delete backup by its id",
+ "summary": "Delete a backup",
+ "tags": [
+ "Backups"
+ ],
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ],
+ "parameters": [
+ {
+ "$ref": "#/components/parameters/BackupId"
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No content - the backup was deleted"
+ },
+ "404": {
+ "description": "Backup not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "string"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/backups/{backupId}/download": {
+ "get": {
+ "description": "Download backup file",
+ "summary": "Download a backup",
+ "tags": [
+ "Backups"
+ ],
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ],
+ "parameters": [
+ {
+ "$ref": "#/components/parameters/BackupId"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Backup file (zip archive)",
+ "content": {
+ "application/zip": {
+ "schema": {}
+ }
+ }
+ },
+ "404": {
+ "description": "Backup not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "string"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
}
}
} \ No newline at end of file
diff --git a/packages/open-api/lib/backups.ts b/packages/open-api/lib/backups.ts
new file mode 100644
index 00000000..0ad29057
--- /dev/null
+++ b/packages/open-api/lib/backups.ts
@@ -0,0 +1,149 @@
+import {
+ extendZodWithOpenApi,
+ OpenAPIRegistry,
+} from "@asteasolutions/zod-to-openapi";
+import { z } from "zod";
+
+import { zBackupSchema } from "@karakeep/shared/types/backups";
+
+import { BearerAuth } from "./common";
+import { ErrorSchema } from "./errors";
+
+export const registry = new OpenAPIRegistry();
+extendZodWithOpenApi(z);
+
+export const BackupIdSchema = registry.registerParameter(
+ "BackupId",
+ z.string().openapi({
+ param: {
+ name: "backupId",
+ in: "path",
+ },
+ example: "ieidlxygmwj87oxz5hxttoc8",
+ }),
+);
+
+registry.registerPath({
+ method: "get",
+ path: "/backups",
+ description: "Get all backups",
+ summary: "Get all backups",
+ tags: ["Backups"],
+ security: [{ [BearerAuth.name]: [] }],
+ responses: {
+ 200: {
+ description: "Object with all backups data.",
+ content: {
+ "application/json": {
+ schema: z.object({
+ backups: z.array(zBackupSchema),
+ }),
+ },
+ },
+ },
+ },
+});
+
+registry.registerPath({
+ method: "post",
+ path: "/backups",
+ description: "Trigger a new backup",
+ summary: "Trigger a new backup",
+ tags: ["Backups"],
+ security: [{ [BearerAuth.name]: [] }],
+ responses: {
+ 201: {
+ description: "Backup created successfully",
+ content: {
+ "application/json": {
+ schema: zBackupSchema,
+ },
+ },
+ },
+ },
+});
+
+registry.registerPath({
+ method: "get",
+ path: "/backups/{backupId}",
+ description: "Get backup by its id",
+ summary: "Get a single backup",
+ tags: ["Backups"],
+ security: [{ [BearerAuth.name]: [] }],
+ request: {
+ params: z.object({ backupId: BackupIdSchema }),
+ },
+ responses: {
+ 200: {
+ description: "Object with backup data.",
+ content: {
+ "application/json": {
+ schema: zBackupSchema,
+ },
+ },
+ },
+ 404: {
+ description: "Backup not found",
+ content: {
+ "application/json": {
+ schema: ErrorSchema,
+ },
+ },
+ },
+ },
+});
+
+registry.registerPath({
+ method: "get",
+ path: "/backups/{backupId}/download",
+ description: "Download backup file",
+ summary: "Download a backup",
+ tags: ["Backups"],
+ security: [{ [BearerAuth.name]: [] }],
+ request: {
+ params: z.object({ backupId: BackupIdSchema }),
+ },
+ responses: {
+ 200: {
+ description: "Backup file (zip archive)",
+ content: {
+ "application/zip": {
+ schema: z.instanceof(Blob),
+ },
+ },
+ },
+ 404: {
+ description: "Backup not found",
+ content: {
+ "application/json": {
+ schema: ErrorSchema,
+ },
+ },
+ },
+ },
+});
+
+registry.registerPath({
+ method: "delete",
+ path: "/backups/{backupId}",
+ description: "Delete backup by its id",
+ summary: "Delete a backup",
+ tags: ["Backups"],
+ security: [{ [BearerAuth.name]: [] }],
+ request: {
+ params: z.object({ backupId: BackupIdSchema }),
+ },
+ responses: {
+ 204: {
+ description: "No content - the backup was deleted",
+ },
+ 404: {
+ description: "Backup not found",
+ content: {
+ "application/json": {
+ schema: ErrorSchema,
+ },
+ },
+ },
+ },
+});
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2026-01-30 08:35:15 +0000