karakeep-python-api 1.8.0__py3-none-any.whl → 1.9.0__py3-none-any.whl

karakeep_python_api/__main__.py

@@ -538,7 +538,23 @@ def create_click_command(
                     ctx.exit(1)
 
                 # Serialize and print the result
-                if result is not None:
+                if isinstance(result, (bytes, bytearray)):
+                    # Binary payloads (e.g. download_a_backup, get_a_single_asset)
+                    # cannot be JSON encoded: write them raw to stdout so the
+                    # output can be redirected straight into a file.
+                    logger.debug(f"Writing {len(result)} raw bytes to stdout.")
+                    stdout_buffer = getattr(sys.stdout, "buffer", None)
+                    if stdout_buffer is not None:
+                        stdout_buffer.write(result)
+                        stdout_buffer.flush()
+                    else:
+                        # Some test/capture harnesses replace sys.stdout with a
+                        # text-only stream that has no .buffer attribute.
+                        sys.stdout.write(
+                            bytes(result).decode("utf-8", errors="surrogateescape")
+                        )
+                        sys.stdout.flush()
+                elif result is not None:
                     output_data = serialize_output(result)
                     # Use ensure_ascii_output flag to control JSON encoding
                     click.echo(

karakeep_python_api/datatypes.py

@@ -53,6 +53,15 @@ class ContentTypeLink(BaseModel):
     favicon: Optional[str] = None
     htmlContent: Optional[str] = None
     contentAssetId: Optional[str] = None
+    # Reader-view triage produced by the crawler: readerViewStatus says whether a
+    # distraction-free rendering could be extracted, readerViewScore (0-100) how
+    # confident that extraction is, and preferredPreview which of the available
+    # renderings the UI should show by default.
+    readerViewStatus: Optional[
+        Literal["readable", "not_readable", "uncertain", "unavailable"]
+    ] = None
+    readerViewScore: Optional[int] = None
+    preferredPreview: Optional[Literal["reader_view", "screenshot", "overview"]] = None
     crawledAt: Optional[str] = None
     crawlStatus: Optional[Literal["success", "failure", "pending"]] = None
     author: Optional[str] = None
@@ -112,8 +121,20 @@ class UploadedAsset(BaseModel):
 Asset = UploadedAsset
 
 
+class SignedAssetUrl(BaseModel):
+    assetId: str
+    # Temporary download URL that carries its own signature, so it works without
+    # the Authorization header and can be handed to a browser or media player.
+    signedUrl: str
+    expiresAt: str
+
+
 class Bookmark(BaseModel):
     id: str
+    # firstCreatedAt records the original creation time when a bookmark is
+    # recreated/re-imported, so it can predate createdAt. Optional in the spec
+    # and absent on Karakeep servers older than the one that introduced it.
+    firstCreatedAt: Optional[str] = None
     createdAt: str
     modifiedAt: Optional[str]
     title: Optional[str] = None
@@ -121,6 +142,10 @@ class Bookmark(BaseModel):
     favourited: bool
     taggingStatus: Optional[Literal["success", "failure", "pending"]] = None
     summarizationStatus: Optional[Literal["success", "failure", "pending"]] = None
+    # Status of the vector-embedding job used by semantic/hybrid search. The
+    # spec marks it required-but-nullable, so no default is given here: a
+    # missing key is a genuine mismatch with the documented server response.
+    embeddingStatus: Optional[Literal["success", "failure", "pending"]]
     note: Optional[str] = None
     summary: Optional[str] = None
     source: Optional[
@@ -136,6 +161,28 @@ class Bookmark(BaseModel):
     assets: List[BookmarkAsset]
 
 
+class ReadableContentRange(BaseModel):
+    # Offsets are in Unicode characters over the *rendered* content, not bytes:
+    # start is inclusive, end is exclusive, and total is the full rendered length.
+    start: int
+    end: int
+    total: int
+
+
+class BookmarkReadableContent(BaseModel):
+    bookmarkId: str
+    bookmarkType: Literal["link", "text", "asset"]
+    format: Literal["markdown", "text"]
+    content: str
+    # Hash of the rendered content the cursor was issued against. The server
+    # answers 409 if the bookmark changed between two chunks, so this value must
+    # not be mixed across a paginated read.
+    contentVersion: str
+    range: ReadableContentRange
+    nextCursor: Optional[str]
+    truncated: bool
+
+
 class PaginatedBookmarks(BaseModel):
     bookmarks: List[Bookmark]
     nextCursor: Optional[str] = ""

karakeep_python_api/karakeep_api.py

@@ -85,7 +85,7 @@ class KarakeepAPI:
     """
 
     # Version reflects the client library version, updated by bumpver
-    VERSION: str = "1.8.0"
+    VERSION: str = "1.9.0"
 
     def __init__(
         self,
@@ -891,16 +891,25 @@ class KarakeepAPI:
     def search_bookmarks(
         self,
         q: str,  # Search query is required
+        search_mode: Optional[Literal["fts", "semantic", "hybrid"]] = None,
         sort_order: Optional[Literal["asc", "desc", "relevance"]] = None,
         limit: Optional[int] = None,
         cursor: Optional[str] = None,
         include_content: bool = True,  # Default from spec
     ) -> Union[datatypes.PaginatedBookmarks, Dict[str, Any], List[Any]]:
         """
-        Search bookmarks. Corresponds to GET /bookmarks/search.
+        Search bookmarks using full-text, semantic or hybrid ranking.
+        Corresponds to GET /bookmarks/search.
 
         Args:
             q: The search query string.
+            search_mode: Search strategy (optional). "fts" is full-text search (API default),
+                         "semantic" ranks with bookmark embeddings, and "hybrid" fuses both.
+                         Hybrid falls back to full-text search when the query has no free-text
+                         terms or when embedding infrastructure is unavailable. Semantic hits
+                         below a minimum similarity are dropped, so "semantic" and "hybrid" may
+                         return fewer results than `limit`. Note that the semantic modes only
+                         support sort_order="relevance".
             sort_order: Sort order for results ("asc", "desc", "relevance"). Default from API is "relevance" (optional).
             limit: Maximum number of bookmarks to return (optional).
             cursor: Pagination cursor for the next page (optional).
@@ -916,6 +925,7 @@ class KarakeepAPI:
         """
         params = {
             "q": q,
+            "searchMode": search_mode,
             "sortOrder": sort_order,
             "limit": limit,
             "cursor": cursor,
@@ -1051,6 +1061,101 @@ class KarakeepAPI:
         # No Pydantic validation applied here as the spec defines a partial response (dict)
         return response_data
 
+    @optional_typecheck
+    def get_bookmark_readable_content(
+        self,
+        bookmark_id: str,
+        format: Optional[Literal["markdown", "text"]] = None,
+        max_chars: Optional[int] = None,
+        cursor: Optional[str] = None,
+        fetch_all: bool = False,
+    ) -> Union[datatypes.BookmarkReadableContent, Dict[str, Any], List[Any]]:
+        """
+        Get an agent-readable rendering of a bookmark's content.
+        Corresponds to GET /bookmarks/{bookmarkId}/content.
+
+        Link content is rendered from the extracted HTML; text and asset bookmarks use
+        their stored or extracted text. The endpoint returns a bounded chunk plus an
+        opaque `nextCursor`; pass that cursor back to continue reading, or set
+        `fetch_all=True` to let this method walk the cursors and return the whole
+        document as a single object.
+
+        Args:
+            bookmark_id: The ID (string) of the bookmark to read.
+            format: Readable representation, "markdown" or "text" (optional). If omitted
+                    together with a cursor, the cursor's own format is reused; otherwise
+                    the API defaults to "markdown".
+            max_chars: Maximum number of Unicode characters per chunk, 1 to 50000
+                       (optional, API default 12000). A chunk may end earlier, at a
+                       paragraph or line boundary.
+            cursor: Opaque continuation cursor returned as `nextCursor` by a previous
+                    response (optional).
+            fetch_all: If True, keep following `nextCursor` until the document is
+                       exhausted and return one merged object whose `content` is the
+                       concatenation of every chunk, with `nextCursor=None` and
+                       `truncated=False` (default: False).
+
+        Returns:
+            datatypes.BookmarkReadableContent: A chunk of readable content (or the whole
+            document when fetch_all is True).
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails (e.g. 404 bookmark not found, or 409 if
+                      the bookmark content changed after the supplied cursor was issued).
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        endpoint = f"bookmarks/{bookmark_id}/content"
+        params = {
+            "format": format,
+            "maxChars": max_chars,
+            "cursor": cursor,
+        }
+        response_data = self._call("GET", endpoint, params=params)
+
+        if fetch_all:
+            # Walk the cursor chain and merge the chunks. The raw dicts are merged
+            # rather than the validated models so that the loop behaves identically
+            # whether or not response validation is enabled.
+            if not isinstance(response_data, dict):
+                raise APIError(
+                    f"Unexpected response format for get_bookmark_readable_content: {response_data}"
+                )
+            merged = dict(response_data)
+            chunks = [merged.get("content", "")]
+            next_cursor = merged.get("nextCursor")
+            while next_cursor:
+                params["cursor"] = next_cursor
+                # The format is carried by the cursor itself, so it is left as passed.
+                page = self._call("GET", endpoint, params=params)
+                if not isinstance(page, dict):
+                    raise APIError(
+                        f"Unexpected response format for get_bookmark_readable_content: {page}"
+                    )
+                chunks.append(page.get("content", ""))
+                # Keep the latest range end/total: the server may only know the true
+                # total once it has rendered further into the document.
+                if "range" in page and "range" in merged:
+                    merged["range"] = {
+                        **page["range"],
+                        "start": merged["range"].get("start", 0),
+                    }
+                merged["contentVersion"] = page.get(
+                    "contentVersion", merged.get("contentVersion")
+                )
+                next_cursor = page.get("nextCursor")
+            merged["content"] = "".join(chunks)
+            merged["nextCursor"] = None
+            merged["truncated"] = False
+            response_data = merged
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        else:
+            # Response should match BookmarkReadableContent schema
+            return datatypes.BookmarkReadableContent.model_validate(response_data)
+
     @optional_typecheck
     def summarize_a_bookmark(self, bookmark_id: str) -> Dict[str, Any]:
         """
@@ -2481,6 +2586,44 @@ class KarakeepAPI:
             logger.error(error_msg)
             raise APIError(error_msg)
 
+    @optional_typecheck
+    def get_asset_signed_url(
+        self, asset_id: str
+    ) -> Union[datatypes.SignedAssetUrl, Dict[str, Any], List[Any]]:
+        """
+        Get a temporary signed URL for downloading an asset.
+        Corresponds to GET /assets/{assetId}/signed-url.
+
+        The returned URL embeds its own signature and expiry, so it can be fetched
+        without an API key. This is the way to hand an asset to something that cannot
+        send the Authorization header (a browser tab, a media player, an <img> tag)
+        without proxying the bytes through get_a_single_asset.
+
+        Args:
+            asset_id: The ID (string) of the asset to sign.
+
+        Returns:
+            datatypes.SignedAssetUrl: The asset id, the temporary URL and its expiry.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails.
+            ValueError: If asset_id is empty.
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        if not asset_id or not asset_id.strip():
+            raise ValueError("asset_id cannot be empty")
+
+        endpoint = f"assets/{asset_id.strip()}/signed-url"
+        response_data = self._call("GET", endpoint)
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        else:
+            # Response should match SignedAssetUrl schema
+            return datatypes.SignedAssetUrl.model_validate(response_data)
+
     # --- Admin: Job Triggers ---
 
     @optional_typecheck
@@ -2488,6 +2631,7 @@ class KarakeepAPI:
         self,
         crawl_status: Literal["success", "failure", "pending", "all"] = "all",
         run_inference: bool = False,
+        modified_within_seconds: Optional[int] = None,
     ) -> Dict[str, Any]:
         """
         Trigger a recrawl of link bookmarks. Admin only.
@@ -2497,6 +2641,9 @@ class KarakeepAPI:
             crawl_status: Filter bookmarks by their current crawl status.
                           Use "failure" to retry only failed crawls. Default: "all".
             run_inference: Whether to run AI inference after crawling. Default: False.
+            modified_within_seconds: Only process bookmarks modified within this many
+                                     seconds. Must be > 0. Omit to process all matching
+                                     bookmarks (optional).
 
         Returns:
             dict: A dictionary with a "success" boolean field.
@@ -2504,16 +2651,34 @@ class KarakeepAPI:
         Raises:
             APIError: If the API request fails (e.g., 403 admin access required).
         """
-        body = {"crawlStatus": crawl_status, "runInference": run_inference}
+        body: Dict[str, Any] = {
+            "crawlStatus": crawl_status,
+            "runInference": run_inference,
+        }
+        # Omitted rather than sent as null: the spec has no null case and the
+        # absence of the key is what means "no time window".
+        if modified_within_seconds is not None:
+            body["modifiedWithinSeconds"] = modified_within_seconds
         return self._call("POST", "admin/jobs/trigger/recrawl", data=body)
 
     @optional_typecheck
-    def admin_trigger_reindex(self) -> Dict[str, Any]:
+    def admin_trigger_reindex(
+        self,
+        modified_within_seconds: Optional[int] = None,
+    ) -> Dict[str, Any]:
         """
-        Trigger a reindex of all bookmarks in the search engine. Admin only.
+        Trigger a reindex of bookmarks in the search engine. Admin only.
         Corresponds to POST /admin/jobs/trigger/reindex.
 
-        Clears the existing index and re-queues all bookmarks for indexing.
+        Without modified_within_seconds this clears the existing index and re-queues
+        every bookmark. With it, only bookmarks modified within that window are
+        re-queued and the existing index is left in place, which makes it usable as a
+        cheap catch-up job rather than a full rebuild.
+
+        Args:
+            modified_within_seconds: Only process bookmarks modified within this many
+                                     seconds. Must be > 0. Omit to reindex everything
+                                     from scratch (optional).
 
         Returns:
             dict: A dictionary with a "success" boolean field.
@@ -2521,13 +2686,22 @@ class KarakeepAPI:
         Raises:
             APIError: If the API request fails (e.g., 403 admin access required).
         """
-        return self._call("POST", "admin/jobs/trigger/reindex")
+        # The request body is optional in the spec, so nothing is sent when no window
+        # is given; that keeps the "clear and rebuild" behaviour byte-identical to
+        # what older servers expect.
+        body = (
+            None
+            if modified_within_seconds is None
+            else {"modifiedWithinSeconds": modified_within_seconds}
+        )
+        return self._call("POST", "admin/jobs/trigger/reindex", data=body)
 
     @optional_typecheck
     def admin_trigger_inference(
         self,
         type: Literal["tag", "summarize"],
         status: Literal["success", "failure", "pending", "all"] = "all",
+        modified_within_seconds: Optional[int] = None,
     ) -> Dict[str, Any]:
         """
         Trigger AI inference (tagging or summarization) on bookmarks. Admin only.
@@ -2538,6 +2712,9 @@ class KarakeepAPI:
                   "summarize" for AI summarization.
             status: Filter bookmarks by their current inference status.
                     Use "failure" to retry only failed ones. Default: "all".
+            modified_within_seconds: Only process bookmarks modified within this many
+                                     seconds. Must be > 0. Omit to process all matching
+                                     bookmarks (optional).
 
         Returns:
             dict: A dictionary with a "success" boolean field.
@@ -2545,7 +2722,10 @@ class KarakeepAPI:
         Raises:
             APIError: If the API request fails (e.g., 403 admin access required).
         """
-        body = {"type": type, "status": status}
+        body: Dict[str, Any] = {"type": type, "status": status}
+        # See admin_trigger_recrawl: the key is omitted rather than sent as null.
+        if modified_within_seconds is not None:
+            body["modifiedWithinSeconds"] = modified_within_seconds
         return self._call("POST", "admin/jobs/trigger/inference", data=body)
 
     # --- Feeds ---

karakeep_python_api/openapi_reference.json

@@ -124,6 +124,10 @@
           "id": {
             "type": "string"
           },
+          "firstCreatedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
           "createdAt": {
             "type": "string",
             "format": "date-time"
@@ -163,6 +167,16 @@
               null
             ]
           },
+          "embeddingStatus": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "success",
+              "failure",
+              "pending",
+              null
+            ]
+          },
           "note": {
             "type": "string",
             "nullable": true
@@ -277,6 +291,33 @@
                     "type": "string",
                     "nullable": true
                   },
+                  "readerViewStatus": {
+                    "type": "string",
+                    "nullable": true,
+                    "enum": [
+                      "readable",
+                      "not_readable",
+                      "uncertain",
+                      "unavailable",
+                      null
+                    ]
+                  },
+                  "readerViewScore": {
+                    "type": "integer",
+                    "nullable": true,
+                    "minimum": 0,
+                    "maximum": 100
+                  },
+                  "preferredPreview": {
+                    "type": "string",
+                    "nullable": true,
+                    "enum": [
+                      "reader_view",
+                      "screenshot",
+                      "overview",
+                      null
+                    ]
+                  },
                   "crawledAt": {
                     "type": "string",
                     "nullable": true,
@@ -441,6 +482,7 @@
           "favourited",
           "taggingStatus",
           "summarizationStatus",
+          "embeddingStatus",
           "userId",
           "tags",
           "content",
@@ -468,6 +510,77 @@
           "message"
         ]
       },
+      "BookmarkReadableContent": {
+        "type": "object",
+        "properties": {
+          "bookmarkId": {
+            "type": "string"
+          },
+          "bookmarkType": {
+            "type": "string",
+            "enum": [
+              "link",
+              "text",
+              "asset"
+            ]
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "markdown",
+              "text"
+            ]
+          },
+          "content": {
+            "type": "string"
+          },
+          "contentVersion": {
+            "type": "string",
+            "description": "A hash identifying the rendered content version used by this cursor."
+          },
+          "range": {
+            "type": "object",
+            "properties": {
+              "start": {
+                "type": "integer",
+                "description": "Zero-based start offset in Unicode characters, inclusive."
+              },
+              "end": {
+                "type": "integer",
+                "description": "Zero-based end offset in Unicode characters, exclusive."
+              },
+              "total": {
+                "type": "integer",
+                "description": "Total number of Unicode characters in the rendered content."
+              }
+            },
+            "required": [
+              "start",
+              "end",
+              "total"
+            ]
+          },
+          "nextCursor": {
+            "type": "string",
+            "nullable": true,
+            "description": "Cursor for the next chunk, or null when all content has been returned."
+          },
+          "truncated": {
+            "type": "boolean",
+            "description": "Whether more readable content remains after this chunk."
+          }
+        },
+        "required": [
+          "bookmarkId",
+          "bookmarkType",
+          "format",
+          "content",
+          "contentVersion",
+          "range",
+          "nextCursor",
+          "truncated"
+        ]
+      },
       "List": {
         "type": "object",
         "properties": {
@@ -656,6 +769,30 @@
           "fileName"
         ]
       },
+      "SignedAssetUrl": {
+        "type": "object",
+        "properties": {
+          "assetId": {
+            "type": "string",
+            "description": "The unique identifier of the asset."
+          },
+          "signedUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "The temporary URL for downloading the asset."
+          },
+          "expiresAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the signed URL expires, in ISO 8601 format."
+          }
+        },
+        "required": [
+          "assetId",
+          "signedUrl",
+          "expiresAt"
+        ]
+      },
       "Feed": {
         "type": "object",
         "properties": {
@@ -1082,7 +1219,7 @@
     "/bookmarks/search": {
       "get": {
         "operationId": "searchBookmarks",
-        "description": "Full-text search across all bookmarks. Searches bookmark titles, content, descriptions, and notes. Results default to relevance sorting.",
+        "description": "Search across all bookmarks using full-text, semantic, or hybrid ranking. Full-text search covers bookmark titles, content, descriptions, and notes. Results default to full-text relevance sorting; semantic and hybrid modes support relevance sorting only.",
         "summary": "Search bookmarks",
         "tags": [
           "Bookmarks"
@@ -1103,6 +1240,22 @@
             "name": "q",
             "in": "query"
           },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "fts",
+                "semantic",
+                "hybrid"
+              ],
+              "default": "fts",
+              "description": "Search strategy. 'fts' uses full-text search, 'semantic' uses bookmark embeddings, and 'hybrid' fuses a fixed candidate window from both. Hybrid falls back to full-text search when the query contains no free-text terms or when embedding infrastructure is unavailable. Semantic hits below a minimum similarity are dropped, so semantic search may return fewer results than requested."
+            },
+            "required": false,
+            "description": "Search strategy. 'fts' uses full-text search, 'semantic' uses bookmark embeddings, and 'hybrid' fuses a fixed candidate window from both. Hybrid falls back to full-text search when the query contains no free-text terms or when embedding infrastructure is unavailable. Semantic hits below a minimum similarity are dropped, so semantic search may return fewer results than requested.",
+            "name": "searchMode",
+            "in": "query"
+          },
           {
             "schema": {
               "type": "string",
@@ -1438,6 +1591,10 @@
                     "id": {
                       "type": "string"
                     },
+                    "firstCreatedAt": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
                     "createdAt": {
                       "type": "string",
                       "format": "date-time"
@@ -1477,6 +1634,16 @@
                         null
                       ]
                     },
+                    "embeddingStatus": {
+                      "type": "string",
+                      "nullable": true,
+                      "enum": [
+                        "success",
+                        "failure",
+                        "pending",
+                        null
+                      ]
+                    },
                     "note": {
                       "type": "string",
                       "nullable": true
@@ -1512,6 +1679,7 @@
                     "favourited",
                     "taggingStatus",
                     "summarizationStatus",
+                    "embeddingStatus",
                     "userId"
                   ]
                 }
@@ -1542,6 +1710,116 @@
         }
       }
     },
+    "/bookmarks/{bookmarkId}/content": {
+      "get": {
+        "operationId": "getBookmarkReadableContent",
+        "description": "Retrieve a bounded chunk of an agent-readable bookmark representation. Link content is rendered from extracted HTML; text and media bookmarks use their stored or extracted text. Continue reading by passing the opaque `nextCursor` from the previous response.",
+        "summary": "Get readable bookmark content",
+        "tags": [
+          "Bookmarks"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/BookmarkId"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "markdown",
+                "text"
+              ],
+              "description": "The readable representation. If omitted with a cursor, the cursor's format is used; otherwise defaults to markdown."
+            },
+            "required": false,
+            "description": "The readable representation. If omitted with a cursor, the cursor's format is used; otherwise defaults to markdown.",
+            "name": "format",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 50000,
+              "default": 12000,
+              "description": "Maximum number of Unicode characters to return. The chunk may end earlier at a paragraph or line boundary."
+            },
+            "required": false,
+            "description": "Maximum number of Unicode characters to return. The chunk may end earlier at a paragraph or line boundary.",
+            "name": "maxChars",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Opaque continuation cursor returned as `nextCursor` by a previous response."
+            },
+            "required": false,
+            "description": "Opaque continuation cursor returned as `nextCursor` by a previous response.",
+            "name": "cursor",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A bounded chunk of readable bookmark content.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BookmarkReadableContent"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request — the cursor is malformed, mismatched, or outside the content.",
+            "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"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Bookmark not found.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "The bookmark content changed after the supplied cursor was issued.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/bookmarks/{bookmarkId}/summarize": {
       "post": {
         "operationId": "summarizeBookmark",
@@ -1571,6 +1849,10 @@
                     "id": {
                       "type": "string"
                     },
+                    "firstCreatedAt": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
                     "createdAt": {
                       "type": "string",
                       "format": "date-time"
@@ -1610,6 +1892,16 @@
                         null
                       ]
                     },
+                    "embeddingStatus": {
+                      "type": "string",
+                      "nullable": true,
+                      "enum": [
+                        "success",
+                        "failure",
+                        "pending",
+                        null
+                      ]
+                    },
                     "note": {
                       "type": "string",
                       "nullable": true
@@ -1645,6 +1937,7 @@
                     "favourited",
                     "taggingStatus",
                     "summarizationStatus",
+                    "embeddingStatus",
                     "userId"
                   ]
                 }
@@ -2827,8 +3120,8 @@
           },
           {
             "schema": {
-              "type": "number",
-              "nullable": true
+              "type": "integer",
+              "minimum": 1
             },
             "required": false,
             "name": "limit",
@@ -3955,6 +4248,49 @@
         }
       }
     },
+    "/assets/{assetId}/signed-url": {
+      "get": {
+        "operationId": "getAssetSignedUrl",
+        "description": "Generate a temporary signed URL that can be used to download an asset without sending an API key.",
+        "summary": "Get a signed asset URL",
+        "tags": [
+          "Assets"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AssetId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A temporary signed URL for downloading the asset and its expiration time.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SignedAssetUrl"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized — the Bearer token is missing, invalid, or expired.",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": "Unauthorized"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/admin/users/{userId}": {
       "put": {
         "operationId": "adminUpdateUser",
@@ -4087,7 +4423,7 @@
     "/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.",
+        "description": "Trigger a recrawl of link bookmarks. You can filter by crawl status to target specific bookmarks (e.g., only failed ones) and by how recently they were modified. Optionally run AI inference after crawling. Requires admin role.",
         "summary": "Trigger recrawl of links (admin)",
         "tags": [
           "Admin"
@@ -4119,11 +4455,18 @@
                     "type": "boolean",
                     "default": false,
                     "description": "Whether to run AI inference after crawling."
+                  },
+                  "modifiedWithinSeconds": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "exclusiveMinimum": true,
+                    "description": "Only process bookmarks modified within this many seconds. Omit to process all matching bookmarks."
                   }
                 },
                 "example": {
                   "crawlStatus": "failure",
-                  "runInference": false
+                  "runInference": false,
+                  "modifiedWithinSeconds": 3600
                 }
               }
             }
@@ -4186,7 +4529,7 @@
     "/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.",
+        "description": "Trigger a reindex of bookmarks in the search engine. Without modifiedWithinSeconds, this clears the existing index and re-queues all bookmarks. When set, only bookmarks modified within that many seconds are re-queued and the existing index is preserved. Requires admin role.",
         "summary": "Trigger reindex of all bookmarks (admin)",
         "tags": [
           "Admin"
@@ -4196,6 +4539,27 @@
             "bearerAuth": []
           }
         ],
+        "requestBody": {
+          "description": "Optional time window for the reindex job.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "modifiedWithinSeconds": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "exclusiveMinimum": true,
+                    "description": "Only process bookmarks modified within this many seconds. Omit to process all matching bookmarks."
+                  }
+                },
+                "example": {
+                  "modifiedWithinSeconds": 3600
+                }
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "description": "Reindex jobs triggered successfully.",
@@ -4243,7 +4607,7 @@
     "/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.",
+        "description": "Trigger AI inference (tagging or summarization) on bookmarks. You can filter by status and by how recently bookmarks were modified. Requires admin role.",
         "summary": "Trigger AI inference on bookmarks (admin)",
         "tags": [
           "Admin"
@@ -4279,6 +4643,12 @@
                     ],
                     "default": "all",
                     "description": "Filter bookmarks by their inference status. Use 'failure' to retry only failed ones."
+                  },
+                  "modifiedWithinSeconds": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "exclusiveMinimum": true,
+                    "description": "Only process bookmarks modified within this many seconds. Omit to process all matching bookmarks."
                   }
                 },
                 "required": [
@@ -4286,7 +4656,8 @@
                 ],
                 "example": {
                   "type": "tag",
-                  "status": "failure"
+                  "status": "failure",
+                  "modifiedWithinSeconds": 3600
                 }
               }
             }

{karakeep_python_api-1.8.0.dist-info → karakeep_python_api-1.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 1.8.0
+Version: 1.9.0
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 Keywords: rss,karakeep,hoarder,data-hoarding,python,api,feeds,openapi
@@ -82,6 +82,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `get_a_single_bookmark`          |   ✅   |  ❌  |  |
 | `delete_a_bookmark`              |   ✅   |  ❌  |  |
 | `update_a_bookmark`              |   ✅   |  ✅  | Tested for title updates.                    |
+| `get_bookmark_readable_content`  |   ✅   |  ❌  | Chunk merging tested offline; live test reads a text bookmark. |
 | `summarize_a_bookmark`           |   ❌   |  ❌  |                                              |
 | `attach_tags_to_a_bookmark`      |   ✅   |  ❌  |  |
 | `detach_tags_from_a_bookmark`    |   ✅   |  ❌  |  |
@@ -110,6 +111,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `update_a_highlight`             |   ❌   |  ❌  |                                              |
 | `upload_a_new_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
 | `get_a_single_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
+| `get_asset_signed_url`           |   ✅   |  ❌  | Tested in PDF asset lifecycle test (downloads without an API key). |
 | `get_current_user_info`          |   ✅   |  ❌  | Pytest: Tested indirectly during client init. CLI not directly tested. |
 | `get_current_user_stats`         |   ✅   |  ✅  |                                              |
 | `update_user`                    |   ❌   |  ❌  |                                              |
@@ -118,6 +120,9 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `get_a_single_backup`            |   ✅   |  ❌  | Tested in backup lifecycle test.            |
 | `delete_a_backup`                |   ✅   |  ❌  | Tested in backup lifecycle test.            |
 | `download_a_backup`              |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `admin_trigger_recrawl`          |   ❌   |  ❌  | Request body construction tested offline only. |
+| `admin_trigger_reindex`          |   ❌   |  ❌  | Request body construction tested offline only. |
+| `admin_trigger_inference`        |   ❌   |  ❌  | Request body construction tested offline only. |
 
 ## Installation
 
@@ -281,4 +286,4 @@ They can be found in the [./community_scripts](https://github.com/thiswillbeyour
 
 ---
 
-*This README was generated with assistance from [aider.chat](https://aider.chat).*
+*This README was generated with assistance from [aider.chat](https://aider.chat), and later kept up to date with [Claude Code](https://claude.com/claude-code).*

karakeep_python_api-1.9.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+karakeep_python_api/__init__.py,sha256=qk3MeIIvnCNAyYzJrv8dMKVXvA4ejLU3mhB3xFzdLDY,606
+karakeep_python_api/__main__.py,sha256=weIwZtSEe8rbSd1nnVj-F__e84tBsVZTaR6DGdZFhn4,39410
+karakeep_python_api/datatypes.py,sha256=tOROux_Ehnum0hmbopFfYBZ_ZaB8M22ktPXWtnOP8ig,6936
+karakeep_python_api/karakeep_api.py,sha256=ExS7S8CjyNYF56G-TitRPlQewyx-Q5rRBkhrbm3-ukk,126407
+karakeep_python_api/openapi_reference.json,sha256=uENNNF1bHCuHzJPHQa2-DfqlEOBrLmQ0mFrVnPu9XaA,163271
+karakeep_python_api-1.9.0.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+karakeep_python_api-1.9.0.dist-info/METADATA,sha256=P9j-caj1OfqFGsnIGvwpKlRVvYrUd6_w37wACZ_v_pE,17687
+karakeep_python_api-1.9.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+karakeep_python_api-1.9.0.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
+karakeep_python_api-1.9.0.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
+karakeep_python_api-1.9.0.dist-info/RECORD,,

{karakeep_python_api-1.8.0.dist-info → karakeep_python_api-1.9.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

karakeep_python_api-1.8.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-karakeep_python_api/__init__.py,sha256=qk3MeIIvnCNAyYzJrv8dMKVXvA4ejLU3mhB3xFzdLDY,606
-karakeep_python_api/__main__.py,sha256=4337OITOcfW5Mze-aqQgb_EBR_WznScRTIIfIvHQ2co,38444
-karakeep_python_api/datatypes.py,sha256=uKhjm7uQQnh-PgsLPl0atBt_ucQBIi0PV2SWFcCNXdg,4850
-karakeep_python_api/karakeep_api.py,sha256=sdyjcz_srsp2guBoCmaXLljsmKmG1pqZVAGuZb82zQQ,117262
-karakeep_python_api/openapi_reference.json,sha256=abhe0s2_sJBL0EyD3T09JLRIOIFevSAx0K2Jucx_fyQ,150304
-karakeep_python_api-1.8.0.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
-karakeep_python_api-1.8.0.dist-info/METADATA,sha256=VFNuHpdhWePYCRn9h-gc_NBxMX58Em4Pf5EMPxgTX_Y,17053
-karakeep_python_api-1.8.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-karakeep_python_api-1.8.0.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
-karakeep_python_api-1.8.0.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
-karakeep_python_api-1.8.0.dist-info/RECORD,,