starred/karakeep

Fork 0

mirror of https://github.com/karakeep-app/karakeep.git synced 2026-04-25 07:56:05 +03:00

[GH-ISSUE #993] Documentation for API is entirely incorrect for bookmark creation #655

New issue

Closed

opened 2026-03-02 11:51:41 +03:00 by kerem · 2 comments

kerem commented

2026-03-02 11:51:41 +03:00

Owner

Originally created by @ShakataGaNai on GitHub (Feb 7, 2025).
Original GitHub issue: https://github.com/karakeep-app/karakeep/issues/993

Describe the Bug

https://docs.hoarder.app/api/create-a-new-bookmark/ says a request should look like:

curl -L 'https://mysite/api/v1/bookmarks' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer xxxxxx' \
-d '{
  "title": "string",
  "archived": true,
  "favourited": true,
  "note": "string",
  "summary": "string",
  "createdAt": "string"
}'

First major problem. Where does the URL go? I want to create a bookmark, this is the create a bookmark API. Yet, there is nowhere to submit an URL for the page I want to save.

Secondarily, if you follow this example you'll receive the error message:
{"code":"ParseError","message":"createdAt: Invalid date, type: Invalid discriminator value. Expected 'link' | 'text' | 'asset'"}

Upon reverse engineering the API, I have deduced the answer is:

curl -L 'https://mysite/api/v1/bookmarks' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer xxxxxx' \
-d '{
  "type": "link",
  "url": "https://mycoolsite/that/i/want/to/bookmark.html",
}'

So I'm good to go and maybe this will help someone else, but the docs are... incorrect.

Steps to Reproduce

Read the docs
Fail

Expected Behaviour

Read the docs and have examples that are valid

Screenshots or Additional Context

No response

Device Details

CLI/n8n

Exact Hoarder Version

v0.21.0

Have you checked the troubleshooting guide?

I have checked the troubleshooting guide and I haven't found a solution to my problem

Originally created by @ShakataGaNai on GitHub (Feb 7, 2025). Original GitHub issue: https://github.com/karakeep-app/karakeep/issues/993 ### Describe the Bug https://docs.hoarder.app/api/create-a-new-bookmark/ says a request should look like: ``` curl -L 'https://mysite/api/v1/bookmarks' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer xxxxxx' \ -d '{ "title": "string", "archived": true, "favourited": true, "note": "string", "summary": "string", "createdAt": "string" }' ``` First major problem. Where does the URL go? I want to create a bookmark, this is the create a bookmark API. Yet, there is nowhere to submit an URL for the page I want to save. Secondarily, if you follow this example you'll receive the error message: `{"code":"ParseError","message":"createdAt: Invalid date, type: Invalid discriminator value. Expected 'link' | 'text' | 'asset'"}` Upon reverse engineering the API, I have deduced the answer is: ``` curl -L 'https://mysite/api/v1/bookmarks' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer xxxxxx' \ -d '{ "type": "link", "url": "https://mycoolsite/that/i/want/to/bookmark.html", }' ``` So I'm good to go and maybe this will help someone else, but the docs are... incorrect. ### Steps to Reproduce 1. Read the docs 2. Fail ### Expected Behaviour Read the docs and have examples that are valid ### Screenshots or Additional Context _No response_ ### Device Details CLI/n8n ### Exact Hoarder Version v0.21.0 ### Have you checked the troubleshooting guide? - [x] I have checked the troubleshooting guide and I haven't found a solution to my problem

kerem

2026-03-02 11:51:41 +03:00

closed this issue
added the
bug

documentation

pri/high

status/approved
labels

kerem commented

2026-03-02 11:51:42 +03:00

Author

Owner

@MohamedBassem commented on GitHub (Feb 8, 2025):

Yeah, unfortunately, currently the generator we use for the API docs doesn't support union types. The API expects a "type" and some metadata depending on the type documented here (https://github.com/hoarder-app/hoarder/blob/main/packages/shared/types/bookmarks.ts#L134-L151).

@MohamedBassem commented on GitHub (Feb 8, 2025): Yeah, unfortunately, currently the generator we use for the API docs doesn't support union types. The API expects a "type" and some metadata depending on the type documented here (https://github.com/hoarder-app/hoarder/blob/main/packages/shared/types/bookmarks.ts#L134-L151).

kerem commented

2026-03-02 11:51:42 +03:00

Author

Owner

@MohamedBassem commented on GitHub (Apr 13, 2025):

This is now fixed in the last docs.

@MohamedBassem commented on GitHub (Apr 13, 2025): This is now fixed in the last docs.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/karakeep#655

No description provided.

Rows
Columns