{"openapi":"3.1.0","info":{"title":"LinkArena API","version":"1.0.0","description":"REST API for LinkArena web, mobile, and extension clients."},"servers":[{"url":"/"}],"tags":[{"name":"Mobile Auth"},{"name":"Bookmarks"},{"name":"Sync"},{"name":"Realtime"},{"name":"Public Mobile"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Token"}}},"paths":{"/api/mobile/auth/login":{"post":{"tags":["Mobile Auth"],"summary":"Login and receive a bearer token","responses":{"200":{"description":"Authenticated"},"401":{"description":"Invalid credentials"},"403":{"description":"Email verification required (code: EMAIL_NOT_VERIFIED) or account suspended"}}}},"/api/mobile/auth/exchange":{"post":{"tags":["Mobile Auth"],"summary":"Redeem a one-time browser sign-in code ({ code, verifier }, PKCE S256) from /mobile/auth for a bearer token","responses":{"200":{"description":"Authenticated"},"400":{"description":"Invalid JSON"},"401":{"description":"Code unknown, expired, already used, wrong verifier, or session revoked"},"429":{"description":"Rate limited"}}}},"/api/mobile/auth/signup":{"post":{"tags":["Mobile Auth"],"summary":"Create an inactive account and send an email verification code","responses":{"201":{"description":"Account created; no bearer token until verification and login","content":{"application/json":{"schema":{"type":"object","required":["email","verificationRequired","emailSent","message"],"properties":{"email":{"type":"string","format":"email"},"verificationRequired":{"type":"boolean","const":true},"emailSent":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input or account already exists"},"403":{"description":"Signup disabled"},"429":{"description":"Too many requests"}}}},"/api/mobile/auth/verify-email":{"post":{"tags":["Mobile Auth"],"summary":"Activate an account using its emailed six-digit code and its password; login afterwards","description":"Requires the password chosen at signup as well as the code, so someone who only controls the inbox cannot activate a password another person chose. A wrong code or password returns the same error and counts toward the five-attempt limit. Users who don't know the password should use the forgot-password flow, which also verifies the email.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","code","password"],"properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","pattern":"^[0-9]{6}$"},"password":{"type":"string","minLength":1,"maxLength":128}}}}}},"responses":{"200":{"description":"Email verified; account active"},"400":{"description":"Missing fields, wrong code or password, or an expired, used, or locked code"},"429":{"description":"Too many attempts"}}}},"/api/mobile/auth/resend-verification":{"post":{"tags":["Mobile Auth"],"summary":"Send a new verification code if the account needs verification","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Request accepted"},"400":{"description":"Invalid input, cooldown, hourly limit, or delivery failure"},"429":{"description":"Too many requests"}}}},"/api/mobile/auth/forgot-password":{"post":{"tags":["Mobile Auth"],"summary":"Email a six-digit password reset code (valid 10 minutes); ok for unknown emails","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Request accepted"},"400":{"description":"Invalid input or delivery failure"},"429":{"description":"Too many requests"}}}},"/api/mobile/auth/verify-reset-code":{"post":{"tags":["Mobile Auth"],"summary":"Check a password reset code without consuming it","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","code"],"properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","pattern":"^[0-9]{6}$"}}}}}},"responses":{"200":{"description":"Code is valid"},"400":{"description":"Invalid, expired, or locked code"},"429":{"description":"Too many attempts"}}}},"/api/mobile/auth/reset-password":{"post":{"tags":["Mobile Auth"],"summary":"Set a new password using the emailed reset code; also verifies the email","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","code","newPassword"],"properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","pattern":"^[0-9]{6}$"},"newPassword":{"type":"string","minLength":8}}}}}},"responses":{"200":{"description":"Password updated"},"400":{"description":"Weak password or invalid, expired, or locked code"},"429":{"description":"Too many attempts"}}}},"/api/bookmarks":{"post":{"tags":["Bookmarks"],"summary":"Create bookmark","security":[{"BearerAuth":[]}],"responses":{"201":{"description":"Created"},"429":{"description":"Quota exceeded"}}},"put":{"tags":["Bookmarks"],"summary":"Update bookmark by URL","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Updated"},"404":{"description":"Not found"}}},"delete":{"tags":["Bookmarks"],"summary":"Delete bookmark by URL","security":[{"BearerAuth":[]}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found"}}}},"/api/bookmarks/{bookmarkId}":{"patch":{"tags":["Bookmarks"],"summary":"Favorite, read later, archive or set tags","description":"Only the fields sent change. `tags` replaces the bookmark's tag list (at most 20 names of up to 32 characters; [] removes all). Not counted against the monthly quota; limited per account instead.","security":[{"BearerAuth":[]}],"parameters":[{"name":"bookmarkId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"isFavorite":{"type":"boolean"},"readLater":{"type":"boolean","description":"true puts it on the reading list; false marks it as read."},"archived":{"type":"boolean","description":"true archives it; false restores it."},"tags":{"type":"array","items":{"type":"string"},"maxItems":20}}}}}},"responses":{"200":{"description":"The updated bookmark, including isFavorite, readLaterAt, archivedAt and tags"},"400":{"description":"Invalid body or too many tags"},"404":{"description":"Not found"},"429":{"description":"Too many changes; see Retry-After"}}},"delete":{"tags":["Bookmarks"],"summary":"Delete bookmark by id","security":[{"BearerAuth":[]}],"parameters":[{"name":"bookmarkId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found"}}}},"/api/sync":{"get":{"tags":["Sync"],"summary":"Sync bookmarks and groups","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Synced"},"429":{"description":"Quota exceeded"}}}},"/api/realtime/bookmarks":{"get":{"tags":["Realtime"],"summary":"SSE stream for bookmark updates","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"SSE stream opened"}}}},"/api/mobile/ads":{"get":{"tags":["Public Mobile"],"summary":"Get mobile ads configuration","responses":{"200":{"description":"Ads config"}}}}}}