anil.recoil.org
OCaml CLI and library to the Karakeep bookmarking app
update
+150
-9
doc/assets.md
+150
-9
doc/assets.md
···
2
3
The Karakeep library provides functions for working with assets (images, documents, etc.) attached to bookmarks.
4
5
## Getting Asset URL
6
7
### `get_asset_url`
···
9
Get the asset URL for a given asset ID.
10
11
```ocaml
12
-
val get_asset_url :
13
-
string ->
14
-
string ->
15
-
string
16
```
17
18
#### Parameters
···
36
Fetch an asset from the Karakeep server as a binary string.
37
38
```ocaml
39
-
val fetch_asset :
40
-
api_key:string ->
41
-
string ->
42
-
string ->
43
-
string Lwt.t
44
```
45
46
#### Parameters
···
60
(* Do something with the binary data *)
61
Lwt.return_unit
62
```
···
2
3
The Karakeep library provides functions for working with assets (images, documents, etc.) attached to bookmarks.
4
5
+
## Types
6
+
7
+
```ocaml
8
+
type asset_id = string
9
+
10
+
type asset_type =
11
+
| Screenshot (* Screenshot of a webpage *)
12
+
| AssetScreenshot (* Screenshot of an asset *)
13
+
| BannerImage (* Banner image *)
14
+
| FullPageArchive (* Archive of a full webpage *)
15
+
| Video (* Video asset *)
16
+
| BookmarkAsset (* Generic bookmark asset *)
17
+
| PrecrawledArchive (* Pre-crawled archive *)
18
+
| Unknown (* Unknown asset type *)
19
+
20
+
type asset = {
21
+
id : asset_id;
22
+
asset_type : asset_type;
23
+
}
24
+
```
25
+
26
## Getting Asset URL
27
28
### `get_asset_url`
···
30
Get the asset URL for a given asset ID.
31
32
```ocaml
33
+
val get_asset_url : string -> asset_id -> string
34
```
35
36
#### Parameters
···
54
Fetch an asset from the Karakeep server as a binary string.
55
56
```ocaml
57
+
val fetch_asset : api_key:string -> string -> asset_id -> string Lwt.t
58
```
59
60
#### Parameters
···
74
(* Do something with the binary data *)
75
Lwt.return_unit
76
```
77
+
78
+
## Attaching Assets
79
+
80
+
### `attach_asset`
81
+
82
+
Attach an asset to a bookmark.
83
+
84
+
```ocaml
85
+
val attach_asset :
86
+
api_key:string ->
87
+
asset_id:asset_id ->
88
+
asset_type:asset_type ->
89
+
string ->
90
+
bookmark_id ->
91
+
asset Lwt.t
92
+
```
93
+
94
+
#### Parameters
95
+
96
+
- `api_key`: API key for authentication
97
+
- `asset_id`: ID of the asset to attach
98
+
- `asset_type`: Type of the asset
99
+
- `base_url`: Base URL of the Karakeep instance
100
+
- `bookmark_id`: ID of the bookmark to attach the asset to
101
+
102
+
#### Example
103
+
104
+
```ocaml
105
+
let attach_screenshot =
106
+
let api_key = "your_api_key" in
107
+
let base_url = "https://hoard.recoil.org" in
108
+
let bookmark_id = "bookmark123" in
109
+
let asset_id = "asset123" in
110
+
let* attached_asset =
111
+
Karakeep.attach_asset
112
+
~api_key
113
+
~asset_id
114
+
~asset_type:Karakeep.Screenshot
115
+
base_url
116
+
bookmark_id in
117
+
Printf.printf "Attached asset %s of type %s\n"
118
+
attached_asset.id
119
+
(match attached_asset.asset_type with
120
+
| Screenshot -> "screenshot"
121
+
| _ -> "other");
122
+
Lwt.return_unit
123
+
```
124
+
125
+
## Replacing Assets
126
+
127
+
### `replace_asset`
128
+
129
+
Replace an asset on a bookmark with a new one.
130
+
131
+
```ocaml
132
+
val replace_asset :
133
+
api_key:string ->
134
+
new_asset_id:asset_id ->
135
+
string ->
136
+
bookmark_id ->
137
+
asset_id ->
138
+
unit Lwt.t
139
+
```
140
+
141
+
#### Parameters
142
+
143
+
- `api_key`: API key for authentication
144
+
- `new_asset_id`: ID of the new asset
145
+
- `base_url`: Base URL of the Karakeep instance
146
+
- `bookmark_id`: ID of the bookmark
147
+
- `asset_id`: ID of the asset to replace
148
+
149
+
#### Example
150
+
151
+
```ocaml
152
+
let replace_screenshot =
153
+
let api_key = "your_api_key" in
154
+
let base_url = "https://hoard.recoil.org" in
155
+
let bookmark_id = "bookmark123" in
156
+
let old_asset_id = "old_asset123" in
157
+
let new_asset_id = "new_asset456" in
158
+
let* () =
159
+
Karakeep.replace_asset
160
+
~api_key
161
+
~new_asset_id
162
+
base_url
163
+
bookmark_id
164
+
old_asset_id in
165
+
Printf.printf "Replaced asset successfully\n";
166
+
Lwt.return_unit
167
+
```
168
+
169
+
## Detaching Assets
170
+
171
+
### `detach_asset`
172
+
173
+
Detach an asset from a bookmark.
174
+
175
+
```ocaml
176
+
val detach_asset :
177
+
api_key:string -> string -> bookmark_id -> asset_id -> unit Lwt.t
178
+
```
179
+
180
+
#### Parameters
181
+
182
+
- `api_key`: API key for authentication
183
+
- `base_url`: Base URL of the Karakeep instance
184
+
- `bookmark_id`: ID of the bookmark
185
+
- `asset_id`: ID of the asset to detach
186
+
187
+
#### Example
188
+
189
+
```ocaml
190
+
let detach_screenshot =
191
+
let api_key = "your_api_key" in
192
+
let base_url = "https://hoard.recoil.org" in
193
+
let bookmark_id = "bookmark123" in
194
+
let asset_id = "asset123" in
195
+
let* () =
196
+
Karakeep.detach_asset
197
+
~api_key
198
+
base_url
199
+
bookmark_id
200
+
asset_id in
201
+
Printf.printf "Detached asset successfully\n";
202
+
Lwt.return_unit
203
+
```
+251
-39
doc/bookmarks.md
+251
-39
doc/bookmarks.md
···
1
# Bookmark Operations
2
3
-
The Karakeep library provides several functions for working with bookmarks.
4
5
## Fetching Bookmarks
6
7
### `fetch_bookmarks`
8
9
-
Fetch bookmarks from a Karakeep instance with pagination support.
10
11
```ocaml
12
-
val fetch_bookmarks :
13
-
api_key:string ->
14
-
?limit:int ->
15
-
?offset:int ->
16
?cursor:string ->
17
?include_content:bool ->
18
-
?filter_tags:string list ->
19
-
string ->
20
-
bookmark_response Lwt.t
21
```
22
23
#### Parameters
24
25
- `api_key`: API key for authentication
26
- `limit`: Number of bookmarks to fetch per page (default: 50)
27
-
- `offset`: Starting index for pagination (0-based) (default: 0)
28
-
- `cursor`: Optional pagination cursor for cursor-based pagination (overrides offset when provided)
29
- `include_content`: Whether to include full content (default: true)
30
-
- `filter_tags`: Optional list of tags to filter by
31
- `base_url`: Base URL of the Karakeep instance
32
33
#### Example
···
36
let fetch_recent =
37
let api_key = "your_api_key" in
38
let base_url = "https://hoard.recoil.org" in
39
-
Karakeep.fetch_bookmarks ~api_key ~limit:10 base_url
40
```
41
42
### `fetch_all_bookmarks`
43
44
-
Fetch all bookmarks from a Karakeep instance using pagination.
45
46
```ocaml
47
-
val fetch_all_bookmarks :
48
-
api_key:string ->
49
-
?page_size:int ->
50
-
?max_pages:int ->
51
-
?filter_tags:string list ->
52
-
string ->
53
bookmark list Lwt.t
54
```
55
···
58
- `api_key`: API key for authentication
59
- `page_size`: Number of bookmarks to fetch per page (default: 50)
60
- `max_pages`: Maximum number of pages to fetch (None for all pages)
61
-
- `filter_tags`: Optional list of tags to filter by
62
- `base_url`: Base URL of the Karakeep instance
63
64
#### Example
65
66
```ocaml
67
-
let fetch_all_with_tag_ocaml =
68
let api_key = "your_api_key" in
69
let base_url = "https://hoard.recoil.org" in
70
-
Karakeep.fetch_all_bookmarks ~api_key ~filter_tags:["ocaml"] base_url
71
```
72
73
### `fetch_bookmark_details`
···
75
Fetch detailed information for a single bookmark by ID.
76
77
```ocaml
78
-
val fetch_bookmark_details :
79
-
api_key:string ->
80
-
string ->
81
-
string ->
82
-
bookmark Lwt.t
83
```
84
85
#### Parameters
···
95
let api_key = "your_api_key" in
96
let base_url = "https://hoard.recoil.org" in
97
let bookmark_id = "123456" in
98
-
Karakeep.fetch_bookmark_details ~api_key base_url bookmark_id
99
```
100
101
-
## Creating Bookmarks
102
103
### `create_bookmark`
104
105
-
Create a new bookmark in Karakeep with optional tags.
106
107
```ocaml
108
val create_bookmark :
···
110
url:string ->
111
?title:string ->
112
?note:string ->
113
-
?tags:string list ->
114
?favourited:bool ->
115
?archived:bool ->
116
string ->
117
bookmark Lwt.t
118
```
···
123
- `url`: The URL to bookmark
124
- `title`: Optional title for the bookmark
125
- `note`: Optional note to add to the bookmark
126
-
- `tags`: Optional list of tag names to add to the bookmark
127
- `favourited`: Whether the bookmark should be marked as favourite (default: false)
128
- `archived`: Whether the bookmark should be archived (default: false)
129
- `base_url`: Base URL of the Karakeep instance
130
131
#### Example
···
134
let create_new_bookmark =
135
let api_key = "your_api_key" in
136
let base_url = "https://hoard.recoil.org" in
137
-
Karakeep.create_bookmark
138
-
~api_key
139
-
~url:"https://ocaml.org"
140
-
~title:"OCaml Programming Language"
141
-
~tags:["programming"; "ocaml"; "functional"]
142
-
base_url
143
```
···
1
# Bookmark Operations
2
3
+
The Karakeep library provides comprehensive functions for working with bookmarks.
4
+
5
+
## Types
6
+
7
+
The primary types related to bookmarks are:
8
+
9
+
```ocaml
10
+
type bookmark_id = string
11
+
12
+
type bookmark_content_type =
13
+
| Link (* A URL to a webpage *)
14
+
| Text (* Plain text content *)
15
+
| Asset (* An attached asset (image, PDF, etc.) *)
16
+
| Unknown (* Unknown content type *)
17
+
18
+
type tagging_status =
19
+
| Success (* Tagging was successful *)
20
+
| Failure (* Tagging failed *)
21
+
| Pending (* Tagging is pending *)
22
+
23
+
type bookmark = {
24
+
id : bookmark_id;
25
+
created_at : Ptime.t;
26
+
modified_at : Ptime.t option;
27
+
title : string option;
28
+
archived : bool;
29
+
favourited : bool;
30
+
tagging_status : tagging_status option;
31
+
note : string option;
32
+
summary : string option;
33
+
tags : bookmark_tag list;
34
+
content : content;
35
+
assets : asset list;
36
+
}
37
+
38
+
type paginated_bookmarks = {
39
+
bookmarks : bookmark list;
40
+
next_cursor : string option;
41
+
}
42
+
```
43
44
## Fetching Bookmarks
45
46
### `fetch_bookmarks`
47
48
+
Fetch a page of bookmarks from a Karakeep instance.
49
50
```ocaml
51
+
val fetch_bookmarks :
52
+
api_key:string ->
53
+
?limit:int ->
54
?cursor:string ->
55
?include_content:bool ->
56
+
?archived:bool ->
57
+
?favourited:bool ->
58
+
string ->
59
+
paginated_bookmarks Lwt.t
60
```
61
62
#### Parameters
63
64
- `api_key`: API key for authentication
65
- `limit`: Number of bookmarks to fetch per page (default: 50)
66
+
- `cursor`: Optional pagination cursor for cursor-based pagination
67
- `include_content`: Whether to include full content (default: true)
68
+
- `archived`: Whether to filter for archived bookmarks
69
+
- `favourited`: Whether to filter for favourited bookmarks
70
- `base_url`: Base URL of the Karakeep instance
71
72
#### Example
···
75
let fetch_recent =
76
let api_key = "your_api_key" in
77
let base_url = "https://hoard.recoil.org" in
78
+
let* response = Karakeep.fetch_bookmarks ~api_key ~limit:10 base_url in
79
+
Printf.printf "Fetched %d bookmarks\n" (List.length response.bookmarks);
80
+
Lwt.return_unit
81
```
82
83
### `fetch_all_bookmarks`
84
85
+
Fetch all bookmarks from a Karakeep instance, automatically handling pagination.
86
87
```ocaml
88
+
val fetch_all_bookmarks :
89
+
api_key:string ->
90
+
?page_size:int ->
91
+
?max_pages:int ->
92
+
?archived:bool ->
93
+
?favourited:bool ->
94
+
string ->
95
bookmark list Lwt.t
96
```
97
···
100
- `api_key`: API key for authentication
101
- `page_size`: Number of bookmarks to fetch per page (default: 50)
102
- `max_pages`: Maximum number of pages to fetch (None for all pages)
103
+
- `archived`: Whether to filter for archived bookmarks
104
+
- `favourited`: Whether to filter for favourited bookmarks
105
- `base_url`: Base URL of the Karakeep instance
106
107
#### Example
108
109
```ocaml
110
+
let fetch_all_favourites =
111
let api_key = "your_api_key" in
112
let base_url = "https://hoard.recoil.org" in
113
+
let* bookmarks =
114
+
Karakeep.fetch_all_bookmarks
115
+
~api_key
116
+
~favourited:true
117
+
base_url in
118
+
Printf.printf "Fetched %d favourited bookmarks\n" (List.length bookmarks);
119
+
Lwt.return_unit
120
+
```
121
+
122
+
### `search_bookmarks`
123
+
124
+
Search for bookmarks matching a query.
125
+
126
+
```ocaml
127
+
val search_bookmarks :
128
+
api_key:string ->
129
+
query:string ->
130
+
?limit:int ->
131
+
?cursor:string ->
132
+
?include_content:bool ->
133
+
string ->
134
+
paginated_bookmarks Lwt.t
135
+
```
136
+
137
+
#### Parameters
138
+
139
+
- `api_key`: API key for authentication
140
+
- `query`: Search query
141
+
- `limit`: Number of bookmarks to fetch per page (default: 50)
142
+
- `cursor`: Optional pagination cursor
143
+
- `include_content`: Whether to include full content (default: true)
144
+
- `base_url`: Base URL of the Karakeep instance
145
+
146
+
#### Example
147
+
148
+
```ocaml
149
+
let search_for_ocaml =
150
+
let api_key = "your_api_key" in
151
+
let base_url = "https://hoard.recoil.org" in
152
+
let* results =
153
+
Karakeep.search_bookmarks
154
+
~api_key
155
+
~query:"ocaml programming"
156
+
base_url in
157
+
Printf.printf "Found %d results\n" (List.length results.bookmarks);
158
+
Lwt.return_unit
159
```
160
161
### `fetch_bookmark_details`
···
163
Fetch detailed information for a single bookmark by ID.
164
165
```ocaml
166
+
val fetch_bookmark_details :
167
+
api_key:string -> string -> bookmark_id -> bookmark Lwt.t
168
```
169
170
#### Parameters
···
180
let api_key = "your_api_key" in
181
let base_url = "https://hoard.recoil.org" in
182
let bookmark_id = "123456" in
183
+
let* bookmark = Karakeep.fetch_bookmark_details ~api_key base_url bookmark_id in
184
+
Printf.printf "Fetched bookmark: %s\n"
185
+
(match bookmark.title with Some t -> t | None -> "Untitled");
186
+
Lwt.return_unit
187
```
188
189
+
## Creating and Updating Bookmarks
190
191
### `create_bookmark`
192
193
+
Create a new bookmark in Karakeep.
194
195
```ocaml
196
val create_bookmark :
···
198
url:string ->
199
?title:string ->
200
?note:string ->
201
+
?summary:string ->
202
?favourited:bool ->
203
?archived:bool ->
204
+
?created_at:Ptime.t ->
205
+
?tags:string list ->
206
string ->
207
bookmark Lwt.t
208
```
···
213
- `url`: The URL to bookmark
214
- `title`: Optional title for the bookmark
215
- `note`: Optional note to add to the bookmark
216
+
- `summary`: Optional summary for the bookmark
217
- `favourited`: Whether the bookmark should be marked as favourite (default: false)
218
- `archived`: Whether the bookmark should be archived (default: false)
219
+
- `created_at`: Optional timestamp for when the bookmark was created
220
+
- `tags`: Optional list of tag names to add to the bookmark
221
- `base_url`: Base URL of the Karakeep instance
222
223
#### Example
···
226
let create_new_bookmark =
227
let api_key = "your_api_key" in
228
let base_url = "https://hoard.recoil.org" in
229
+
let* bookmark =
230
+
Karakeep.create_bookmark
231
+
~api_key
232
+
~url:"https://ocaml.org"
233
+
~title:"OCaml Programming Language"
234
+
~tags:["programming"; "ocaml"; "functional"]
235
+
base_url in
236
+
Printf.printf "Created bookmark with ID: %s\n" bookmark.id;
237
+
Lwt.return_unit
238
+
```
239
+
240
+
### `update_bookmark`
241
+
242
+
Update an existing bookmark.
243
+
244
+
```ocaml
245
+
val update_bookmark :
246
+
api_key:string ->
247
+
?title:string ->
248
+
?note:string ->
249
+
?summary:string ->
250
+
?favourited:bool ->
251
+
?archived:bool ->
252
+
?url:string ->
253
+
?description:string ->
254
+
?author:string ->
255
+
?publisher:string ->
256
+
?date_published:Ptime.t ->
257
+
?date_modified:Ptime.t ->
258
+
?text:string ->
259
+
?asset_content:string ->
260
+
string ->
261
+
bookmark_id ->
262
+
bookmark Lwt.t
263
+
```
264
+
265
+
#### Parameters
266
+
267
+
- `api_key`: API key for authentication
268
+
- `title`: Optional new title for the bookmark
269
+
- `note`: Optional new note for the bookmark
270
+
- `summary`: Optional new summary for the bookmark
271
+
- `favourited`: Whether the bookmark should be marked as favourite
272
+
- `archived`: Whether the bookmark should be archived
273
+
- `url`: Optional new URL for the bookmark
274
+
- `description`: Optional new description for the bookmark
275
+
- `author`: Optional new author for the bookmark
276
+
- `publisher`: Optional new publisher for the bookmark
277
+
- `date_published`: Optional new publication date for the bookmark
278
+
- `date_modified`: Optional new modification date for the bookmark
279
+
- `text`: Optional new text content for the bookmark
280
+
- `asset_content`: Optional new asset content for the bookmark
281
+
- `base_url`: Base URL of the Karakeep instance
282
+
- `bookmark_id`: ID of the bookmark to update
283
+
284
+
#### Example
285
+
286
+
```ocaml
287
+
let update_bookmark_title =
288
+
let api_key = "your_api_key" in
289
+
let base_url = "https://hoard.recoil.org" in
290
+
let bookmark_id = "123456" in
291
+
let* updated =
292
+
Karakeep.update_bookmark
293
+
~api_key
294
+
~title:"Updated OCaml Programming Language"
295
+
~favourited:true
296
+
base_url
297
+
bookmark_id in
298
+
Printf.printf "Updated bookmark title to: %s\n"
299
+
(match updated.title with Some t -> t | None -> "Untitled");
300
+
Lwt.return_unit
301
```
302
+
303
+
### `delete_bookmark`
304
+
305
+
Delete a bookmark by its ID.
306
+
307
+
```ocaml
308
+
val delete_bookmark : api_key:string -> string -> bookmark_id -> unit Lwt.t
309
+
```
310
+
311
+
#### Parameters
312
+
313
+
- `api_key`: API key for authentication
314
+
- `base_url`: Base URL of the Karakeep instance
315
+
- `bookmark_id`: ID of the bookmark to delete
316
+
317
+
#### Example
318
+
319
+
```ocaml
320
+
let delete_bookmark =
321
+
let api_key = "your_api_key" in
322
+
let base_url = "https://hoard.recoil.org" in
323
+
let bookmark_id = "123456" in
324
+
let* () = Karakeep.delete_bookmark ~api_key base_url bookmark_id in
325
+
Printf.printf "Deleted bookmark successfully\n";
326
+
Lwt.return_unit
327
+
```
328
+
329
+
### `summarize_bookmark`
330
+
331
+
Generate a summary for a bookmark using AI.
332
+
333
+
```ocaml
334
+
val summarize_bookmark :
335
+
api_key:string -> string -> bookmark_id -> bookmark Lwt.t
336
+
```
337
+
338
+
#### Parameters
339
+
340
+
- `api_key`: API key for authentication
341
+
- `base_url`: Base URL of the Karakeep instance
342
+
- `bookmark_id`: ID of the bookmark to summarize
343
+
344
+
#### Example
345
+
346
+
```ocaml
347
+
let summarize_bookmark =
348
+
let api_key = "your_api_key" in
349
+
let base_url = "https://hoard.recoil.org" in
350
+
let bookmark_id = "123456" in
351
+
let* bookmark = Karakeep.summarize_bookmark ~api_key base_url bookmark_id in
352
+
Printf.printf "Generated summary: %s\n"
353
+
(match bookmark.summary with Some s -> s | None -> "No summary generated");
354
+
Lwt.return_unit
355
+
```
+179
-24
doc/types.md
+179
-24
doc/types.md
···
1
# Karakeep Types
2
3
-
This document describes the main types used in the Karakeep OCaml client.
4
5
-
## Bookmark
6
7
-
Represents a single bookmark in Karakeep.
8
9
```ocaml
10
type bookmark = {
11
-
id: string;
12
-
title: string option;
13
-
url: string;
14
-
note: string option;
15
-
created_at: Ptime.t;
16
-
updated_at: Ptime.t option;
17
-
favourited: bool;
18
-
archived: bool;
19
-
tags: string list;
20
-
tagging_status: string option;
21
-
summary: string option;
22
-
content: (string * string) list;
23
-
assets: (string * string) list;
24
}
25
```
26
27
-
## Bookmark Response
28
-
29
-
Represents a paginated response from the Karakeep API containing bookmarks.
30
31
```ocaml
32
-
type bookmark_response = {
33
-
total: int;
34
-
data: bookmark list;
35
-
next_cursor: string option;
36
}
37
```
38
39
-
See [Bookmarks](bookmarks.md) for more information on how to use these types.
···
1
# Karakeep Types
2
3
+
This document describes the main types used in the Karakeep OCL client.
4
5
+
## Core Types
6
7
+
### Identifiers
8
9
```ocaml
10
+
type asset_id = string
11
+
type bookmark_id = string
12
+
type list_id = string
13
+
type tag_id = string
14
+
type highlight_id = string
15
+
```
16
+
17
+
These types are used to represent the unique identifiers for various resources in the Karakeep API.
18
+
19
+
### Enumerations
20
+
21
+
```ocaml
22
+
type bookmark_content_type =
23
+
| Link (* A URL to a webpage *)
24
+
| Text (* Plain text content *)
25
+
| Asset (* An attached asset (image, PDF, etc.) *)
26
+
| Unknown (* Unknown content type *)
27
+
28
+
type asset_type =
29
+
| Screenshot (* Screenshot of a webpage *)
30
+
| AssetScreenshot (* Screenshot of an asset *)
31
+
| BannerImage (* Banner image *)
32
+
| FullPageArchive (* Archive of a full webpage *)
33
+
| Video (* Video asset *)
34
+
| BookmarkAsset (* Generic bookmark asset *)
35
+
| PrecrawledArchive (* Pre-crawled archive *)
36
+
| Unknown (* Unknown asset type *)
37
+
38
+
type tagging_status =
39
+
| Success (* Tagging was successful *)
40
+
| Failure (* Tagging failed *)
41
+
| Pending (* Tagging is pending *)
42
+
43
+
type list_type =
44
+
| Manual (* List is manually managed *)
45
+
| Smart (* List is dynamically generated based on a query *)
46
+
47
+
type highlight_color =
48
+
| Yellow (* Yellow highlight *)
49
+
| Red (* Red highlight *)
50
+
| Green (* Green highlight *)
51
+
| Blue (* Blue highlight *)
52
+
53
+
type tag_attachment_type =
54
+
| AI (* Tag was attached by AI *)
55
+
| Human (* Tag was attached by a human *)
56
+
```
57
+
58
+
### Content Types
59
+
60
+
```ocaml
61
+
type link_content = {
62
+
url : string;
63
+
title : string option;
64
+
description : string option;
65
+
image_url : string option;
66
+
image_asset_id : asset_id option;
67
+
screenshot_asset_id : asset_id option;
68
+
full_page_archive_asset_id : asset_id option;
69
+
precrawled_archive_asset_id : asset_id option;
70
+
video_asset_id : asset_id option;
71
+
favicon : string option;
72
+
html_content : string option;
73
+
crawled_at : Ptime.t option;
74
+
author : string option;
75
+
publisher : string option;
76
+
date_published : Ptime.t option;
77
+
date_modified : Ptime.t option;
78
+
}
79
+
80
+
type text_content = {
81
+
text : string;
82
+
source_url : string option;
83
+
}
84
+
85
+
type asset_content = {
86
+
asset_type : [ `Image | `PDF ];
87
+
asset_id : asset_id;
88
+
file_name : string option;
89
+
source_url : string option;
90
+
size : int option;
91
+
content : string option;
92
+
}
93
+
94
+
type content =
95
+
| Link of link_content
96
+
| Text of text_content
97
+
| Asset of asset_content
98
+
| Unknown
99
+
```
100
+
101
+
### Resource Types
102
+
103
+
```ocaml
104
+
type asset = {
105
+
id : asset_id;
106
+
asset_type : asset_type;
107
+
}
108
+
109
+
type bookmark_tag = {
110
+
id : tag_id;
111
+
name : string;
112
+
attached_by : tag_attachment_type;
113
+
}
114
+
115
type bookmark = {
116
+
id : bookmark_id;
117
+
created_at : Ptime.t;
118
+
modified_at : Ptime.t option;
119
+
title : string option;
120
+
archived : bool;
121
+
favourited : bool;
122
+
tagging_status : tagging_status option;
123
+
note : string option;
124
+
summary : string option;
125
+
tags : bookmark_tag list;
126
+
content : content;
127
+
assets : asset list;
128
+
}
129
+
130
+
type paginated_bookmarks = {
131
+
bookmarks : bookmark list;
132
+
next_cursor : string option;
133
+
}
134
+
135
+
type list = {
136
+
id : list_id;
137
+
name : string;
138
+
description : string option;
139
+
icon : string;
140
+
parent_id : list_id option;
141
+
list_type : list_type;
142
+
query : string option;
143
+
}
144
+
145
+
type tag = {
146
+
id : tag_id;
147
+
name : string;
148
+
num_bookmarks : int;
149
+
num_bookmarks_by_attached_type : (tag_attachment_type * int) list;
150
+
}
151
+
152
+
type highlight = {
153
+
bookmark_id : bookmark_id;
154
+
start_offset : int;
155
+
end_offset : int;
156
+
color : highlight_color;
157
+
text : string option;
158
+
note : string option;
159
+
id : highlight_id;
160
+
user_id : string;
161
+
created_at : Ptime.t;
162
+
}
163
+
164
+
type paginated_highlights = {
165
+
highlights : highlight list;
166
+
next_cursor : string option;
167
}
168
```
169
170
+
### User Information
171
172
```ocaml
173
+
type user_info = {
174
+
id : string;
175
+
name : string option;
176
+
email : string option;
177
+
}
178
+
179
+
type user_stats = {
180
+
num_bookmarks : int;
181
+
num_favorites : int;
182
+
num_archived : int;
183
+
num_tags : int;
184
+
num_lists : int;
185
+
num_highlights : int;
186
+
}
187
+
188
+
type error_response = {
189
+
code : string;
190
+
message : string;
191
}
192
```
193
194
+
For more information about how to use these types with the API functions, see the [API documentation](index.md).
+739
-84
lib/karakeep.mli
+739
-84
lib/karakeep.mli
···
42
All operations require an API key that can be obtained from your Karakeep
43
instance. *)
44
45
type bookmark = {
46
-
id : string; (** Unique identifier for the bookmark *)
47
title : string option; (** Optional title of the bookmarked page *)
48
-
url : string; (** URL of the bookmarked page *)
49
-
note : string option; (** Optional user note associated with the bookmark *)
50
-
created_at : Ptime.t; (** Timestamp when the bookmark was created *)
51
-
updated_at : Ptime.t option; (** Optional timestamp of the last update *)
52
favourited : bool; (** Whether the bookmark is marked as a favorite *)
53
-
archived : bool; (** Whether the bookmark is archived *)
54
-
tags : string list; (** List of tags associated with the bookmark *)
55
-
tagging_status : string option; (** Optional status of automatic tagging *)
56
summary : string option; (** Optional AI-generated summary *)
57
-
content : (string * string) list;
58
-
(** List of key-value pairs with content metadata *)
59
-
assets : (string * string) list;
60
-
(** List of (id, type) pairs for associated assets *)
61
}
62
-
(** Type representing a Karakeep bookmark. Each bookmark contains metadata and
63
-
content information from the Karakeep service. *)
64
65
-
type bookmark_response = {
66
-
total : int; (** Total number of bookmarks available *)
67
-
data : bookmark list; (** List of bookmarks in the current page *)
68
next_cursor : string option; (** Optional cursor for fetching the next page *)
69
}
70
-
(** Type for Karakeep API response containing bookmarks. This represents a page
71
-
of results from the Karakeep API. *)
72
73
-
val parse_bookmark : Ezjsonm.value -> bookmark
74
-
(** [parse_bookmark json] parses a single bookmark from Karakeep JSON.
75
76
-
This is an internal function used to parse bookmark data from the Karakeep
77
-
API. Most users will not need to call this directly.
78
79
-
@param json Ezjsonm value representing a bookmark
80
-
@return The parsed bookmark record *)
81
82
-
val parse_bookmark_response : Ezjsonm.value -> bookmark_response
83
-
(** [parse_bookmark_response json] parses a Karakeep API response containing
84
-
bookmarks.
85
86
-
This is an internal function used to parse response data from the Karakeep
87
-
API. Most users will not need to call this directly.
88
89
-
@param json Ezjsonm value representing a bookmark response
90
-
@return The parsed bookmark_response record *)
91
92
val fetch_bookmarks :
93
api_key:string ->
94
?limit:int ->
95
-
?offset:int ->
96
?cursor:string ->
97
?include_content:bool ->
98
-
?filter_tags:string list ->
99
string ->
100
-
bookmark_response Lwt.t
101
-
(** [fetch_bookmarks ~api_key ?limit ?offset ?cursor ?include_content
102
-
?filter_tags base_url] fetches a single page of bookmarks from a Karakeep
103
-
instance.
104
-
105
-
This function provides fine-grained control over pagination with offset or
106
-
cursor-based pagination. It returns a {!bookmark_response} that includes
107
-
pagination information like total count and next cursor.
108
109
-
Use this function when you need to:
110
-
- Control pagination manually
111
-
- Process results one page at a time
112
-
- Access pagination metadata
113
114
@param api_key API key for authentication
115
@param limit Number of bookmarks to fetch per page (default: 50)
116
-
@param offset Starting index for pagination (0-based) (default: 0)
117
-
@param cursor
118
-
Optional pagination cursor for cursor-based pagination (overrides offset
119
-
when provided)
120
@param include_content Whether to include full content (default: true)
121
-
@param filter_tags Optional list of tags to filter by
122
@param base_url Base URL of the Karakeep instance
123
@return
124
A Lwt promise with the bookmark response containing a single page of
···
128
api_key:string ->
129
?page_size:int ->
130
?max_pages:int ->
131
-
?filter_tags:string list ->
132
string ->
133
bookmark list Lwt.t
134
-
(** [fetch_all_bookmarks ~api_key ?page_size ?max_pages ?filter_tags base_url]
135
-
fetches all bookmarks from a Karakeep instance, automatically handling
136
-
pagination.
137
138
This function handles pagination internally and returns a flattened list of
139
all bookmarks. It will continue making API requests until all pages have
···
147
@param api_key API key for authentication
148
@param page_size Number of bookmarks to fetch per page (default: 50)
149
@param max_pages Maximum number of pages to fetch (None for all pages)
150
-
@param filter_tags Optional list of tags to filter by
151
@param base_url Base URL of the Karakeep instance
152
@return A Lwt promise with all bookmarks combined into a single list *)
153
154
val fetch_bookmark_details :
155
-
api_key:string -> string -> string -> bookmark Lwt.t
156
(** [fetch_bookmark_details ~api_key base_url bookmark_id] fetches detailed
157
information for a single bookmark by ID.
158
···
165
@param bookmark_id ID of the bookmark to fetch
166
@return A Lwt promise with the complete bookmark details *)
167
168
-
val fetch_asset : api_key:string -> string -> string -> string Lwt.t
169
-
(** [fetch_asset ~api_key base_url asset_id] fetches an asset from the Karakeep
170
-
server as a binary string.
171
-
172
-
Assets can include images, PDFs, or other files attached to bookmarks. This
173
-
function retrieves the binary content of an asset by its ID.
174
-
175
-
@param api_key API key for authentication
176
-
@param base_url Base URL of the Karakeep instance
177
-
@param asset_id ID of the asset to fetch
178
-
@return A Lwt promise with the binary asset data *)
179
-
180
-
val get_asset_url : string -> string -> string
181
-
(** [get_asset_url base_url asset_id] returns the full URL for a given asset ID.
182
-
183
-
This is a pure function that constructs the URL for an asset without making
184
-
any API calls. The returned URL can be used to access the asset directly,
185
-
assuming proper authentication.
186
-
187
-
@param base_url Base URL of the Karakeep instance
188
-
@param asset_id ID of the asset
189
-
@return The full URL to the asset *)
190
-
191
val create_bookmark :
192
api_key:string ->
193
url:string ->
194
?title:string ->
195
?note:string ->
196
-
?tags:string list ->
197
?favourited:bool ->
198
?archived:bool ->
199
string ->
200
bookmark Lwt.t
201
-
(** [create_bookmark ~api_key ~url ?title ?note ?tags ?favourited ?archived
202
-
base_url] creates a new bookmark in Karakeep.
203
204
This function adds a new bookmark to the Karakeep instance for the given
205
URL. It supports setting various bookmark attributes and adding tags.
···
217
@param url The URL to bookmark
218
@param title Optional title for the bookmark
219
@param note Optional note to add to the bookmark
220
-
@param tags Optional list of tag names to add to the bookmark
221
@param favourited
222
Whether the bookmark should be marked as favourite (default: false)
223
@param archived Whether the bookmark should be archived (default: false)
224
@param base_url Base URL of the Karakeep instance
225
@return A Lwt promise with the created bookmark *)
···
42
All operations require an API key that can be obtained from your Karakeep
43
instance. *)
44
45
+
(** {1 Core Types} *)
46
+
47
+
(** Asset identifier type *)
48
+
type asset_id = string
49
+
50
+
(** Bookmark identifier type *)
51
+
type bookmark_id = string
52
+
53
+
(** List identifier type *)
54
+
type list_id = string
55
+
56
+
(** Tag identifier type *)
57
+
type tag_id = string
58
+
59
+
(** Highlight identifier type *)
60
+
type highlight_id = string
61
+
62
+
(** Type of content a bookmark can have *)
63
+
type bookmark_content_type =
64
+
| Link (** A URL to a webpage *)
65
+
| Text (** Plain text content *)
66
+
| Asset (** An attached asset (image, PDF, etc.) *)
67
+
| Unknown (** Unknown content type *)
68
+
69
+
(** Type of asset *)
70
+
type asset_type =
71
+
| Screenshot (** Screenshot of a webpage *)
72
+
| AssetScreenshot (** Screenshot of an asset *)
73
+
| BannerImage (** Banner image *)
74
+
| FullPageArchive (** Archive of a full webpage *)
75
+
| Video (** Video asset *)
76
+
| BookmarkAsset (** Generic bookmark asset *)
77
+
| PrecrawledArchive (** Pre-crawled archive *)
78
+
| Unknown (** Unknown asset type *)
79
+
80
+
(** Type of tagging status *)
81
+
type tagging_status =
82
+
| Success (** Tagging was successful *)
83
+
| Failure (** Tagging failed *)
84
+
| Pending (** Tagging is pending *)
85
+
86
+
(** Type of bookmark list *)
87
+
type list_type =
88
+
| Manual (** List is manually managed *)
89
+
| Smart (** List is dynamically generated based on a query *)
90
+
91
+
(** Highlight color *)
92
+
type highlight_color =
93
+
| Yellow (** Yellow highlight *)
94
+
| Red (** Red highlight *)
95
+
| Green (** Green highlight *)
96
+
| Blue (** Blue highlight *)
97
+
98
+
(** Type of how a tag was attached *)
99
+
type tag_attachment_type =
100
+
| AI (** Tag was attached by AI *)
101
+
| Human (** Tag was attached by a human *)
102
+
103
+
(** Link content for a bookmark *)
104
+
type link_content = {
105
+
url : string; (** The URL of the bookmarked page *)
106
+
title : string option; (** Title from the link *)
107
+
description : string option; (** Description from the link *)
108
+
image_url : string option; (** URL of an image from the link *)
109
+
image_asset_id : asset_id option; (** ID of an image asset *)
110
+
screenshot_asset_id : asset_id option; (** ID of a screenshot asset *)
111
+
full_page_archive_asset_id : asset_id option;
112
+
(** ID of a full page archive asset *)
113
+
precrawled_archive_asset_id : asset_id option;
114
+
(** ID of a pre-crawled archive asset *)
115
+
video_asset_id : asset_id option; (** ID of a video asset *)
116
+
favicon : string option; (** URL of the favicon *)
117
+
html_content : string option; (** HTML content of the page *)
118
+
crawled_at : Ptime.t option; (** When the page was crawled *)
119
+
author : string option; (** Author of the content *)
120
+
publisher : string option; (** Publisher of the content *)
121
+
date_published : Ptime.t option; (** When the content was published *)
122
+
date_modified : Ptime.t option; (** When the content was last modified *)
123
+
}
124
+
125
+
(** Text content for a bookmark *)
126
+
type text_content = {
127
+
text : string; (** The text content *)
128
+
source_url : string option; (** Optional source URL for the text *)
129
+
}
130
+
131
+
(** Asset content for a bookmark *)
132
+
type asset_content = {
133
+
asset_type : [ `Image | `PDF ]; (** Type of the asset *)
134
+
asset_id : asset_id; (** ID of the asset *)
135
+
file_name : string option; (** Name of the file *)
136
+
source_url : string option; (** Source URL for the asset *)
137
+
size : int option; (** Size of the asset in bytes *)
138
+
content : string option; (** Extracted content from the asset *)
139
+
}
140
+
141
+
(** Content of a bookmark *)
142
+
type content =
143
+
| Link of link_content (** Link-type content *)
144
+
| Text of text_content (** Text-type content *)
145
+
| Asset of asset_content (** Asset-type content *)
146
+
| Unknown (** Unknown content type *)
147
+
148
+
(** Asset attached to a bookmark *)
149
+
type asset = {
150
+
id : asset_id; (** ID of the asset *)
151
+
asset_type : asset_type; (** Type of the asset *)
152
+
}
153
+
154
+
(** Tag with attachment information *)
155
+
type bookmark_tag = {
156
+
id : tag_id; (** ID of the tag *)
157
+
name : string; (** Name of the tag *)
158
+
attached_by : tag_attachment_type; (** How the tag was attached *)
159
+
}
160
+
161
+
(** A bookmark from the Karakeep service *)
162
type bookmark = {
163
+
id : bookmark_id; (** Unique identifier for the bookmark *)
164
+
created_at : Ptime.t; (** Timestamp when the bookmark was created *)
165
+
modified_at : Ptime.t option; (** Optional timestamp of the last update *)
166
title : string option; (** Optional title of the bookmarked page *)
167
+
archived : bool; (** Whether the bookmark is archived *)
168
favourited : bool; (** Whether the bookmark is marked as a favorite *)
169
+
tagging_status : tagging_status option; (** Status of automatic tagging *)
170
+
note : string option; (** Optional user note associated with the bookmark *)
171
summary : string option; (** Optional AI-generated summary *)
172
+
tags : bookmark_tag list; (** Tags associated with the bookmark *)
173
+
content : content; (** Content of the bookmark *)
174
+
assets : asset list; (** Assets attached to the bookmark *)
175
}
176
177
+
(** Paginated response of bookmarks *)
178
+
type paginated_bookmarks = {
179
+
bookmarks : bookmark list; (** List of bookmarks in the current page *)
180
next_cursor : string option; (** Optional cursor for fetching the next page *)
181
}
182
183
+
(** List in Karakeep *)
184
+
type _list = {
185
+
id : list_id; (** ID of the list *)
186
+
name : string; (** Name of the list *)
187
+
description : string option; (** Optional description of the list *)
188
+
icon : string; (** Icon for the list *)
189
+
parent_id : list_id option; (** Optional parent list ID *)
190
+
list_type : list_type; (** Type of the list *)
191
+
query : string option; (** Optional query for smart lists *)
192
+
}
193
194
+
(** Tag in Karakeep *)
195
+
type tag = {
196
+
id : tag_id; (** ID of the tag *)
197
+
name : string; (** Name of the tag *)
198
+
num_bookmarks : int; (** Number of bookmarks with this tag *)
199
+
num_bookmarks_by_attached_type : (tag_attachment_type * int) list; (** Number of bookmarks by attachment type *)
200
+
}
201
202
+
(** Highlight in Karakeep *)
203
+
type highlight = {
204
+
bookmark_id : bookmark_id; (** ID of the bookmark *)
205
+
start_offset : int; (** Start position of the highlight *)
206
+
end_offset : int; (** End position of the highlight *)
207
+
color : highlight_color; (** Color of the highlight *)
208
+
text : string option; (** Text of the highlight *)
209
+
note : string option; (** Note for the highlight *)
210
+
id : highlight_id; (** ID of the highlight *)
211
+
user_id : string; (** ID of the user who created the highlight *)
212
+
created_at : Ptime.t; (** When the highlight was created *)
213
+
}
214
215
+
(** Paginated response of highlights *)
216
+
type paginated_highlights = {
217
+
highlights : highlight list; (** List of highlights in the current page *)
218
+
next_cursor : string option; (** Optional cursor for fetching the next page *)
219
+
}
220
221
+
(** User information *)
222
+
type user_info = {
223
+
id : string; (** ID of the user *)
224
+
name : string option; (** Name of the user *)
225
+
email : string option; (** Email of the user *)
226
+
}
227
228
+
(** User statistics *)
229
+
type user_stats = {
230
+
num_bookmarks : int; (** Number of bookmarks *)
231
+
num_favorites : int; (** Number of favorite bookmarks *)
232
+
num_archived : int; (** Number of archived bookmarks *)
233
+
num_tags : int; (** Number of tags *)
234
+
num_lists : int; (** Number of lists *)
235
+
num_highlights : int; (** Number of highlights *)
236
+
}
237
+
238
+
(** Error response from the API *)
239
+
type error_response = {
240
+
code : string; (** Error code *)
241
+
message : string; (** Error message *)
242
+
}
243
+
244
+
(** {1 Bookmark Operations} *)
245
246
val fetch_bookmarks :
247
api_key:string ->
248
?limit:int ->
249
?cursor:string ->
250
?include_content:bool ->
251
+
?archived:bool ->
252
+
?favourited:bool ->
253
string ->
254
+
paginated_bookmarks Lwt.t
255
+
(** [fetch_bookmarks ~api_key ?limit ?cursor ?include_content ?archived
256
+
?favourited base_url] fetches a page of bookmarks from a Karakeep instance.
257
258
+
This function provides fine-grained control over pagination with
259
+
cursor-based pagination. It returns a {!paginated_bookmarks} that includes
260
+
pagination information like the next cursor.
261
262
@param api_key API key for authentication
263
@param limit Number of bookmarks to fetch per page (default: 50)
264
+
@param cursor Optional pagination cursor for cursor-based pagination
265
@param include_content Whether to include full content (default: true)
266
+
@param archived Whether to filter for archived bookmarks
267
+
@param favourited Whether to filter for favourited bookmarks
268
@param base_url Base URL of the Karakeep instance
269
@return
270
A Lwt promise with the bookmark response containing a single page of
···
274
api_key:string ->
275
?page_size:int ->
276
?max_pages:int ->
277
+
?archived:bool ->
278
+
?favourited:bool ->
279
string ->
280
bookmark list Lwt.t
281
+
(** [fetch_all_bookmarks ~api_key ?page_size ?max_pages ?archived ?favourited
282
+
base_url] fetches all bookmarks from a Karakeep instance, automatically
283
+
handling pagination.
284
285
This function handles pagination internally and returns a flattened list of
286
all bookmarks. It will continue making API requests until all pages have
···
294
@param api_key API key for authentication
295
@param page_size Number of bookmarks to fetch per page (default: 50)
296
@param max_pages Maximum number of pages to fetch (None for all pages)
297
+
@param archived Whether to filter for archived bookmarks
298
+
@param favourited Whether to filter for favourited bookmarks
299
@param base_url Base URL of the Karakeep instance
300
@return A Lwt promise with all bookmarks combined into a single list *)
301
302
+
val search_bookmarks :
303
+
api_key:string ->
304
+
query:string ->
305
+
?limit:int ->
306
+
?cursor:string ->
307
+
?include_content:bool ->
308
+
string ->
309
+
paginated_bookmarks Lwt.t
310
+
(** [search_bookmarks ~api_key ~query ?limit ?cursor ?include_content base_url]
311
+
searches for bookmarks matching a query.
312
+
313
+
@param api_key API key for authentication
314
+
@param query Search query
315
+
@param limit Number of bookmarks to fetch per page (default: 50)
316
+
@param cursor Optional pagination cursor
317
+
@param include_content Whether to include full content (default: true)
318
+
@param base_url Base URL of the Karakeep instance
319
+
@return
320
+
A Lwt promise with the bookmark response containing search results *)
321
+
322
val fetch_bookmark_details :
323
+
api_key:string -> string -> bookmark_id -> bookmark Lwt.t
324
(** [fetch_bookmark_details ~api_key base_url bookmark_id] fetches detailed
325
information for a single bookmark by ID.
326
···
333
@param bookmark_id ID of the bookmark to fetch
334
@return A Lwt promise with the complete bookmark details *)
335
336
val create_bookmark :
337
api_key:string ->
338
url:string ->
339
?title:string ->
340
?note:string ->
341
+
?summary:string ->
342
?favourited:bool ->
343
?archived:bool ->
344
+
?created_at:Ptime.t ->
345
+
?tags:string list ->
346
string ->
347
bookmark Lwt.t
348
+
(** [create_bookmark ~api_key ~url ?title ?note ?summary ?favourited ?archived
349
+
?created_at ?tags base_url] creates a new bookmark in Karakeep.
350
351
This function adds a new bookmark to the Karakeep instance for the given
352
URL. It supports setting various bookmark attributes and adding tags.
···
364
@param url The URL to bookmark
365
@param title Optional title for the bookmark
366
@param note Optional note to add to the bookmark
367
+
@param summary Optional summary for the bookmark
368
@param favourited
369
Whether the bookmark should be marked as favourite (default: false)
370
@param archived Whether the bookmark should be archived (default: false)
371
+
@param created_at Optional timestamp for when the bookmark was created
372
+
@param tags Optional list of tag names to add to the bookmark
373
@param base_url Base URL of the Karakeep instance
374
@return A Lwt promise with the created bookmark *)
375
+
376
+
val update_bookmark :
377
+
api_key:string ->
378
+
?title:string ->
379
+
?note:string ->
380
+
?summary:string ->
381
+
?favourited:bool ->
382
+
?archived:bool ->
383
+
?url:string ->
384
+
?description:string ->
385
+
?author:string ->
386
+
?publisher:string ->
387
+
?date_published:Ptime.t ->
388
+
?date_modified:Ptime.t ->
389
+
?text:string ->
390
+
?asset_content:string ->
391
+
string ->
392
+
bookmark_id ->
393
+
bookmark Lwt.t
394
+
(** [update_bookmark ~api_key ?title ?note ?summary ?favourited ?archived ?url
395
+
?description ?author ?publisher ?date_published ?date_modified ?text
396
+
?asset_content base_url bookmark_id] updates a bookmark by its ID.
397
+
398
+
This function updates various attributes of an existing bookmark. Only the
399
+
fields provided will be updated.
400
+
401
+
@param api_key API key for authentication
402
+
@param title Optional new title for the bookmark
403
+
@param note Optional new note for the bookmark
404
+
@param summary Optional new summary for the bookmark
405
+
@param favourited Whether the bookmark should be marked as favourite
406
+
@param archived Whether the bookmark should be archived
407
+
@param url Optional new URL for the bookmark
408
+
@param description Optional new description for the bookmark
409
+
@param author Optional new author for the bookmark
410
+
@param publisher Optional new publisher for the bookmark
411
+
@param date_published Optional new publication date for the bookmark
412
+
@param date_modified Optional new modification date for the bookmark
413
+
@param text Optional new text content for the bookmark
414
+
@param asset_content Optional new asset content for the bookmark
415
+
@param base_url Base URL of the Karakeep instance
416
+
@param bookmark_id ID of the bookmark to update
417
+
@return A Lwt promise with the updated bookmark details *)
418
+
419
+
val delete_bookmark : api_key:string -> string -> bookmark_id -> unit Lwt.t
420
+
(** [delete_bookmark ~api_key base_url bookmark_id] deletes a bookmark by its
421
+
ID.
422
+
423
+
This function permanently removes a bookmark from the Karakeep instance.
424
+
425
+
@param api_key API key for authentication
426
+
@param base_url Base URL of the Karakeep instance
427
+
@param bookmark_id ID of the bookmark to delete
428
+
@return A Lwt promise that completes when the bookmark is deleted *)
429
+
430
+
val summarize_bookmark :
431
+
api_key:string -> string -> bookmark_id -> bookmark Lwt.t
432
+
(** [summarize_bookmark ~api_key base_url bookmark_id] generates a summary for a
433
+
bookmark.
434
+
435
+
This function uses AI to generate a summary of the bookmark's content. The
436
+
summary is added to the bookmark.
437
+
438
+
@param api_key API key for authentication
439
+
@param base_url Base URL of the Karakeep instance
440
+
@param bookmark_id ID of the bookmark to summarize
441
+
@return A Lwt promise with the updated bookmark including the summary *)
442
+
443
+
(** {1 Tag Operations} *)
444
+
445
+
val attach_tags :
446
+
api_key:string ->
447
+
tag_refs:[ `TagId of tag_id | `TagName of string ] list ->
448
+
string ->
449
+
bookmark_id ->
450
+
tag_id list Lwt.t
451
+
(** [attach_tags ~api_key ~tag_refs base_url bookmark_id] attaches tags to a
452
+
bookmark.
453
+
454
+
This function adds one or more tags to a bookmark. Tags can be referred to
455
+
either by their ID or by their name. If a tag name is provided and the tag
456
+
doesn't exist, it will be created.
457
+
458
+
@param api_key API key for authentication
459
+
@param tag_refs List of tag references (either by ID or name)
460
+
@param base_url Base URL of the Karakeep instance
461
+
@param bookmark_id ID of the bookmark to tag
462
+
@return A Lwt promise with the list of attached tag IDs *)
463
+
464
+
val detach_tags :
465
+
api_key:string ->
466
+
tag_refs:[ `TagId of tag_id | `TagName of string ] list ->
467
+
string ->
468
+
bookmark_id ->
469
+
tag_id list Lwt.t
470
+
(** [detach_tags ~api_key ~tag_refs base_url bookmark_id] detaches tags from a
471
+
bookmark.
472
+
473
+
This function removes one or more tags from a bookmark. Tags can be referred
474
+
to either by their ID or by their name.
475
+
476
+
@param api_key API key for authentication
477
+
@param tag_refs List of tag references (either by ID or name)
478
+
@param base_url Base URL of the Karakeep instance
479
+
@param bookmark_id ID of the bookmark to remove tags from
480
+
@return A Lwt promise with the list of detached tag IDs *)
481
+
482
+
val fetch_all_tags : api_key:string -> string -> tag list Lwt.t
483
+
(** [fetch_all_tags ~api_key base_url] fetches all tags.
484
+
485
+
This function retrieves all tags from the Karakeep instance.
486
+
487
+
@param api_key API key for authentication
488
+
@param base_url Base URL of the Karakeep instance
489
+
@return A Lwt promise with the list of all tags *)
490
+
491
+
val fetch_tag_details : api_key:string -> string -> tag_id -> tag Lwt.t
492
+
(** [fetch_tag_details ~api_key base_url tag_id] fetches detailed information
493
+
for a single tag by ID.
494
+
495
+
This function retrieves complete details for a specific tag identified by
496
+
its ID.
497
+
498
+
@param api_key API key for authentication
499
+
@param base_url Base URL of the Karakeep instance
500
+
@param tag_id ID of the tag to fetch
501
+
@return A Lwt promise with the complete tag details *)
502
+
503
+
val fetch_bookmarks_with_tag :
504
+
api_key:string ->
505
+
?limit:int ->
506
+
?cursor:string ->
507
+
?include_content:bool ->
508
+
string ->
509
+
tag_id ->
510
+
paginated_bookmarks Lwt.t
511
+
(** [fetch_bookmarks_with_tag ~api_key ?limit ?cursor ?include_content base_url
512
+
tag_id] fetches bookmarks with a specific tag.
513
+
514
+
This function retrieves bookmarks that have been tagged with a specific tag.
515
+
516
+
@param api_key API key for authentication
517
+
@param limit Number of bookmarks to fetch per page (default: 50)
518
+
@param cursor Optional pagination cursor
519
+
@param include_content Whether to include full content (default: true)
520
+
@param base_url Base URL of the Karakeep instance
521
+
@param tag_id ID of the tag to filter by
522
+
@return
523
+
A Lwt promise with the bookmark response containing bookmarks with the tag *)
524
+
525
+
val update_tag :
526
+
api_key:string -> name:string -> string -> tag_id -> tag Lwt.t
527
+
(** [update_tag ~api_key ~name base_url tag_id] updates a tag's name.
528
+
529
+
This function changes the name of an existing tag.
530
+
531
+
@param api_key API key for authentication
532
+
@param name New name for the tag
533
+
@param base_url Base URL of the Karakeep instance
534
+
@param tag_id ID of the tag to update
535
+
@return A Lwt promise with the updated tag details *)
536
+
537
+
val delete_tag : api_key:string -> string -> tag_id -> unit Lwt.t
538
+
(** [delete_tag ~api_key base_url tag_id] deletes a tag by its ID.
539
+
540
+
This function permanently removes a tag from the Karakeep instance and
541
+
detaches it from all bookmarks.
542
+
543
+
@param api_key API key for authentication
544
+
@param base_url Base URL of the Karakeep instance
545
+
@param tag_id ID of the tag to delete
546
+
@return A Lwt promise that completes when the tag is deleted *)
547
+
548
+
(** {1 List Operations} *)
549
+
550
+
val fetch_all_lists : api_key:string -> string -> _list list Lwt.t
551
+
(** [fetch_all_lists ~api_key base_url] fetches all lists.
552
+
553
+
This function retrieves all lists from the Karakeep instance.
554
+
555
+
@param api_key API key for authentication
556
+
@param base_url Base URL of the Karakeep instance
557
+
@return A Lwt promise with the list of all lists *)
558
+
559
+
val fetch_list_details : api_key:string -> string -> list_id -> _list Lwt.t
560
+
(** [fetch_list_details ~api_key base_url list_id] fetches detailed information
561
+
for a single list by ID.
562
+
563
+
This function retrieves complete details for a specific list identified by
564
+
its ID.
565
+
566
+
@param api_key API key for authentication
567
+
@param base_url Base URL of the Karakeep instance
568
+
@param list_id ID of the list to fetch
569
+
@return A Lwt promise with the complete list details *)
570
+
571
+
val create_list :
572
+
api_key:string ->
573
+
name:string ->
574
+
icon:string ->
575
+
?description:string ->
576
+
?parent_id:list_id ->
577
+
?list_type:list_type ->
578
+
?query:string ->
579
+
string ->
580
+
_list Lwt.t
581
+
(** [create_list ~api_key ~name ~icon ?description ?parent_id ?list_type ?query
582
+
base_url] creates a new list in Karakeep.
583
+
584
+
This function adds a new list to the Karakeep instance. Lists can be
585
+
hierarchical with parent-child relationships, and can be either manual or
586
+
smart (query-based).
587
+
588
+
@param api_key API key for authentication
589
+
@param name Name of the list (max 40 characters)
590
+
@param icon Icon for the list
591
+
@param description Optional description for the list (max 100 characters)
592
+
@param parent_id Optional parent list ID for hierarchical organization
593
+
@param list_type Type of the list (default: Manual)
594
+
@param query Optional query string for smart lists
595
+
@param base_url Base URL of the Karakeep instance
596
+
@return A Lwt promise with the created list *)
597
+
598
+
val update_list :
599
+
api_key:string ->
600
+
?name:string ->
601
+
?description:string ->
602
+
?icon:string ->
603
+
?parent_id:list_id option ->
604
+
?query:string ->
605
+
string ->
606
+
list_id ->
607
+
_list Lwt.t
608
+
(** [update_list ~api_key ?name ?description ?icon ?parent_id ?query base_url
609
+
list_id] updates a list by its ID.
610
+
611
+
This function updates various attributes of an existing list. Only the
612
+
fields provided will be updated.
613
+
614
+
@param api_key API key for authentication
615
+
@param name Optional new name for the list
616
+
@param description Optional new description for the list
617
+
@param icon Optional new icon for the list
618
+
@param parent_id
619
+
Optional new parent list ID (use None to remove the parent)
620
+
@param query Optional new query for smart lists
621
+
@param base_url Base URL of the Karakeep instance
622
+
@param list_id ID of the list to update
623
+
@return A Lwt promise with the updated list details *)
624
+
625
+
val delete_list : api_key:string -> string -> list_id -> unit Lwt.t
626
+
(** [delete_list ~api_key base_url list_id] deletes a list by its ID.
627
+
628
+
This function permanently removes a list from the Karakeep instance. Note
629
+
that this does not delete the bookmarks in the list.
630
+
631
+
@param api_key API key for authentication
632
+
@param base_url Base URL of the Karakeep instance
633
+
@param list_id ID of the list to delete
634
+
@return A Lwt promise that completes when the list is deleted *)
635
+
636
+
val fetch_bookmarks_in_list :
637
+
api_key:string ->
638
+
?limit:int ->
639
+
?cursor:string ->
640
+
?include_content:bool ->
641
+
string ->
642
+
list_id ->
643
+
paginated_bookmarks Lwt.t
644
+
(** [fetch_bookmarks_in_list ~api_key ?limit ?cursor ?include_content base_url
645
+
list_id] fetches bookmarks in a specific list.
646
+
647
+
This function retrieves bookmarks that have been added to a specific list.
648
+
649
+
@param api_key API key for authentication
650
+
@param limit Number of bookmarks to fetch per page (default: 50)
651
+
@param cursor Optional pagination cursor
652
+
@param include_content Whether to include full content (default: true)
653
+
@param base_url Base URL of the Karakeep instance
654
+
@param list_id ID of the list to get bookmarks from
655
+
@return
656
+
A Lwt promise with the bookmark response containing bookmarks in the list *)
657
+
658
+
val add_bookmark_to_list :
659
+
api_key:string -> string -> list_id -> bookmark_id -> unit Lwt.t
660
+
(** [add_bookmark_to_list ~api_key base_url list_id bookmark_id] adds a bookmark
661
+
to a list.
662
+
663
+
This function adds a bookmark to a manual list. Smart lists cannot be
664
+
directly modified.
665
+
666
+
@param api_key API key for authentication
667
+
@param base_url Base URL of the Karakeep instance
668
+
@param list_id ID of the list to add the bookmark to
669
+
@param bookmark_id ID of the bookmark to add
670
+
@return A Lwt promise that completes when the bookmark is added to the list *)
671
+
672
+
val remove_bookmark_from_list :
673
+
api_key:string -> string -> list_id -> bookmark_id -> unit Lwt.t
674
+
(** [remove_bookmark_from_list ~api_key base_url list_id bookmark_id] removes a
675
+
bookmark from a list.
676
+
677
+
This function removes a bookmark from a manual list. Smart lists cannot be
678
+
directly modified.
679
+
680
+
@param api_key API key for authentication
681
+
@param base_url Base URL of the Karakeep instance
682
+
@param list_id ID of the list to remove the bookmark from
683
+
@param bookmark_id ID of the bookmark to remove
684
+
@return
685
+
A Lwt promise that completes when the bookmark is removed from the list *)
686
+
687
+
(** {1 Highlight Operations} *)
688
+
689
+
val fetch_all_highlights :
690
+
api_key:string -> ?limit:int -> ?cursor:string -> string -> paginated_highlights Lwt.t
691
+
(** [fetch_all_highlights ~api_key ?limit ?cursor base_url] fetches all
692
+
highlights.
693
+
694
+
This function retrieves highlights from the Karakeep instance with
695
+
pagination.
696
+
697
+
@param api_key API key for authentication
698
+
@param limit Number of highlights to fetch per page (default: 50)
699
+
@param cursor Optional pagination cursor
700
+
@param base_url Base URL of the Karakeep instance
701
+
@return A Lwt promise with the paginated highlights response *)
702
+
703
+
val fetch_bookmark_highlights :
704
+
api_key:string -> string -> bookmark_id -> highlight list Lwt.t
705
+
(** [fetch_bookmark_highlights ~api_key base_url bookmark_id] fetches highlights
706
+
for a specific bookmark.
707
+
708
+
This function retrieves all highlights that have been created for a specific
709
+
bookmark.
710
+
711
+
@param api_key API key for authentication
712
+
@param base_url Base URL of the Karakeep instance
713
+
@param bookmark_id ID of the bookmark to get highlights for
714
+
@return A Lwt promise with the list of highlights for the bookmark *)
715
+
716
+
val fetch_highlight_details :
717
+
api_key:string -> string -> highlight_id -> highlight Lwt.t
718
+
(** [fetch_highlight_details ~api_key base_url highlight_id] fetches detailed
719
+
information for a single highlight by ID.
720
+
721
+
This function retrieves complete details for a specific highlight identified
722
+
by its ID.
723
+
724
+
@param api_key API key for authentication
725
+
@param base_url Base URL of the Karakeep instance
726
+
@param highlight_id ID of the highlight to fetch
727
+
@return A Lwt promise with the complete highlight details *)
728
+
729
+
val create_highlight :
730
+
api_key:string ->
731
+
bookmark_id:bookmark_id ->
732
+
start_offset:int ->
733
+
end_offset:int ->
734
+
text:string ->
735
+
?note:string ->
736
+
?color:highlight_color ->
737
+
string ->
738
+
highlight Lwt.t
739
+
(** [create_highlight ~api_key ~bookmark_id ~start_offset ~end_offset ~text
740
+
?note ?color base_url] creates a new highlight in Karakeep.
741
+
742
+
This function adds a new highlight to a bookmark in the Karakeep instance.
743
+
Highlights mark specific portions of the bookmark's content.
744
+
745
+
@param api_key API key for authentication
746
+
@param bookmark_id ID of the bookmark to highlight
747
+
@param start_offset Starting position of the highlight
748
+
@param end_offset Ending position of the highlight
749
+
@param text Text content of the highlight
750
+
@param note Optional note for the highlight
751
+
@param color Color of the highlight (default: Yellow)
752
+
@param base_url Base URL of the Karakeep instance
753
+
@return A Lwt promise with the created highlight *)
754
+
755
+
val update_highlight :
756
+
api_key:string ->
757
+
?color:highlight_color ->
758
+
string ->
759
+
highlight_id ->
760
+
highlight Lwt.t
761
+
(** [update_highlight ~api_key ?color base_url highlight_id] updates a highlight
762
+
by its ID.
763
+
764
+
This function updates the color of an existing highlight.
765
+
766
+
@param api_key API key for authentication
767
+
@param color New color for the highlight
768
+
@param base_url Base URL of the Karakeep instance
769
+
@param highlight_id ID of the highlight to update
770
+
@return A Lwt promise with the updated highlight details *)
771
+
772
+
val delete_highlight : api_key:string -> string -> highlight_id -> unit Lwt.t
773
+
(** [delete_highlight ~api_key base_url highlight_id] deletes a highlight by its
774
+
ID.
775
+
776
+
This function permanently removes a highlight from the Karakeep instance.
777
+
778
+
@param api_key API key for authentication
779
+
@param base_url Base URL of the Karakeep instance
780
+
@param highlight_id ID of the highlight to delete
781
+
@return A Lwt promise that completes when the highlight is deleted *)
782
+
783
+
(** {1 Asset Operations} *)
784
+
785
+
val fetch_asset : api_key:string -> string -> asset_id -> string Lwt.t
786
+
(** [fetch_asset ~api_key base_url asset_id] fetches an asset from the Karakeep
787
+
server as a binary string.
788
+
789
+
Assets can include images, PDFs, or other files attached to bookmarks. This
790
+
function retrieves the binary content of an asset by its ID.
791
+
792
+
@param api_key API key for authentication
793
+
@param base_url Base URL of the Karakeep instance
794
+
@param asset_id ID of the asset to fetch
795
+
@return A Lwt promise with the binary asset data *)
796
+
797
+
val get_asset_url : string -> asset_id -> string
798
+
(** [get_asset_url base_url asset_id] returns the full URL for a given asset ID.
799
+
800
+
This is a pure function that constructs the URL for an asset without making
801
+
any API calls. The returned URL can be used to access the asset directly,
802
+
assuming proper authentication.
803
+
804
+
@param base_url Base URL of the Karakeep instance
805
+
@param asset_id ID of the asset
806
+
@return The full URL to the asset *)
807
+
808
+
val attach_asset :
809
+
api_key:string ->
810
+
asset_id:asset_id ->
811
+
asset_type:asset_type ->
812
+
string ->
813
+
bookmark_id ->
814
+
asset Lwt.t
815
+
(** [attach_asset ~api_key ~asset_id ~asset_type base_url bookmark_id] attaches
816
+
an asset to a bookmark.
817
+
818
+
This function adds an existing asset to a bookmark.
819
+
820
+
@param api_key API key for authentication
821
+
@param asset_id ID of the asset to attach
822
+
@param asset_type Type of the asset
823
+
@param base_url Base URL of the Karakeep instance
824
+
@param bookmark_id ID of the bookmark to attach the asset to
825
+
@return A Lwt promise with the attached asset details *)
826
+
827
+
val replace_asset :
828
+
api_key:string ->
829
+
new_asset_id:asset_id ->
830
+
string ->
831
+
bookmark_id ->
832
+
asset_id ->
833
+
unit Lwt.t
834
+
(** [replace_asset ~api_key ~new_asset_id base_url bookmark_id asset_id]
835
+
replaces an asset on a bookmark with a new one.
836
+
837
+
This function replaces an existing asset on a bookmark with a different
838
+
asset.
839
+
840
+
@param api_key API key for authentication
841
+
@param new_asset_id ID of the new asset
842
+
@param base_url Base URL of the Karakeep instance
843
+
@param bookmark_id ID of the bookmark
844
+
@param asset_id ID of the asset to replace
845
+
@return A Lwt promise that completes when the asset is replaced *)
846
+
847
+
val detach_asset :
848
+
api_key:string -> string -> bookmark_id -> asset_id -> unit Lwt.t
849
+
(** [detach_asset ~api_key base_url bookmark_id asset_id] detaches an asset from
850
+
a bookmark.
851
+
852
+
This function removes an asset from a bookmark.
853
+
854
+
@param api_key API key for authentication
855
+
@param base_url Base URL of the Karakeep instance
856
+
@param bookmark_id ID of the bookmark
857
+
@param asset_id ID of the asset to detach
858
+
@return A Lwt promise that completes when the asset is detached *)
859
+
860
+
(** {1 User Operations} *)
861
+
862
+
val get_current_user : api_key:string -> string -> user_info Lwt.t
863
+
(** [get_current_user ~api_key base_url] gets information about the current
864
+
user.
865
+
866
+
This function retrieves details about the authenticated user.
867
+
868
+
@param api_key API key for authentication
869
+
@param base_url Base URL of the Karakeep instance
870
+
@return A Lwt promise with the user information *)
871
+
872
+
val get_user_stats : api_key:string -> string -> user_stats Lwt.t
873
+
(** [get_user_stats ~api_key base_url] gets statistics about the current user.
874
+
875
+
This function retrieves statistics about the authenticated user, such as the
876
+
number of bookmarks, tags, lists, etc.
877
+
878
+
@param api_key API key for authentication
879
+
@param base_url Base URL of the Karakeep instance
880
+
@return A Lwt promise with the user statistics *)