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 examplehttps://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 oncode, showmessage.detailsappears only for some codes (banned,quota_exceeded,vault_move_blocked).errorrepeatsmessagefor older clients. - Caching: successful JSON reads carry an
ETagandCache-Control: private, no-cache. Send the tag back inIf-None-Matchto get304 Not Modifiedwith no body. - Rate limits: sign-in, registration and some writes answer
429with codetoo_many_requestswhen 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
| Code | Status | Meaning |
|---|---|---|
bad_request | 400 | The input was refused; message says why. |
invalid_body | 422 | The JSON body did not match the expected fields. |
unauthorized | 401 | Wrong password, or no credentials where they are needed. |
session_expired | 401 | The session or API key is missing, expired or revoked. |
forbidden | 403 | Signed in, but not allowed. |
banned | 403 | The account is banned; details.ban has the reason and end. |
email_unverified | 403 | The instance requires a verified email address first. |
quota_exceeded | 403 | details has meter, limit and used. |
not_found | 404 | No such thing, or not visible to you. |
method_not_allowed | 405 | The path exists with other methods. |
conflict | 409 | Already exists or changed meanwhile. |
vault_move_blocked | 409 | details.blockers lists what to undo first. |
payload_too_large | 413 | The upload is over the limit. |
unsupported_media_type | 415 | Send Content-Type: application/json. |
vault_locked | 423 | Unlock the vault first. |
vault_unlock_failed | 401 | Wrong vault passphrase. |
too_many_requests | 429 | Slow down and retry later. |
internal | 500 | Server error; quote the X-Request-Id. |
Endpoints
Activity
GET /activity
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
limit | query | integer (int64) | ||
subject_type | query | string | ||
action | query | string |
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.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
status | query | string |
200: any
POST /admin/reports/{id}/resolve
Auth: Sign-in session only (bearer session token or cookie); API keys are refused.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
POST /admin/users/{id}/moderate
Auth: Sign-in session only (bearer session token or cookie); API keys are refused.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
Agent Skill
GET /agent-skill
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
folder | query | string (uuid) | ||
tag | query | string | ||
format | query | string | zip (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
code | query | string | ||
state | query | string | ||
error | query | string |
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
GET /auth/oidc/pending-link
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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
mode | query | string | ||
terms_version | query | string | ||
provider | query | string | oidc, google, microsoft or github; the first configured one when unset. | |
return | query | string | Reauth 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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
category_id | query | string (uuid) | ||
folder | query | string | ||
limit | query | integer (int64) | ||
cursor | query | string | ||
sort | query | string | ||
tag | query | string | Comma-separated or single tag name(s). | |
flag | query | string | Comma-separated or single flag name(s). | |
since | query | string | RFC3339 timestamp lower bound on created_at. | |
include_vault | query | boolean | ||
vault | query | string | Alias: vault=1 also sets vault-only filter. | |
vault_only | query | boolean |
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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
category_id | query | string (uuid) | ||
folder | query | string | ||
limit | query | integer (int64) | ||
cursor | query | string | ||
sort | query | string | ||
tag | query | string | Comma-separated or single tag name(s). | |
flag | query | string | Comma-separated or single flag name(s). | |
since | query | string | RFC3339 timestamp lower bound on created_at. | |
include_vault | query | boolean | ||
vault | query | string | Alias: vault=1 also sets vault-only filter. | |
vault_only | query | boolean |
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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
url | query | string | yes |
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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
GET /bookmarks/{id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: BookmarkView
PATCH /bookmarks/{id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
Body (application/json): UpdateBookmark
200: BookmarkView
POST /bookmarks/{id}/check-link
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: BookmarkView
GET /bookmarks/{id}/favicon
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: FilingSuggestions
GET /bookmarks/{id}/og
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: OK
DELETE /bookmarks/{id}/preview
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: BookmarkView
GET /bookmarks/{id}/preview
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: OK
POST /bookmarks/{id}/preview
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: BookmarkView
Categories
GET /categories
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
include_hidden | query | boolean | ||
include_vault | query | boolean |
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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
PATCH /categories/{id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
Body (application/json): UpdateCategory
200: CategoryView
POST /categories/{id}/fork
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes | |
pending_id | path | string (uuid) | yes |
200: any
PATCH /categories/{id}/pending-shares/{pending_id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes | |
pending_id | path | string (uuid) | yes |
Body (application/json): UpdatePendingShareInvite
DELETE /categories/{id}/public-link
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
GET /categories/{id}/public-link
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
POST /categories/{id}/public-link
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
POST /categories/{id}/public-link/rotate
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
GET /categories/{id}/shares
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
POST /categories/{id}/shares
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes | |
user_id | path | string (uuid) | yes |
200: any
PATCH /categories/{id}/shares/{user_id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes | |
user_id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: DashboardSummary[]
GET /dashboards/{id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: DashboardView
PATCH /dashboards/{id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
Body (application/json): PatchDashboard
200: DashboardView
PUT /dashboards/{id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes | |
pending_id | path | string (uuid) | yes |
200: any
PATCH /dashboards/{id}/pending-shares/{pending_id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes | |
pending_id | path | string (uuid) | yes |
Body (application/json): UpdatePendingShareInvite
GET /dashboards/{id}/shares
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
POST /dashboards/{id}/shares
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes | |
user_id | path | string (uuid) | yes |
200: any
PATCH /dashboards/{id}/shares/{user_id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes | |
user_id | path | string (uuid) | yes |
Body (application/json): UpdateDashboardShare
200: DashboardShareView
Email
GET /email/unsubscribe
Auth: None (public).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
u | query | string | ||
s | query | string | ||
t | query | string |
200: any
POST /email/unsubscribe
Auth: None (public).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
u | query | string | ||
s | query | string | ||
t | query | string |
200: any
Export
GET /export
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
format | query | string |
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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
limit | query | integer (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
Public
GET /public/lists/{slug}
Auth: None (public).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | yes |
200: PublicListView
GET /public/lists/{slug}/bookmarks/{id}/favicon
Auth: None (public).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | yes | |
id | path | string (uuid) | yes |
200: OK
GET /public/lists/{slug}/bookmarks/{id}/og
Auth: None (public).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | yes | |
id | path | string (uuid) | yes |
200: OK
GET /public/lists/{slug}/bookmarks/{id}/preview
Auth: None (public).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | yes | |
id | path | string (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
Search
GET /search
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
q | query | string | yes | |
limit | query | integer |
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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
POST /share-invites/{id}/reject
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
POST /share-invites/{id}/restore
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
GET /social/{subject_type}/{subject_id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
subject_type | path | string | yes | |
subject_id | path | string (uuid) | yes |
200: any
POST /social/{subject_type}/{subject_id}/comments
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
subject_type | path | string | yes | |
subject_id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
subject_type | path | string | yes | |
subject_id | path | string (uuid) | yes |
200: any
POST /social/{subject_type}/{subject_id}/like
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
subject_type | path | string | yes | |
subject_id | path | string (uuid) | yes |
200: any
DELETE /social/{subject_type}/{subject_id}/rating
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
subject_type | path | string | yes | |
subject_id | path | string (uuid) | yes |
200: any
POST /social/{subject_type}/{subject_id}/rating
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
subject_type | path | string | yes | |
subject_id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
kind | path | string | yes | |
id | path | string (uuid) | yes |
200: any
POST /trash/{kind}/{id}/restore
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
kind | path | string | yes | |
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
kind | path | string | yes |
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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
PATCH /users/me/passkeys/{id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: OK
DELETE /users/{id}/block
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
POST /users/{id}/block
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
GET /users/{id}/block-status
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
GET /users/{id}/bookmarks
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes | |
limit | query | integer (int64) | ||
offset | query | integer (int64) |
200: ProfileBookmarksPage
DELETE /users/{id}/follow
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
POST /users/{id}/follow
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
GET /users/{id}/follow-status
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
GET /users/{id}/followers
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
GET /users/{id}/following
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
DELETE /users/{id}/mute
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
POST /users/{id}/mute
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
GET /users/{id}/mute-status
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
GET /users/{id}/profile
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
Body (application/json): DeleteVaultRequest
200: any
PATCH /vaults/{id}
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
Body (application/json): RenameVaultRequest
200: any
DELETE /vaults/{id}/global
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
POST /vaults/{id}/global
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
POST /vaults/{id}/lock
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
200: any
POST /vaults/{id}/recover
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (uuid) | yes |
Body (application/json): VaultUnlockRequest
200: any
POST /vaults/{id}/unlock
Auth: API key or sign-in session (bearer token or cookie).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string (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.
| Field | Type | Required | Notes |
|---|---|---|---|
terms_version | string | yes | Must equal legal::TERMS_VERSION. |
ApiKeyView
Public key metadata (never includes the secret).
| Field | Type | Required | Notes |
|---|---|---|---|
created_at | string (date-time) | yes | |
id | string (uuid) | yes | |
last_used_at | string (date-time) | ||
name | string | yes | |
prefix | string | yes | |
revoked_at | string (date-time) |
AuthorizeRequest
| Field | Type | Required | Notes |
|---|---|---|---|
code_challenge | string | yes | |
code_challenge_method | string | ||
extension_origin | string | yes | The extension's base address, chrome-extension://<id>/ or moz-extension://<uuid>/. |
state | string |
BookmarkIdsResponse
| Field | Type | Required | Notes |
|---|---|---|---|
ids | string (uuid)[] | yes |
BookmarkListResponse
| Field | Type | Required | Notes |
|---|---|---|---|
items | BookmarkView[] | yes | |
next_cursor | string | ||
total | integer (int64) | yes |
BookmarkView
| Field | Type | Required | Notes |
|---|---|---|---|
can_write | boolean | yes | Whether the requesting user may mutate this bookmark. |
categories | CategoryRef[] | yes | |
category_id | string (uuid) | Primary / first category (legacy + export). Prefer categories. | |
created_at | string (date-time) | yes | |
deleted_at | string (date-time) | ||
description | string | ||
favicon_url | string | ||
has_preview | boolean | yes | |
id | string (uuid) | yes | |
is_favorite | boolean | Per-viewer flags (reading list / favorites / pin). | |
is_pinned | boolean | ||
is_private | boolean | yes | |
is_unread | boolean | ||
is_vault | boolean | yes | |
link_check_error | string | ||
link_check_status | LinkCheckStatus | ||
link_check_status_code | integer (int32) | ||
link_checked_at | string (date-time) | ||
notes | string | ||
owner_display_name | string | Present for invitees — owner's display name (or email local-part). | |
owner_user_id | string (uuid) | yes | |
preview_image_url | string | ||
shared_out | boolean | Owner has shared a folder this bookmark lives in (invitees see invitee badges instead). | |
shared_with | string[] | Owner-only: invitee display labels for the outgoing share pill tooltip. | |
tags | string[] | yes | |
title | string | yes | |
updated_at | string (date-time) | yes | |
url | string | yes | |
vault_id | string (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).
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | yes | |
path | string | SPA path, e.g. /l/ldl_…. | |
slug | string | Present when enabled. High-entropy unlisted slug. |
CategoryRef
| Field | Type | Required | Notes |
|---|---|---|---|
id | string (uuid) | yes | |
name | string | yes | |
path | string | yes | Nested path, e.g. Work / Side projects. |
CategoryShareView
| Field | Type | Required | Notes |
|---|---|---|---|
access | ShareAccess | yes | |
category_id | string (uuid) | yes | |
created_at | string (date-time) | yes | |
id | string (uuid) | yes | |
invited_by_user_id | string (uuid) | yes | |
invitee_display_name | string | ||
invitee_email | string | yes | |
invitee_user_id | string (uuid) | yes | |
updated_at | string (date-time) | yes |
CategorySharesEnvelope
| Field | Type | Required | Notes |
|---|---|---|---|
pending | PendingShareInviteView[] | yes | |
shares | CategoryShareView[] | yes |
CategoryView
| Field | Type | Required | Notes |
|---|---|---|---|
access | CategoryAccess | yes | |
created_at | string (date-time) | yes | |
deleted_at | string (date-time) | ||
icon | string | ||
id | string (uuid) | yes | |
is_hidden | boolean | yes | |
is_vault | boolean | yes | |
last_bookmark_at | string (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. | |
name | string | yes | |
owner_display_name | string | Present for invitees — owner's display name (or email local-part). | |
owner_user_id | string (uuid) | yes | |
parent_id | string (uuid) | ||
position | integer (int32) | yes | |
shared_out | boolean | True when the owner has shared this folder (or an ancestor) with someone. | |
shared_with | string[] | Owner-only: invitee display labels for the outgoing share pill tooltip. | |
updated_at | string (date-time) | yes | |
vault_id | string (uuid) | ||
visibility | string | yes |
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.
| Field | Type | Required | Notes |
|---|---|---|---|
days | integer (int64) | ||
ends_at | string (date-time) | ||
permanent | boolean | ||
reason | string | ||
user_ids | string (uuid)[] | yes |
ChangeEmail
| Field | Type | Required | Notes |
|---|---|---|---|
email | string | yes |
ChangeGlobalPassphraseRequest
| Field | Type | Required | Notes |
|---|---|---|---|
current_passphrase | string | yes | |
new_passphrase | string | yes |
ChangePassword
| Field | Type | Required | Notes |
|---|---|---|---|
current_password | string | yes | |
new_password | string | yes | |
revoke_api_keys | boolean | Also revoke every API key. Other login sessions always end. |
ChangeRequest
| Field | Type | Required | Notes |
|---|---|---|---|
new_email | string | yes | |
password | string | yes |
ClaimRequest
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes |
CreateAbuseReport
target_id is a public list's slug or category id, a user id, or a comment id.
| Field | Type | Required | Notes |
|---|---|---|---|
details | string | ||
reason | string | yes | |
target_id | string | yes | |
target_type | AbuseTargetType | yes |
CreateApiKey
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes |
CreateApiKeyResponse
One-shot create response: view + plaintext token (shown once).
| Field | Type | Required | Notes |
|---|---|---|---|
key | ApiKeyView | yes | |
token | string | yes |
CreateBan
ends_at or days sets the end. Neither means permanent.
| Field | Type | Required | Notes |
|---|---|---|---|
days | integer (int64) | ||
ends_at | string (date-time) | ||
reason | string | yes |
CreateBookmark
| Field | Type | Required | Notes |
|---|---|---|---|
category_id | string (uuid) | ||
category_ids | string (uuid)[] | ||
description | string | ||
is_favorite | boolean | ||
is_pinned | boolean | ||
is_unread | boolean | ||
notes | string | ||
tags | string[] | ||
title | string | ||
url | string | yes | |
vault_id | string (uuid) | For a loose vault bookmark. Categories inside a vault imply their vault. |
CreateCategory
| Field | Type | Required | Notes |
|---|---|---|---|
icon | string | ||
is_hidden | boolean | yes | |
name | string | yes | |
parent_id | string (uuid) | ||
vault_id | string (uuid) |
CreateCategoryShare
| Field | Type | Required | Notes |
|---|---|---|---|
access | ShareAccess | yes | |
email | string | yes |
CreateDashboard
| Field | Type | Required | Notes |
|---|---|---|---|
title | string |
CreateDashboardShare
| Field | Type | Required | Notes |
|---|---|---|---|
access | ShareAccess | yes | |
email | string | yes |
CreateRegistrationInvite
| Field | Type | Required | Notes |
|---|---|---|---|
email | string | Optional: bind invite to this email (case-insensitive match on register). | |
expires_in_days | integer (int32) | Days until expiry (default 7, clamp 1..=90). |
CreateSocialComment
| Field | Type | Required | Notes |
|---|---|---|---|
body | string | yes |
CreateVaultRequest
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
passphrase | string | yes |
DashboardItemView
| Field | Type | Required | Notes |
|---|---|---|---|
bookmark | BookmarkView | yes | |
id | string (uuid) | yes | |
last_opened_at | string (date-time) | When the viewer last opened it. | |
open_count | integer (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. | |
position | integer (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.
| Field | Type | Required | Notes |
|---|---|---|---|
h | integer (int32) | yes | |
w | integer (int32) | yes | |
x | integer (int32) | yes | |
y | integer (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.
| Field | Type | Required | Notes |
|---|---|---|---|
display | DashboardSectionDisplay | ||
item_limit | integer (int32) | ||
kind | DashboardSectionKind | ||
layout | DashboardSectionLayout | ||
open_window | DashboardOpenWindow | ||
source | DashboardSectionSource |
DashboardSectionSource
Filters for a section that fills itself. A bookmark must match every one that is set.
| Field | Type | Required | Notes |
|---|---|---|---|
category_id | string (uuid) | A folder of the owner's, with its subfolders. | |
favorites | boolean | ||
site | string | A website, such as github.com; its subdomains match too. | |
tag | string | ||
unread | boolean |
DashboardSectionView
Type: DashboardSectionSettings & object
DashboardShareView
| Field | Type | Required | Notes |
|---|---|---|---|
access | ShareAccess | yes | |
created_at | string (date-time) | yes | |
dashboard_id | string (uuid) | yes | |
id | string (uuid) | yes | |
invited_by_user_id | string (uuid) | yes | |
invitee_display_name | string | ||
invitee_email | string | yes | |
invitee_user_id | string (uuid) | yes | |
updated_at | string (date-time) | yes |
DashboardSharesEnvelope
| Field | Type | Required | Notes |
|---|---|---|---|
pending | PendingShareInviteView[] | yes | |
shares | DashboardShareView[] | yes |
DashboardSummary
Lightweight row for switchers / settings (no sections).
| Field | Type | Required | Notes |
|---|---|---|---|
access | CategoryAccess | yes | |
created_at | string (date-time) | yes | |
deleted_at | string (date-time) | ||
id | string (uuid) | yes | |
is_default | boolean | yes | |
owner_display_name | string | ||
owner_user_id | string (uuid) | yes | |
shared_out | boolean | ||
shared_with | string[] | ||
title | string | yes | |
updated_at | string (date-time) | yes |
DashboardView
| Field | Type | Required | Notes |
|---|---|---|---|
access | CategoryAccess | yes | |
created_at | string (date-time) | yes | |
deleted_at | string (date-time) | ||
id | string (uuid) | yes | |
is_default | boolean | yes | |
owner_display_name | string | ||
owner_user_id | string (uuid) | yes | |
sections | DashboardSectionView[] | yes | |
shared_out | boolean | True when the owner has shared this dashboard with someone. | |
shared_with | string[] | Owner-only: invitee display labels for the outgoing share pill tooltip. | |
title | string | yes | |
updated_at | string (date-time) | yes |
DeleteVaultRequest
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
password | string |
DisconnectRequest
| Field | Type | Required | Notes |
|---|---|---|---|
password | string | yes |
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.
| Field | Type | Required | Notes |
|---|---|---|---|
default | DuplicateAction | ||
overrides | map of DuplicateAction |
DuplicateExisting
| Field | Type | Required | Notes |
|---|---|---|---|
description | string | ||
folders | string[] | yes | Full paths, Work / Rust. |
id | string (uuid) | yes | |
tags | string[] | yes | |
title | string | yes | |
updated_at | string (date-time) | yes |
DuplicateIncoming
| Field | Type | Required | Notes |
|---|---|---|---|
description | string | ||
folders | string[] | yes | |
tags | string[] | yes | |
title | string |
EmailDelivery
How a notification kind's email arrives.
Type: instant, daily
ErrorBody
The error body. See the module docs.
| Field | Type | Required | Notes |
|---|---|---|---|
code | string | yes | Stable machine-readable id, such as not_found or quota_exceeded. |
details | object | Extra data for some codes: ban for banned, meter/limit/used for quota_exceeded, blockers for vault_move_blocked. | |
error | string | yes | Same as message. Kept for older clients. |
message | string | yes | Human-readable text. Wording may change between releases; match on code. |
FilingSuggestions
| Field | Type | Required | Notes |
|---|---|---|---|
folders | FolderSuggestion[] | yes | |
tags | TagSuggestion[] | yes |
FolderCounts
Live bookmarks per folder the person can open, and in their Unsorted.
| Field | Type | Required | Notes |
|---|---|---|---|
folders | map of integer (int64) | yes | Direct bookmarks per folder (not counting subfolders). Folders with none are absent. |
uncategorized | integer (int64) | yes |
FolderSuggestion
| Field | Type | Required | Notes |
|---|---|---|---|
count | integer (int64) | yes | Bookmarks on the same site in this folder. |
id | string (uuid) | yes |
FollowRelation
| Field | Type | Required | Notes |
|---|---|---|---|
followers | integer (int64) | yes | |
following | boolean | yes | |
following_count | integer (int64) | yes |
ForgotRequest
| Field | Type | Required | Notes |
|---|---|---|---|
email | string | yes |
ForkCategory
Copy a readable category tree (+ bookmarks) into a new owned root.
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Defaults to {name} (copy). |
ImportBody
| Field | Type | Required | Notes |
|---|---|---|---|
content | string | yes | |
duplicates | DuplicateDecisions | What to do with bookmarks already in the library. Missing: create them all, as before. | |
format | string | yes |
ImportDuplicate
| Field | Type | Required | Notes |
|---|---|---|---|
existing | DuplicateExisting | yes | |
incoming | DuplicateIncoming | yes | |
index | integer | yes | |
url | string | yes |
ImportFolderCounts
| Field | Type | Required | Notes |
|---|---|---|---|
created | integer | yes | |
reused | integer | yes |
ImportPreview
| Field | Type | Required | Notes |
|---|---|---|---|
duplicates | ImportDuplicate[] | yes | |
folders | ImportFolderCounts | yes | |
new | integer | yes | |
total | integer | yes |
LiftBans
| Field | Type | Required | Notes |
|---|---|---|---|
user_ids | string (uuid)[] | yes |
LinkCheckStatus
Last probe result from the broken-link checker worker.
Type: ok, broken, unreachable, unverifiable
LoginFinish
| Field | Type | Required | Notes |
|---|---|---|---|
challenge_id | string (uuid) | yes | |
credential | object | yes | The browser's WebAuthn credential, as JSON. |
LoginRequest
| Field | Type | Required | Notes |
|---|---|---|---|
email | string | yes | |
password | string | yes |
ModerateAction
| Field | Type | Required | Notes |
|---|---|---|---|
action | string | yes | |
subject_id | string (uuid) | yes | |
subject_type | string | Needed for removed_to_trash and share_revoked. |
ModerateRequest
| Field | Type | Required | Notes |
|---|---|---|---|
actions | ModerateAction[] | yes | |
reason | string | yes |
MoveToVaultRequest
| Field | Type | Required | Notes |
|---|---|---|---|
bookmark_ids | string (uuid)[] | ||
category_ids | string (uuid)[] | ||
destination_vault_id | string (uuid) |
PageDetailsRequest
| Field | Type | Required | Notes |
|---|---|---|---|
url | string | yes |
PatchDashboard
Rename and/or pin. Pinning a shared dashboard needs read access and only affects the caller.
| Field | Type | Required | Notes |
|---|---|---|---|
is_default | boolean | ||
title | string |
PendingShareInviteView
| Field | Type | Required | Notes |
|---|---|---|---|
access | ShareAccess | yes | |
claim_token | string | Single-use claim link token. Only present in the response that created it. | |
created_at | string (date-time) | yes | |
id | string (uuid) | yes | |
invited_by_user_id | string (uuid) | yes | |
invitee_email | string | yes | |
subject_id | string (uuid) | yes | |
subject_type | PendingShareSubjectType | yes | |
updated_at | string (date-time) | yes |
PendingShareSubjectType
Subject for a pending (pre-account) share invite.
Type: category, dashboard
ProfileBookmarksPage
| Field | Type | Required | Notes |
|---|---|---|---|
bookmarks | PublicBookmarkView[] | yes | |
total | integer (int64) | yes |
ProfileView
A user's profile as another signed-in user sees it.
| Field | Type | Required | Notes |
|---|---|---|---|
bio | string | ||
display_name | string | yes | |
email | string | Self only. | |
follow | FollowRelation | yes | |
has_avatar | boolean | yes | |
id | string (uuid) | yes | |
is_self | boolean | yes | |
profile_visibility | string | Self 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).
| Field | Type | Required | Notes |
|---|---|---|---|
description | string | ||
favicon_url | string | ||
has_preview | boolean | yes | |
id | string (uuid) | yes | |
preview_image_url | string | ||
preview_url | string | Where anyone may load the stored preview, when has_preview and the caller is anonymous. Set on public lists. | |
tags | string[] | yes | |
title | string | yes | |
url | string | yes |
PublicListView
Anonymous read model for a published bookmark list.
| Field | Type | Required | Notes |
|---|---|---|---|
bookmarks | PublicBookmarkView[] | yes | The newest bookmarks, at most PUBLIC_LIST_LIMIT of them. |
icon | string | ||
name | string | yes | |
owner_display_name | string | yes | |
total | integer (int64) | How many bookmarks the list holds, including any left out of bookmarks. |
PurgeTrashRequest
| Field | Type | Required | Notes |
|---|---|---|---|
items | TrashItemRef[] | yes |
PutDashboardLayout
Full layout replace for a personal dashboard.
| Field | Type | Required | Notes |
|---|---|---|---|
sections | PutDashboardSection[] | yes | |
title | string |
PutDashboardSection
Type: DashboardSectionSettings & object
RecoverVaultRequest
| Field | Type | Required | Notes |
|---|---|---|---|
new_passphrase | string | yes | |
recovery_key | string | yes |
RegisterFinish
| Field | Type | Required | Notes |
|---|---|---|---|
challenge_id | string (uuid) | yes | |
credential | object | yes | The browser's WebAuthn credential, as JSON. |
name | string | yes |
RegisterRequest
| Field | Type | Required | Notes |
|---|---|---|---|
bootstrap_token | string | The server's BOOTSTRAP_TOKEN, needed for the first account when one is set. | |
display_name | string | ||
email | string | yes | |
invite_code | string | Required when registration is closed (after bootstrap). | |
password | string | yes | |
share_token | string | From a share invite's claim link. | |
terms_version | string | Terms of Service version the user accepted; must equal legal::TERMS_VERSION. | |
turnstile_token | string | Cloudflare Turnstile widget token; required when the server has Turnstile keys. |
RegisterStart
| Field | Type | Required | Notes |
|---|---|---|---|
password | string | Required when the account has a password. |
Rename
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes |
RenameVaultRequest
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes |
ResetRequest
| Field | Type | Required | Notes |
|---|---|---|---|
password | string | yes | |
revoke_api_keys | boolean | ||
token | string | yes |
ResolveAbuseReport
| Field | Type | Required | Notes |
|---|---|---|---|
action | AbuseAction | yes | |
note | string |
ScheduleAccountDeletion
Body of POST /users/me/deletion.
| Field | Type | Required | Notes |
|---|---|---|---|
confirm_email | string | yes | Must match the account email (case-insensitive). |
password | string | Required for accounts with a local password; ignored for single sign-on only accounts. |
SetEmailVerified
| Field | Type | Required | Notes |
|---|---|---|---|
verified | boolean | yes |
SetNotificationEmail
| Field | Type | Required | Notes |
|---|---|---|---|
delivery | EmailDelivery | ||
enabled | boolean | yes |
ShareAccess
Membership grant on a shared category (read / write only).
Type: read, write
Tag
| Field | Type | Required | Notes |
|---|---|---|---|
created_at | string (date-time) | yes | |
id | string (uuid) | yes | |
name | string | yes | |
owner_user_id | string (uuid) | yes |
TagSuggestion
| Field | Type | Required | Notes |
|---|---|---|---|
count | integer (int64) | yes | |
name | string | yes |
TokenRequest
| Field | Type | Required | Notes |
|---|---|---|---|
code | string | yes | |
code_verifier | string | yes | |
extension_origin | string | yes |
TrashItem
| Field | Type | Required | Notes |
|---|---|---|---|
deleted_at | string (date-time) | yes | |
id | string (uuid) | yes | |
kind | TrashKind | yes | |
title | string | yes |
TrashItemRef
| Field | Type | Required | Notes |
|---|---|---|---|
id | string (uuid) | yes | |
kind | TrashKind | yes |
TrashKind
Type: bookmark, category, dashboard
UpdateAdminUser
| Field | Type | Required | Notes |
|---|---|---|---|
api_keys_enabled | boolean | ||
is_admin | boolean |
UpdateBookmark
| Field | Type | Required | Notes |
|---|---|---|---|
add_category_ids | string (uuid)[] | Folders to add the bookmark to, alongside the ones it is in when the edit is saved. | |
add_tags | string[] | Tags to add to whatever the bookmark has when the edit is saved. | |
category_id | string (uuid) | ||
category_ids | string (uuid)[] | ||
description | string | ||
is_favorite | boolean | ||
is_pinned | boolean | ||
is_private | boolean | ||
is_unread | boolean | ||
notes | string | ||
tags | string[] | ||
title | string | ||
url | string |
UpdateCategory
| Field | Type | Required | Notes |
|---|---|---|---|
icon | string | Some(None) clears the icon; Some(Some(key)) sets it. | |
is_hidden | boolean | ||
name | string | ||
parent_id | string (uuid) | ||
position | integer (int32) | ||
visibility | CategoryVisibility |
UpdateCategoryShare
| Field | Type | Required | Notes |
|---|---|---|---|
access | ShareAccess | yes |
UpdateDashboardShare
| Field | Type | Required | Notes |
|---|---|---|---|
access | ShareAccess | yes |
UpdatePendingShareInvite
| Field | Type | Required | Notes |
|---|---|---|---|
access | ShareAccess | yes |
UpdatePlatformSettings
| Field | Type | Required | Notes |
|---|---|---|---|
abuse_contact_email | string | Some(None) clears; Some(Some(email)) sets; omit = no change. | |
api_keys_enabled | boolean | ||
max_bookmarks | integer (int64) | Some(None) clears; Some(Some(n)) sets; omit = no change. | |
max_enrich_actions_per_day | integer (int64) | ||
max_import_bytes | integer (int64) | ||
max_stored_image_bytes | integer (int64) | ||
max_upload_image_bytes | integer (int64) | ||
registration_open | boolean | ||
require_verified_email | boolean | ||
screenshot_auto_retry_days | integer (int32) | 1 to 90. | |
screenshot_retry_cooldown_hours | integer (int32) | 1 to 720. |
UpdateProfile
| Field | Type | Required | Notes |
|---|---|---|---|
bio | string | ||
display_name | string | ||
email | string | Accepted only when it matches the current address. An address changes through an emailed confirmation link, or by an instance admin. | |
profile_visibility | ProfileVisibility | ||
timezone | string |
UpdateSettings
| Field | Type | Required | Notes |
|---|---|---|---|
default_landing | string | ||
library_view | string | ||
show_deleted_in_library | boolean | ||
show_hidden | boolean | ||
show_keyboard_hints | boolean | Hide key numbers, key hint lines and shortcut keycaps. Missing means unchanged. | |
show_vault_in_library | boolean | ||
theme | string | ||
trash_retention_days | integer (int32) | ||
vault_auto_lock_minutes | integer (int32) | ||
vault_delete_mode | string | ||
vault_search_mode | string |
UpsertSocialRating
| Field | Type | Required | Notes |
|---|---|---|---|
rating | integer (int32) | yes |
VaultUnlockRequest
| Field | Type | Required | Notes |
|---|---|---|---|
passphrase | string | yes |