Skip to main content

API reference

Every endpoint of the Linkdean HTTP API (version 0.0.11), generated from the routes. The same description as an OpenAPI 3.1 document: openapi.json. A running instance also serves its own copy at /api/openapi.json.

Basics​

  • Base URL: https://<your instance>/api, for example https://app.linkdean.app/api.
  • Authentication: send an API key (create one under Config options → API keys) as Authorization: Bearer ldk_…. Endpoints marked sign-in session only refuse API keys, so a leaked key cannot mint more keys or use admin powers.
  • Errors: every error has the same JSON body, { "code": "not_found", "message": "not found", "details": { … }, "error": "not found" }. Match on code, show message. details appears only for some codes (banned, quota_exceeded, vault_move_blocked). error repeats message for older clients.
  • Caching: successful JSON reads carry an ETag and Cache-Control: private, no-cache. Send the tag back in If-None-Match to get 304 Not Modified with no body.
  • Rate limits: sign-in, registration and some writes answer 429 with code too_many_requests when called too often.
  • Request IDs: every response has an X-Request-Id. Send your own (letters, digits, _, -, ., up to 128) to follow a request through the server logs and traces.

Error codes​

CodeStatusMeaning
bad_request400The input was refused; message says why.
invalid_body422The JSON body did not match the expected fields.
unauthorized401Wrong password, or no credentials where they are needed.
session_expired401The session or API key is missing, expired or revoked.
forbidden403Signed in, but not allowed.
banned403The account is banned; details.ban has the reason and end.
email_unverified403The instance requires a verified email address first.
quota_exceeded403details has meter, limit and used.
not_found404No such thing, or not visible to you.
method_not_allowed405The path exists with other methods.
conflict409Already exists or changed meanwhile.
vault_move_blocked409details.blockers lists what to undo first.
payload_too_large413The upload is over the limit.
unsupported_media_type415Send Content-Type: application/json.
vault_locked423Unlock the vault first.
vault_unlock_failed401Wrong vault passphrase.
too_many_requests429Slow down and retry later.
internal500Server error; quote the X-Request-Id.

Endpoints​

Activity​

GET /activity​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
limitqueryinteger (int64)
subject_typequerystring
actionquerystring

200: any

Admin​

GET /admin/bans​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

200: any

PATCH /admin/bans​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

Body (application/json): ChangeBans

200: any

POST /admin/bans/lift​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

Body (application/json): LiftBans

200: any

GET /admin/email​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

200: any

POST /admin/email/test​

Sends straight away, skipping the outbox, so the admin sees the SMTP result at once.

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

200: any

GET /admin/invites​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

200: any

POST /admin/invites​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

Body (application/json): CreateRegistrationInvite

200: any

DELETE /admin/invites/{id}​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

GET /admin/platform-settings​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

200: any

PATCH /admin/platform-settings​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

Body (application/json): UpdatePlatformSettings

200: any

GET /admin/reports​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
statusquerystring

200: any

POST /admin/reports/{id}/resolve​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): ResolveAbuseReport

200: any

GET /admin/screenshots/retry​

What the retry button needs: how many failed screenshots a retry would take, and when it is next allowed.

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

200: any

POST /admin/screenshots/retry​

Queue failed screenshots for another try, at most once per cooldown. Only failures older than the cooldown are taken, so a page that just failed is not tried again at once.

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

200: any

POST /admin/search/reindex​

Clear Meili bookmarks index and re-upsert all non-vault, non-deleted bookmarks.

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

200: any

GET /admin/users​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

200: any

PATCH /admin/users/{id}​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): UpdateAdminUser

200: any

POST /admin/users/{id}/ban​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): CreateBan

200: any

POST /admin/users/{id}/email​

Change an account's email at once. The admin vouches for the address, so it counts as verified.

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): ChangeEmail

200: any

POST /admin/users/{id}/email-verified​

Mark an account verified (its waiting invites attach) or remove its verification (new invites wait; accepted shares stay).

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): SetEmailVerified

200: any

GET /admin/users/{id}/exposed-content​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

POST /admin/users/{id}/moderate​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): ModerateRequest

200: any

GET /admin/users/{id}/moderation-actions​

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

POST /admin/users/{id}/reset-link​

A reset link to hand over privately; the only way back in when mail is off.

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

Agent Skill​

GET /agent-skill​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
folderquerystring (uuid)
tagquerystring
formatquerystringzip (default): a <name>/ folder. md: the SKILL.md alone, every link inline.

200: OK

API keys​

GET /api-keys​

Auth: API key or sign-in session (bearer token or cookie).

200: any

POST /api-keys​

Login sessions only: a key that could mint keys would survive its own revocation.

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

Body (application/json): CreateApiKey

200: CreateApiKeyResponse

DELETE /api-keys/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

Auth​

GET /auth/bootstrap-status​

Auth: None (public).

200: any

GET /auth/config​

Auth: None (public).

200: any

POST /auth/email/change​

Start an email change: the link goes to the new address, a notice to the old one. The address stays the same until the link is opened.

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): ChangeRequest

200: any

POST /auth/email/confirm-change​

Finish an email change with its link. No session needed.

Auth: None (public).

Body (application/json): TokenRequest

200: any

POST /auth/email/resend​

Send a new verification link to the signed-in account's address.

Auth: API key or sign-in session (bearer token or cookie).

200: any

POST /auth/email/verify​

Verify an address with its link. No session needed.

Auth: None (public).

Body (application/json): TokenRequest

200: any

POST /auth/extension/authorize​

Login sessions only, like creating any API key: a key must never mint another.

Auth: Sign-in session only (bearer session token or cookie); API keys are refused.

Body (application/json): AuthorizeRequest

200: any

POST /auth/extension/token​

No session: the extension proves itself with the verifier only it holds.

Auth: None (public).

Body (application/json): TokenRequest

200: any

POST /auth/login​

Auth: None (public).

Body (application/json): LoginRequest

200: OK

POST /auth/logout​

Auth: None (public).

200: OK

GET /auth/me​

Auth: API key or sign-in session (bearer token or cookie).

200: any

GET /auth/oidc/callback​

Always redirects: home with a session, the login page with a pending link or a reason, or back to the profile page in connect mode.

Auth: None (public).

ParameterInTypeRequiredNotes
codequerystring
statequerystring
errorquerystring

200: OK

POST /auth/oidc/disconnect​

Detach single sign-on after a password check. Accounts without a password cannot, so they keep a way to sign in. Wrong passwords count against the sign-in limits.

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): DisconnectRequest

200: any

The masked provider address of the browser's pending link, for the login prompt. 404 when there is none or it expired or was used.

Auth: None (public).

200: any

GET /auth/oidc/start​

?mode=connect attaches the provider identity to the signed-in account instead of signing in; it needs a session. Sign-in may create an account, so it needs ?terms_version= equal to the current terms version; the flow cookie carries it to the callback, which records it on a new account. Existing accounts sign in unchanged. Connect mode never creates an account.

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
modequerystring
terms_versionquerystring
providerquerystringoidc, google, microsoft or github; the first configured one when unset.
returnquerystringReauth mode: profile returns to the profile page, anything else to settings.

200: OK

POST /auth/onboarding/complete​

Auth: API key or sign-in session (bearer token or cookie).

200: any

POST /auth/passkey/finish​

Checks the passkey's answer and signs in. Failures count against the address's sign-in limit.

Auth: None (public).

Body (application/json): LoginFinish

200: OK

POST /auth/passkey/start​

Starts a passkey sign-in. Anyone may ask; it costs a row that expires in minutes.

Auth: None (public).

200: any

POST /auth/password/forgot​

Always answers the same, at once; the lookup and email happen in the background, so neither the reply nor its timing says whether the address has an account.

Auth: None (public).

Body (application/json): ForgotRequest

200: any

POST /auth/password/reset​

Set the new password, end every session and sign this browser in.

Auth: None (public).

Body (application/json): ResetRequest

200: OK

POST /auth/register​

Local sign-up. The first account becomes admin and needs BOOTSTRAP_TOKEN when one is set; later ones need open registration or an invite. create_user_gated checks both and claims the invite under one lock and transaction.

Auth: None (public).

Body (application/json): RegisterRequest

200: OK

Bookmarks​

GET /bookmarks​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
category_idquerystring (uuid)
folderquerystring
limitqueryinteger (int64)
cursorquerystring
sortquerystring
tagquerystringComma-separated or single tag name(s).
flagquerystringComma-separated or single flag name(s).
sincequerystringRFC3339 timestamp lower bound on created_at.
include_vaultqueryboolean
vaultquerystringAlias: vault=1 also sets vault-only filter.
vault_onlyqueryboolean

200: BookmarkListResponse

POST /bookmarks​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): CreateBookmark

200: BookmarkView

GET /bookmarks/broken​

Auth: API key or sign-in session (bearer token or cookie).

200: BookmarkView[]

GET /bookmarks/duplicates​

Auth: API key or sign-in session (bearer token or cookie).

200: any

GET /bookmarks/folder-counts​

Live bookmarks per folder and in Unsorted, for Explorer's folder tiles.

Auth: API key or sign-in session (bearer token or cookie).

200: FolderCounts

GET /bookmarks/ids​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
category_idquerystring (uuid)
folderquerystring
limitqueryinteger (int64)
cursorquerystring
sortquerystring
tagquerystringComma-separated or single tag name(s).
flagquerystringComma-separated or single flag name(s).
sincequerystringRFC3339 timestamp lower bound on created_at.
include_vaultqueryboolean
vaultquerystringAlias: vault=1 also sets vault-only filter.
vault_onlyqueryboolean

200: BookmarkIdsResponse

GET /bookmarks/lookup​

The person's own bookmark at exactly this URL, if any, so quick save can open it instead of saving a second copy. Vault bookmarks are never matched.

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
urlquerystringyes

200: any

POST /bookmarks/page-details​

Fetches a page's title, description and keyword tags so the bookmark form can fill in what the person has not typed yet. Nothing is saved. Counts as one enrich action and is rate limited per user. The SPA never calls it for a bookmark headed into a vault.

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): PageDetailsRequest

200: any

GET /bookmarks/url-hashes​

Hashes of every URL the person has saved, for the browser extension's saved-page icon.

Auth: API key or sign-in session (bearer token or cookie).

200: any

DELETE /bookmarks/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

GET /bookmarks/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: BookmarkView

PATCH /bookmarks/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): UpdateBookmark

200: BookmarkView

POST /bookmarks/{id}/check-link​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: BookmarkView

GET /bookmarks/{id}/favicon​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: OK

GET /bookmarks/{id}/filing-suggestions​

Folders and tags the person already uses on this bookmark's site, for the filing queue.

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: FilingSuggestions

GET /bookmarks/{id}/og​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: OK

POST /bookmarks/{id}/open​

Records that the signed-in person opened the bookmark, for the dashboard's Most opened and Recently visited sections. Vault bookmarks are not recorded.

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: OK

DELETE /bookmarks/{id}/preview​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: BookmarkView

GET /bookmarks/{id}/preview​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: OK

POST /bookmarks/{id}/preview​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (multipart/form-data): A file field with a PNG, JPEG or WebP image.

200: BookmarkView

POST /bookmarks/{id}/save​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: BookmarkView

Categories​

GET /categories​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
include_hiddenqueryboolean
include_vaultqueryboolean

200: CategoryView[]

POST /categories​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): CreateCategory

200: CategoryView

DELETE /categories/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

PATCH /categories/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): UpdateCategory

200: CategoryView

POST /categories/{id}/fork​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): ForkCategory

200: any

DELETE /categories/{id}/pending-shares/{pending_id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes
pending_idpathstring (uuid)yes

200: any

PATCH /categories/{id}/pending-shares/{pending_id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes
pending_idpathstring (uuid)yes

Body (application/json): UpdatePendingShareInvite

200: PendingShareInviteView

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: CategoryPublicLinkView

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: CategoryPublicLinkView

POST /categories/{id}/public-link​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: CategoryPublicLinkView

POST /categories/{id}/public-link/rotate​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: CategoryPublicLinkView

GET /categories/{id}/shares​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: CategorySharesEnvelope

POST /categories/{id}/shares​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): CreateCategoryShare

200: any

DELETE /categories/{id}/shares/{user_id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes
user_idpathstring (uuid)yes

200: any

PATCH /categories/{id}/shares/{user_id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes
user_idpathstring (uuid)yes

Body (application/json): UpdateCategoryShare

200: CategoryShareView

Dashboards​

GET /dashboards​

Auth: API key or sign-in session (bearer token or cookie).

200: DashboardSummary[]

POST /dashboards​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): CreateDashboard

200: DashboardView

GET /dashboards/default​

Auth: API key or sign-in session (bearer token or cookie).

200: DashboardView

PUT /dashboards/default​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): PutDashboardLayout

200: DashboardView

DELETE /dashboards/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: DashboardSummary[]

GET /dashboards/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: DashboardView

PATCH /dashboards/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): PatchDashboard

200: DashboardView

PUT /dashboards/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): PutDashboardLayout

200: DashboardView

DELETE /dashboards/{id}/pending-shares/{pending_id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes
pending_idpathstring (uuid)yes

200: any

PATCH /dashboards/{id}/pending-shares/{pending_id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes
pending_idpathstring (uuid)yes

Body (application/json): UpdatePendingShareInvite

200: PendingShareInviteView

GET /dashboards/{id}/shares​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: DashboardSharesEnvelope

POST /dashboards/{id}/shares​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): CreateDashboardShare

200: any

DELETE /dashboards/{id}/shares/{user_id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes
user_idpathstring (uuid)yes

200: any

PATCH /dashboards/{id}/shares/{user_id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes
user_idpathstring (uuid)yes

Body (application/json): UpdateDashboardShare

200: DashboardShareView

Email​

GET /email/unsubscribe​

Auth: None (public).

ParameterInTypeRequiredNotes
uquerystring
squerystring
tquerystring

200: any

POST /email/unsubscribe​

Auth: None (public).

ParameterInTypeRequiredNotes
uquerystring
squerystring
tquerystring

200: any

Export​

GET /export​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
formatquerystring

200: OK

Health​

GET /health​

Liveness. Reports the running version so a deploy can confirm which build is live.

Auth: None (public).

200: OK

Import​

POST /import​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): ImportBody

200: any

POST /import/preview​

What an import of this file would do: which bookmarks are already in the library, and how many folders would be reused. Writes nothing.

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): ImportBody

200: ImportPreview

This document​

GET /openapi.json​

This API's OpenAPI 3.1 description.

Auth: None (public).

200: OpenAPI 3.1 document

Metrics​

GET /metrics​

Auth: None (public).

200: OK

Notifications​

GET /notifications​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
limitqueryinteger (int64)

200: any

POST /notifications/read-all​

Auth: API key or sign-in session (bearer token or cookie).

200: any

GET /notifications/unread-count​

Auth: API key or sign-in session (bearer token or cookie).

200: any

POST /notifications/{id}/read​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

Public​

GET /public/lists/{slug}​

Auth: None (public).

ParameterInTypeRequiredNotes
slugpathstringyes

200: PublicListView

GET /public/lists/{slug}/bookmarks/{id}/favicon​

Auth: None (public).

ParameterInTypeRequiredNotes
slugpathstringyes
idpathstring (uuid)yes

200: OK

GET /public/lists/{slug}/bookmarks/{id}/og​

Auth: None (public).

ParameterInTypeRequiredNotes
slugpathstringyes
idpathstring (uuid)yes

200: OK

GET /public/lists/{slug}/bookmarks/{id}/preview​

Auth: None (public).

ParameterInTypeRequiredNotes
slugpathstringyes
idpathstring (uuid)yes

200: OK

Ready​

GET /ready​

Liveness of dependencies (Postgres + Meilisearch). Use for Compose / k8s probes.

Auth: None (public).

200: OK

Reports​

POST /reports​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): CreateAbuseReport

200: any

GET /reports/config​

Where to send abuse and takedown requests that do not fit the report form.

Auth: API key or sign-in session (bearer token or cookie).

200: any

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
qquerystringyes
limitqueryinteger

200: any

Share invites​

GET /share-invites​

Auth: API key or sign-in session (bearer token or cookie).

200: any

POST /share-invites/{id}/accept​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

POST /share-invites/{id}/reject​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

POST /share-invites/{id}/restore​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

Shares​

POST /shares/claim​

Claim an invite link while signed in. The invite must be for this account's address; it then shows up with the other invites to accept.

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): ClaimRequest

200: any

Social​

DELETE /social/comments/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

GET /social/{subject_type}/{subject_id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
subject_typepathstringyes
subject_idpathstring (uuid)yes

200: any

POST /social/{subject_type}/{subject_id}/comments​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
subject_typepathstringyes
subject_idpathstring (uuid)yes

Body (application/json): CreateSocialComment

200: any

DELETE /social/{subject_type}/{subject_id}/like​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
subject_typepathstringyes
subject_idpathstring (uuid)yes

200: any

POST /social/{subject_type}/{subject_id}/like​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
subject_typepathstringyes
subject_idpathstring (uuid)yes

200: any

DELETE /social/{subject_type}/{subject_id}/rating​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
subject_typepathstringyes
subject_idpathstring (uuid)yes

200: any

POST /social/{subject_type}/{subject_id}/rating​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
subject_typepathstringyes
subject_idpathstring (uuid)yes

Body (application/json): UpsertSocialRating

200: any

Tags​

GET /tags​

Auth: API key or sign-in session (bearer token or cookie).

200: Tag[]

Trash​

GET /trash​

Auth: API key or sign-in session (bearer token or cookie).

200: TrashItem[]

POST /trash/purge​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): PurgeTrashRequest

200: any

DELETE /trash/{kind}/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
kindpathstringyes
idpathstring (uuid)yes

200: any

POST /trash/{kind}/{id}/restore​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
kindpathstringyes
idpathstring (uuid)yes

200: any

Users​

PATCH /users/me​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): UpdateProfile

200: any

DELETE /users/me/avatar​

Auth: API key or sign-in session (bearer token or cookie).

200: any

GET /users/me/avatar​

Auth: API key or sign-in session (bearer token or cookie).

200: OK

POST /users/me/avatar​

Auth: API key or sign-in session (bearer token or cookie).

Body (multipart/form-data): A file field with the image.

200: any

GET /users/me/blocked​

Auth: API key or sign-in session (bearer token or cookie).

200: any

DELETE /users/me/deletion​

Auth: API key or sign-in session (bearer token or cookie).

200: any

POST /users/me/deletion​

Schedules the account for deletion after the grace period. The session stays signed in, so the person can still export their data and cancel.

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): ScheduleAccountDeletion

200: any

GET /users/me/followers​

Auth: API key or sign-in session (bearer token or cookie).

200: any

GET /users/me/following​

Auth: API key or sign-in session (bearer token or cookie).

200: any

GET /users/me/muted​

Auth: API key or sign-in session (bearer token or cookie).

200: any

GET /users/me/notification-emails​

Which notification kinds the user also gets by email, and how, in settings order.

Auth: API key or sign-in session (bearer token or cookie).

200: any

PUT /users/me/notification-emails/{kind}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
kindpathstringyes

Body (application/json): SetNotificationEmail

200: any

GET /users/me/passkeys​

Auth: API key or sign-in session (bearer token or cookie).

200: any

POST /users/me/passkeys/register/finish​

Saves the passkey the browser made, and tells the account's address.

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): RegisterFinish

200: any

POST /users/me/passkeys/register/start​

Starts adding a passkey to the signed-in account. Login sessions only, not API keys.

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): RegisterStart

200: any

DELETE /users/me/passkeys/{id}​

Removes a passkey. Passkeys are never an account's only way in, so no check is needed.

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

PATCH /users/me/passkeys/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): Rename

200: any

POST /users/me/password​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): ChangePassword

200: any

GET /users/me/quota-usage​

Auth: API key or sign-in session (bearer token or cookie).

200: any

GET /users/me/settings​

Auth: API key or sign-in session (bearer token or cookie).

200: any

PATCH /users/me/settings​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): UpdateSettings

200: any

POST /users/me/terms​

Accepts the current Terms of Service, after they changed since the account last did.

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): AcceptTerms

200: any

GET /users/{id}/avatar​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: OK

DELETE /users/{id}/block​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

POST /users/{id}/block​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

GET /users/{id}/block-status​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

GET /users/{id}/bookmarks​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes
limitqueryinteger (int64)
offsetqueryinteger (int64)

200: ProfileBookmarksPage

DELETE /users/{id}/follow​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

POST /users/{id}/follow​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

GET /users/{id}/follow-status​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

GET /users/{id}/followers​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

GET /users/{id}/following​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

DELETE /users/{id}/mute​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

POST /users/{id}/mute​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

GET /users/{id}/mute-status​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

GET /users/{id}/profile​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: ProfileView

Vaults​

GET /vaults​

Auth: API key or sign-in session (bearer token or cookie).

200: any

POST /vaults​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): CreateVaultRequest

200: any

DELETE /vaults/global​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): VaultUnlockRequest

200: any

GET /vaults/global​

Auth: API key or sign-in session (bearer token or cookie).

200: any

POST /vaults/global​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): VaultUnlockRequest

200: any

PUT /vaults/global​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): ChangeGlobalPassphraseRequest

200: any

POST /vaults/global/unlock​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): VaultUnlockRequest

200: any

POST /vaults/lock-all​

Auth: API key or sign-in session (bearer token or cookie).

200: any

POST /vaults/move​

Auth: API key or sign-in session (bearer token or cookie).

Body (application/json): MoveToVaultRequest

200: OK

DELETE /vaults/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): DeleteVaultRequest

200: any

PATCH /vaults/{id}​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): RenameVaultRequest

200: any

DELETE /vaults/{id}/global​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

POST /vaults/{id}/global​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

POST /vaults/{id}/lock​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

200: any

POST /vaults/{id}/recover​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): RecoverVaultRequest

200: any

POST /vaults/{id}/recovery-key​

Replacing the recovery key cancels the old one, so it takes the vault passphrase even when the vault is unlocked.

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): VaultUnlockRequest

200: any

POST /vaults/{id}/unlock​

Auth: API key or sign-in session (bearer token or cookie).

ParameterInTypeRequiredNotes
idpathstring (uuid)yes

Body (application/json): VaultUnlockRequest

200: any

Schemas​

AbuseAction​

Type: dismiss, hide, warn, ban

AbuseTargetType​

Type: public_list, profile, comment

AcceptTerms​

Body of POST /users/me/terms.

FieldTypeRequiredNotes
terms_versionstringyesMust equal legal::TERMS_VERSION.

ApiKeyView​

Public key metadata (never includes the secret).

FieldTypeRequiredNotes
created_atstring (date-time)yes
idstring (uuid)yes
last_used_atstring (date-time)
namestringyes
prefixstringyes
revoked_atstring (date-time)

AuthorizeRequest​

FieldTypeRequiredNotes
code_challengestringyes
code_challenge_methodstring
extension_originstringyesThe extension's base address, chrome-extension://<id>/ or moz-extension://<uuid>/.
statestring

BookmarkIdsResponse​

FieldTypeRequiredNotes
idsstring (uuid)[]yes

BookmarkListResponse​

FieldTypeRequiredNotes
itemsBookmarkView[]yes
next_cursorstring
totalinteger (int64)yes

BookmarkView​

FieldTypeRequiredNotes
can_writebooleanyesWhether the requesting user may mutate this bookmark.
categoriesCategoryRef[]yes
category_idstring (uuid)Primary / first category (legacy + export). Prefer categories.
created_atstring (date-time)yes
deleted_atstring (date-time)
descriptionstring
favicon_urlstring
has_previewbooleanyes
idstring (uuid)yes
is_favoritebooleanPer-viewer flags (reading list / favorites / pin).
is_pinnedboolean
is_privatebooleanyes
is_unreadboolean
is_vaultbooleanyes
link_check_errorstring
link_check_statusLinkCheckStatus
link_check_status_codeinteger (int32)
link_checked_atstring (date-time)
notesstring
owner_display_namestringPresent for invitees — owner's display name (or email local-part).
owner_user_idstring (uuid)yes
preview_image_urlstring
shared_outbooleanOwner has shared a folder this bookmark lives in (invitees see invitee badges instead).
shared_withstring[]Owner-only: invitee display labels for the outgoing share pill tooltip.
tagsstring[]yes
titlestringyes
updated_atstring (date-time)yes
urlstringyes
vault_idstring (uuid)

CategoryAccess​

Effective access for the current user on a category.

Type: owner, read, write

CategoryPublicLinkView​

Owner-facing public-link state for a category (list).

FieldTypeRequiredNotes
enabledbooleanyes
pathstringSPA path, e.g. /l/ldl_….
slugstringPresent when enabled. High-entropy unlisted slug.

CategoryRef​

FieldTypeRequiredNotes
idstring (uuid)yes
namestringyes
pathstringyesNested path, e.g. Work / Side projects.

CategoryShareView​

FieldTypeRequiredNotes
accessShareAccessyes
category_idstring (uuid)yes
created_atstring (date-time)yes
idstring (uuid)yes
invited_by_user_idstring (uuid)yes
invitee_display_namestring
invitee_emailstringyes
invitee_user_idstring (uuid)yes
updated_atstring (date-time)yes

CategorySharesEnvelope​

FieldTypeRequiredNotes
pendingPendingShareInviteView[]yes
sharesCategoryShareView[]yes

CategoryView​

FieldTypeRequiredNotes
accessCategoryAccessyes
created_atstring (date-time)yes
deleted_atstring (date-time)
iconstring
idstring (uuid)yes
is_hiddenbooleanyes
is_vaultbooleanyes
last_bookmark_atstring (date-time)When a live bookmark directly in this folder was last added or changed. Set by list_categories only; the sidebar orders its recent folders by it.
namestringyes
owner_display_namestringPresent for invitees — owner's display name (or email local-part).
owner_user_idstring (uuid)yes
parent_idstring (uuid)
positioninteger (int32)yes
shared_outbooleanTrue when the owner has shared this folder (or an ancestor) with someone.
shared_withstring[]Owner-only: invitee display labels for the outgoing share pill tooltip.
updated_atstring (date-time)yes
vault_idstring (uuid)
visibilitystringyes

CategoryVisibility​

Who can see a category's bookmarks on the owner's profile. "Public" is reserved for the no-login Public link, so the widest tier here is Members.

Type: private, followers, members

ChangeBans​

Changes every listed ban. Fields left out keep their value.

FieldTypeRequiredNotes
daysinteger (int64)
ends_atstring (date-time)
permanentboolean
reasonstring
user_idsstring (uuid)[]yes

ChangeEmail​

FieldTypeRequiredNotes
emailstringyes

ChangeGlobalPassphraseRequest​

FieldTypeRequiredNotes
current_passphrasestringyes
new_passphrasestringyes

ChangePassword​

FieldTypeRequiredNotes
current_passwordstringyes
new_passwordstringyes
revoke_api_keysbooleanAlso revoke every API key. Other login sessions always end.

ChangeRequest​

FieldTypeRequiredNotes
new_emailstringyes
passwordstringyes

ClaimRequest​

FieldTypeRequiredNotes
tokenstringyes

CreateAbuseReport​

target_id is a public list's slug or category id, a user id, or a comment id.

FieldTypeRequiredNotes
detailsstring
reasonstringyes
target_idstringyes
target_typeAbuseTargetTypeyes

CreateApiKey​

FieldTypeRequiredNotes
namestringyes

CreateApiKeyResponse​

One-shot create response: view + plaintext token (shown once).

FieldTypeRequiredNotes
keyApiKeyViewyes
tokenstringyes

CreateBan​

ends_at or days sets the end. Neither means permanent.

FieldTypeRequiredNotes
daysinteger (int64)
ends_atstring (date-time)
reasonstringyes

CreateBookmark​

FieldTypeRequiredNotes
category_idstring (uuid)
category_idsstring (uuid)[]
descriptionstring
is_favoriteboolean
is_pinnedboolean
is_unreadboolean
notesstring
tagsstring[]
titlestring
urlstringyes
vault_idstring (uuid)For a loose vault bookmark. Categories inside a vault imply their vault.

CreateCategory​

FieldTypeRequiredNotes
iconstring
is_hiddenbooleanyes
namestringyes
parent_idstring (uuid)
vault_idstring (uuid)

CreateCategoryShare​

FieldTypeRequiredNotes
accessShareAccessyes
emailstringyes

CreateDashboard​

FieldTypeRequiredNotes
titlestring

CreateDashboardShare​

FieldTypeRequiredNotes
accessShareAccessyes
emailstringyes

CreateRegistrationInvite​

FieldTypeRequiredNotes
emailstringOptional: bind invite to this email (case-insensitive match on register).
expires_in_daysinteger (int32)Days until expiry (default 7, clamp 1..=90).

CreateSocialComment​

FieldTypeRequiredNotes
bodystringyes

CreateVaultRequest​

FieldTypeRequiredNotes
namestringyes
passphrasestringyes

DashboardItemView​

FieldTypeRequiredNotes
bookmarkBookmarkViewyes
idstring (uuid)yes
last_opened_atstring (date-time)When the viewer last opened it.
open_countinteger (int64)How often the viewer opened it: in the last 30 days for a section counting that window, otherwise of all time. Absent when never opened.
positioninteger (int32)yes

DashboardOpenWindow​

The period "Most opened" counts opens over.

Type: last_30_days, all_time

DashboardSectionDisplay​

How a section shows its bookmarks.

Type: small, medium, large, icons

DashboardSectionKind​

What fills a dashboard section.

Type: pinned, latest, most_opened, recently_visited

DashboardSectionLayout​

A section's place and size on the dashboard's 12-column grid, in grid units. The web app packs sections upward, so y orders them more than it places them.

FieldTypeRequiredNotes
hinteger (int32)yes
winteger (int32)yes
xinteger (int32)yes
yinteger (int32)yes

DashboardSectionSettings​

A section's type, display mode and source. Every field has a default, so older layouts and exports (title and pins only) still read as pinned, medium sections.

FieldTypeRequiredNotes
displayDashboardSectionDisplay
item_limitinteger (int32)
kindDashboardSectionKind
layoutDashboardSectionLayout
open_windowDashboardOpenWindow
sourceDashboardSectionSource

DashboardSectionSource​

Filters for a section that fills itself. A bookmark must match every one that is set.

FieldTypeRequiredNotes
category_idstring (uuid)A folder of the owner's, with its subfolders.
favoritesboolean
sitestringA website, such as github.com; its subdomains match too.
tagstring
unreadboolean

DashboardSectionView​

Type: DashboardSectionSettings & object

DashboardShareView​

FieldTypeRequiredNotes
accessShareAccessyes
created_atstring (date-time)yes
dashboard_idstring (uuid)yes
idstring (uuid)yes
invited_by_user_idstring (uuid)yes
invitee_display_namestring
invitee_emailstringyes
invitee_user_idstring (uuid)yes
updated_atstring (date-time)yes

DashboardSharesEnvelope​

FieldTypeRequiredNotes
pendingPendingShareInviteView[]yes
sharesDashboardShareView[]yes

DashboardSummary​

Lightweight row for switchers / settings (no sections).

FieldTypeRequiredNotes
accessCategoryAccessyes
created_atstring (date-time)yes
deleted_atstring (date-time)
idstring (uuid)yes
is_defaultbooleanyes
owner_display_namestring
owner_user_idstring (uuid)yes
shared_outboolean
shared_withstring[]
titlestringyes
updated_atstring (date-time)yes

DashboardView​

FieldTypeRequiredNotes
accessCategoryAccessyes
created_atstring (date-time)yes
deleted_atstring (date-time)
idstring (uuid)yes
is_defaultbooleanyes
owner_display_namestring
owner_user_idstring (uuid)yes
sectionsDashboardSectionView[]yes
shared_outbooleanTrue when the owner has shared this dashboard with someone.
shared_withstring[]Owner-only: invitee display labels for the outgoing share pill tooltip.
titlestringyes
updated_atstring (date-time)yes

DeleteVaultRequest​

FieldTypeRequiredNotes
namestringyes
passwordstring

DisconnectRequest​

FieldTypeRequiredNotes
passwordstringyes

DuplicateAction​

What to do with an imported bookmark whose URL is already in the library.

Type: skip, replace, merge, keep

DuplicateDecisions​

The person's choices, by index into the parsed file. Missing means Keep for every row.

FieldTypeRequiredNotes
defaultDuplicateAction
overridesmap of DuplicateAction

DuplicateExisting​

FieldTypeRequiredNotes
descriptionstring
foldersstring[]yesFull paths, Work / Rust.
idstring (uuid)yes
tagsstring[]yes
titlestringyes
updated_atstring (date-time)yes

DuplicateIncoming​

FieldTypeRequiredNotes
descriptionstring
foldersstring[]yes
tagsstring[]yes
titlestring

EmailDelivery​

How a notification kind's email arrives.

Type: instant, daily

ErrorBody​

The error body. See the module docs.

FieldTypeRequiredNotes
codestringyesStable machine-readable id, such as not_found or quota_exceeded.
detailsobjectExtra data for some codes: ban for banned, meter/limit/used for quota_exceeded, blockers for vault_move_blocked.
errorstringyesSame as message. Kept for older clients.
messagestringyesHuman-readable text. Wording may change between releases; match on code.

FilingSuggestions​

FieldTypeRequiredNotes
foldersFolderSuggestion[]yes
tagsTagSuggestion[]yes

FolderCounts​

Live bookmarks per folder the person can open, and in their Unsorted.

FieldTypeRequiredNotes
foldersmap of integer (int64)yesDirect bookmarks per folder (not counting subfolders). Folders with none are absent.
uncategorizedinteger (int64)yes

FolderSuggestion​

FieldTypeRequiredNotes
countinteger (int64)yesBookmarks on the same site in this folder.
idstring (uuid)yes

FollowRelation​

FieldTypeRequiredNotes
followersinteger (int64)yes
followingbooleanyes
following_countinteger (int64)yes

ForgotRequest​

FieldTypeRequiredNotes
emailstringyes

ForkCategory​

Copy a readable category tree (+ bookmarks) into a new owned root.

FieldTypeRequiredNotes
namestringDefaults to {name} (copy).

ImportBody​

FieldTypeRequiredNotes
contentstringyes
duplicatesDuplicateDecisionsWhat to do with bookmarks already in the library. Missing: create them all, as before.
formatstringyes

ImportDuplicate​

FieldTypeRequiredNotes
existingDuplicateExistingyes
incomingDuplicateIncomingyes
indexintegeryes
urlstringyes

ImportFolderCounts​

FieldTypeRequiredNotes
createdintegeryes
reusedintegeryes

ImportPreview​

FieldTypeRequiredNotes
duplicatesImportDuplicate[]yes
foldersImportFolderCountsyes
newintegeryes
totalintegeryes

LiftBans​

FieldTypeRequiredNotes
user_idsstring (uuid)[]yes

LinkCheckStatus​

Last probe result from the broken-link checker worker.

Type: ok, broken, unreachable, unverifiable

LoginFinish​

FieldTypeRequiredNotes
challenge_idstring (uuid)yes
credentialobjectyesThe browser's WebAuthn credential, as JSON.

LoginRequest​

FieldTypeRequiredNotes
emailstringyes
passwordstringyes

ModerateAction​

FieldTypeRequiredNotes
actionstringyes
subject_idstring (uuid)yes
subject_typestringNeeded for removed_to_trash and share_revoked.

ModerateRequest​

FieldTypeRequiredNotes
actionsModerateAction[]yes
reasonstringyes

MoveToVaultRequest​

FieldTypeRequiredNotes
bookmark_idsstring (uuid)[]
category_idsstring (uuid)[]
destination_vault_idstring (uuid)

PageDetailsRequest​

FieldTypeRequiredNotes
urlstringyes

PatchDashboard​

Rename and/or pin. Pinning a shared dashboard needs read access and only affects the caller.

FieldTypeRequiredNotes
is_defaultboolean
titlestring

PendingShareInviteView​

FieldTypeRequiredNotes
accessShareAccessyes
claim_tokenstringSingle-use claim link token. Only present in the response that created it.
created_atstring (date-time)yes
idstring (uuid)yes
invited_by_user_idstring (uuid)yes
invitee_emailstringyes
subject_idstring (uuid)yes
subject_typePendingShareSubjectTypeyes
updated_atstring (date-time)yes

PendingShareSubjectType​

Subject for a pending (pre-account) share invite.

Type: category, dashboard

ProfileBookmarksPage​

FieldTypeRequiredNotes
bookmarksPublicBookmarkView[]yes
totalinteger (int64)yes

ProfileView​

A user's profile as another signed-in user sees it.

FieldTypeRequiredNotes
biostring
display_namestringyes
emailstringSelf only.
followFollowRelationyes
has_avatarbooleanyes
idstring (uuid)yes
is_selfbooleanyes
profile_visibilitystringSelf only.

ProfileVisibility​

Who can open a profile.

Type: members, followers, hidden

PublicBookmarkView​

Bookmark fields safe to expose on a public list (no notes / vault / owner ids).

FieldTypeRequiredNotes
descriptionstring
favicon_urlstring
has_previewbooleanyes
idstring (uuid)yes
preview_image_urlstring
preview_urlstringWhere anyone may load the stored preview, when has_preview and the caller is anonymous. Set on public lists.
tagsstring[]yes
titlestringyes
urlstringyes

PublicListView​

Anonymous read model for a published bookmark list.

FieldTypeRequiredNotes
bookmarksPublicBookmarkView[]yesThe newest bookmarks, at most PUBLIC_LIST_LIMIT of them.
iconstring
namestringyes
owner_display_namestringyes
totalinteger (int64)How many bookmarks the list holds, including any left out of bookmarks.

PurgeTrashRequest​

FieldTypeRequiredNotes
itemsTrashItemRef[]yes

PutDashboardLayout​

Full layout replace for a personal dashboard.

FieldTypeRequiredNotes
sectionsPutDashboardSection[]yes
titlestring

PutDashboardSection​

Type: DashboardSectionSettings & object

RecoverVaultRequest​

FieldTypeRequiredNotes
new_passphrasestringyes
recovery_keystringyes

RegisterFinish​

FieldTypeRequiredNotes
challenge_idstring (uuid)yes
credentialobjectyesThe browser's WebAuthn credential, as JSON.
namestringyes

RegisterRequest​

FieldTypeRequiredNotes
bootstrap_tokenstringThe server's BOOTSTRAP_TOKEN, needed for the first account when one is set.
display_namestring
emailstringyes
invite_codestringRequired when registration is closed (after bootstrap).
passwordstringyes
share_tokenstringFrom a share invite's claim link.
terms_versionstringTerms of Service version the user accepted; must equal legal::TERMS_VERSION.
turnstile_tokenstringCloudflare Turnstile widget token; required when the server has Turnstile keys.

RegisterStart​

FieldTypeRequiredNotes
passwordstringRequired when the account has a password.

Rename​

FieldTypeRequiredNotes
namestringyes

RenameVaultRequest​

FieldTypeRequiredNotes
namestringyes

ResetRequest​

FieldTypeRequiredNotes
passwordstringyes
revoke_api_keysboolean
tokenstringyes

ResolveAbuseReport​

FieldTypeRequiredNotes
actionAbuseActionyes
notestring

ScheduleAccountDeletion​

Body of POST /users/me/deletion.

FieldTypeRequiredNotes
confirm_emailstringyesMust match the account email (case-insensitive).
passwordstringRequired for accounts with a local password; ignored for single sign-on only accounts.

SetEmailVerified​

FieldTypeRequiredNotes
verifiedbooleanyes

SetNotificationEmail​

FieldTypeRequiredNotes
deliveryEmailDelivery
enabledbooleanyes

ShareAccess​

Membership grant on a shared category (read / write only).

Type: read, write

Tag​

FieldTypeRequiredNotes
created_atstring (date-time)yes
idstring (uuid)yes
namestringyes
owner_user_idstring (uuid)yes

TagSuggestion​

FieldTypeRequiredNotes
countinteger (int64)yes
namestringyes

TokenRequest​

FieldTypeRequiredNotes
codestringyes
code_verifierstringyes
extension_originstringyes

TrashItem​

FieldTypeRequiredNotes
deleted_atstring (date-time)yes
idstring (uuid)yes
kindTrashKindyes
titlestringyes

TrashItemRef​

FieldTypeRequiredNotes
idstring (uuid)yes
kindTrashKindyes

TrashKind​

Type: bookmark, category, dashboard

UpdateAdminUser​

FieldTypeRequiredNotes
api_keys_enabledboolean
is_adminboolean

UpdateBookmark​

FieldTypeRequiredNotes
add_category_idsstring (uuid)[]Folders to add the bookmark to, alongside the ones it is in when the edit is saved.
add_tagsstring[]Tags to add to whatever the bookmark has when the edit is saved.
category_idstring (uuid)
category_idsstring (uuid)[]
descriptionstring
is_favoriteboolean
is_pinnedboolean
is_privateboolean
is_unreadboolean
notesstring
tagsstring[]
titlestring
urlstring

UpdateCategory​

FieldTypeRequiredNotes
iconstringSome(None) clears the icon; Some(Some(key)) sets it.
is_hiddenboolean
namestring
parent_idstring (uuid)
positioninteger (int32)
visibilityCategoryVisibility

UpdateCategoryShare​

FieldTypeRequiredNotes
accessShareAccessyes

UpdateDashboardShare​

FieldTypeRequiredNotes
accessShareAccessyes

UpdatePendingShareInvite​

FieldTypeRequiredNotes
accessShareAccessyes

UpdatePlatformSettings​

FieldTypeRequiredNotes
abuse_contact_emailstringSome(None) clears; Some(Some(email)) sets; omit = no change.
api_keys_enabledboolean
max_bookmarksinteger (int64)Some(None) clears; Some(Some(n)) sets; omit = no change.
max_enrich_actions_per_dayinteger (int64)
max_import_bytesinteger (int64)
max_stored_image_bytesinteger (int64)
max_upload_image_bytesinteger (int64)
registration_openboolean
require_verified_emailboolean
screenshot_auto_retry_daysinteger (int32)1 to 90.
screenshot_retry_cooldown_hoursinteger (int32)1 to 720.

UpdateProfile​

FieldTypeRequiredNotes
biostring
display_namestring
emailstringAccepted only when it matches the current address. An address changes through an emailed confirmation link, or by an instance admin.
profile_visibilityProfileVisibility
timezonestring

UpdateSettings​

FieldTypeRequiredNotes
default_landingstring
library_viewstring
show_deleted_in_libraryboolean
show_hiddenboolean
show_keyboard_hintsbooleanHide key numbers, key hint lines and shortcut keycaps. Missing means unchanged.
show_vault_in_libraryboolean
themestring
trash_retention_daysinteger (int32)
vault_auto_lock_minutesinteger (int32)
vault_delete_modestring
vault_search_modestring

UpsertSocialRating​

FieldTypeRequiredNotes
ratinginteger (int32)yes

VaultUnlockRequest​

FieldTypeRequiredNotes
passphrasestringyes