{"openapi":"3.1.0","info":{"title":"newdivine","description":"","license":{"name":""},"version":"0.0.1"},"paths":{"/auth/login":{"post":{"tags":["auth"],"summary":"Unknown login handle, unregistered identity, and wrong password all\nget the same 401 — the endpoint must not be an oracle for which part\nfailed (US-10). An all-digit `login` resolves as `public_id`\n(pre-login-name accounts); anything else as `login_name` ci.","operationId":"login","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Logged in; new session token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/auth/logout":{"post":{"tags":["auth"],"summary":"Revokes exactly the calling session. A legacy `identity.id` bearer\nisn't a session — revoking it is a no-op, the client just forgets it.","operationId":"logout","responses":{"204":{"description":"Session revoked (no-op for legacy bearers)"},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]}},"/auth/register":{"post":{"tags":["auth"],"summary":"Optional bearer (US-9): with a valid guest/known bearer the current\nidentity is claimed — same public_id, past messages stay attributed,\nthe nickname locks in (`known`). Without one a fresh registered\nidentity is created. `Identity` extractor can't express \"optional\",\nso the header is read directly.","operationId":"register","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"201":{"description":"Registered; session token issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"Password too short or bad nickname","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid bearer on the upgrade path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Identity already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]}},"/circles":{"get":{"tags":["circles"],"operationId":"list_circles","parameters":[{"name":"lat","in":"path","required":true,"schema":{"type":"number","format":"double"}},{"name":"lng","in":"path","required":true,"schema":{"type":"number","format":"double"}}],"responses":{"200":{"description":"Visible circles for the position","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VisibleCircleDto"}}}}},"400":{"description":"Invalid coordinates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]},"post":{"tags":["circles"],"operationId":"create_circle","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCircleRequest"}}},"required":true},"responses":{"201":{"description":"Circle created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CircleDto"}}}},"400":{"description":"Invalid circle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]}},"/circles/{id}/messages":{"get":{"tags":["messages"],"operationId":"list_messages","parameters":[{"name":"id","in":"path","description":"Circle ID","required":true,"schema":{"type":"string"}},{"name":"lat","in":"path","required":true,"schema":{"type":"number","format":"double"}},{"name":"lng","in":"path","required":true,"schema":{"type":"number","format":"double"}},{"name":"before","in":"path","required":true,"schema":{"type":["integer","null"],"format":"int64"}},{"name":"limit","in":"path","required":true,"schema":{"type":["integer","null"],"format":"int64"}}],"responses":{"200":{"description":"Message page, oldest to newest","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MessageDto"}}}}},"400":{"description":"Invalid coordinates or pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"No geo access to this circle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Circle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]},"post":{"tags":["messages"],"operationId":"create_message","parameters":[{"name":"id","in":"path","description":"Circle ID","required":true,"schema":{"type":"string"}},{"name":"lat","in":"path","required":true,"schema":{"type":"number","format":"double"}},{"name":"lng","in":"path","required":true,"schema":{"type":"number","format":"double"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMessageRequest"}}},"required":true},"responses":{"201":{"description":"Message created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDto"}}}},"400":{"description":"Invalid body or coordinates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"No geo access to this circle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Circle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]}},"/config":{"get":{"tags":["config"],"operationId":"get_config","responses":{"200":{"description":"Instance config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigDto"}}}}}}},"/identity":{"post":{"tags":["identity"],"operationId":"create_identity","responses":{"201":{"description":"New persona created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentityResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/me":{"get":{"tags":["identity"],"operationId":"get_me","responses":{"200":{"description":"Current persona","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentityResponse"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]},"delete":{"tags":["auth"],"summary":"`DELETE /me` (US-11/US-12): erase the calling identity in one\ntransaction. Registered identities must re-enter their password —\na stolen session must not be able to erase the account; the 401\nmessage matches login's so it's no oracle. Unregistered identities\nhave nothing to verify — the bearer alone deletes them (kills the\nabandoned credential, prunes their empty rooms).","operationId":"delete_me","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteRequest"}}},"required":true},"responses":{"204":{"description":"Identity erased — sessions, credential, empty owned rooms"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing/invalid bearer or wrong password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]},"patch":{"tags":["identity"],"operationId":"update_me","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMeRequest"}}},"required":true},"responses":{"200":{"description":"Nickname updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentityResponse"}}}},"400":{"description":"Invalid nickname","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]}},"/qr.svg":{"get":{"tags":["share"],"summary":"QR SVG for an arbitrary absolute http(s) URL — used for share\ntargets that have no `/r/{key}` (e.g. the board list itself).","operationId":"generic_qr","parameters":[{"name":"url","in":"query","description":"Absolute http(s) URL to encode","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"QR code SVG encoding the given URL","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"description":"Missing, malformed, or non-http(s) URL"}}}},"/r/{key}":{"get":{"tags":["share"],"operationId":"share_redirect","parameters":[{"name":"key","in":"path","description":"Room share key","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the canonical room destination (web app room, or share page when PUBLIC_WEB_URL is unset)"},"404":{"description":"Unknown share key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/r/{key}/qr.svg":{"get":{"tags":["share"],"operationId":"share_qr","parameters":[{"name":"key","in":"path","description":"Room share key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"QR code SVG encoding the absolute share URL","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"Unknown share key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/r/{key}/share":{"get":{"tags":["share"],"operationId":"share_page","parameters":[{"name":"key","in":"path","description":"Room share key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Printable share page (HTML) with QR code and link","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Unknown share key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/rooms":{"get":{"tags":["rooms"],"operationId":"list_rooms","parameters":[{"name":"parent","in":"path","description":"Parent room id; absent lists boards (depth 0).","required":true,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"Child rooms; no parent param lists boards","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RoomDto"}}}}},"400":{"description":"Invalid parent id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Parent room not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]},"post":{"tags":["rooms"],"operationId":"create_room","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRoomRequest"}}},"required":true},"responses":{"201":{"description":"Room created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomDto"}}}},"400":{"description":"Invalid title, parent, or max depth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Board creation requires a known identity, or parent is full (MAX_CHILDREN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Parent room not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]}},"/rooms/{id}":{"get":{"tags":["rooms"],"operationId":"get_room","parameters":[{"name":"id","in":"path","description":"Room ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Room with ancestor chain for breadcrumbs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomDetailDto"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Room not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]}},"/rooms/{id}/messages":{"get":{"tags":["rooms"],"operationId":"list_room_messages","parameters":[{"name":"id","in":"path","description":"Room ID","required":true,"schema":{"type":"string"}},{"name":"before","in":"path","required":true,"schema":{"type":["integer","null"],"format":"int64"}},{"name":"limit","in":"path","required":true,"schema":{"type":["integer","null"],"format":"int64"}}],"responses":{"200":{"description":"Message page, oldest to newest","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RoomMessageDto"}}}}},"400":{"description":"Invalid pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Room not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]},"post":{"tags":["rooms"],"operationId":"create_room_message","parameters":[{"name":"id","in":"path","description":"Room ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMessageRequest"}}},"required":true},"responses":{"201":{"description":"Message created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomMessageDto"}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Room not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer_auth":[]}]}},"/share":{"get":{"tags":["share"],"summary":"Printable share page for an arbitrary absolute http(s) URL — the\ngeneric counterpart of `/r/{key}/share` for targets without a room\nkey (e.g. the app root / board list). No open button — same as the\nroom page without PUBLIC_WEB_URL; title falls back to the URL.","operationId":"generic_share_page","parameters":[{"name":"url","in":"query","description":"Absolute http(s) URL the QR encodes","required":true,"schema":{"type":"string"}},{"name":"title","in":"query","description":"Display title (≤100 chars)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Printable share page (HTML) with QR code and link","content":{"text/html":{"schema":{"type":"string"}}}},"400":{"description":"Missing, malformed, or non-http(s) URL"}}}}},"components":{"schemas":{"AuthResponse":{"type":"object","required":["session_token","identity"],"properties":{"identity":{"$ref":"#/components/schemas/IdentityResponse"},"session_token":{"type":"string","description":"New session token: the bearer credential for all later requests."}}},"AuthorState":{"type":"string","description":"Live author state (spec 013 FR-20) — derived from the join, never\na stored snapshot: registered authors show nickname + public_id,\nguests render \"Unknown\" with no handle, erased authors \"deleted\".","enum":["known","unknown","deleted"]},"CircleDto":{"type":"object","required":["id","title","lat","lng","radius_m","retention"],"properties":{"id":{"type":"string"},"lat":{"type":"number","format":"double"},"lng":{"type":"number","format":"double"},"radius_m":{"type":"integer","format":"int32"},"retention":{"$ref":"#/components/schemas/Retention"},"title":{"type":"string"}}},"CircleQuery":{"type":"object","required":["lat","lng"],"properties":{"lat":{"type":"number","format":"double"},"lng":{"type":"number","format":"double"}}},"ConfigDto":{"type":"object","description":"Instance config for clients (spec 014 FR-23). Public, no auth, no\nDB — same sensitivity class as `/health`: the brand is displayed\non every public page anyway.","properties":{"brand":{"type":["string","null"],"description":"Instance brand (BRAND_NAME) — null when unbranded; clients fall\nback to \"Unknown\" (guest label) / \"NewDivine\" (title)."}}},"CreateCircleRequest":{"type":"object","required":["title","lat","lng","radius_m","retention"],"properties":{"lat":{"type":"number","format":"double"},"lng":{"type":"number","format":"double"},"radius_m":{"type":"integer","format":"int32"},"retention":{"$ref":"#/components/schemas/Retention"},"title":{"type":"string"}}},"CreateMessageRequest":{"type":"object","required":["body"],"properties":{"body":{"type":"string"}}},"CreateRoomRequest":{"type":"object","required":["title"],"properties":{"parent_id":{"type":["string","null"],"description":"Absent = create a board (depth 0, known identity required)."},"title":{"type":"string"}}},"DeleteRequest":{"type":"object","description":"`DELETE /me` (spec 013 FR-15): registered identities must prove\nthe account is really theirs — a stolen session can't erase it.\nUnregistered identities have no password to check; they send\n`{\"password\": null}` or an empty object and the bearer alone\nauthorizes deletion.","properties":{"password":{"type":["string","null"]}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"IdentityResponse":{"type":"object","required":["id","nickname","known","registered"],"properties":{"id":{"type":"string"},"known":{"type":"boolean","description":"Locked-in flag (v1 FR-4): false = displays as \"Unknown\"."},"login_name":{"type":["string","null"],"description":"FR-13: the chosen login handle. Owner-only — this DTO is never\nsent for other users' identities."},"nickname":{"type":"string"},"public_id":{"type":["integer","null"],"format":"int64","description":"Human-readable random number (`#482917350`) safe to display —\nnever a credential. Registered only (slice 013): null for\nguests, who hold no public handle."},"registered":{"type":"boolean","description":"FR-13: has an account password → login name + password logs in."}}},"LoginRequest":{"type":"object","required":["login","password"],"properties":{"login":{"type":"string","description":"Login name — or the identity's human-readable number\n(`#482917350`, digits only), kept working for pre-login-name\naccounts."},"password":{"type":"string","description":"The password chosen at registration; hyphens optional."}}},"MessageAuthorDto":{"type":"object","required":["public_id","nickname"],"properties":{"nickname":{"type":"string"},"public_id":{"type":"integer","format":"int64"}}},"MessageDto":{"type":"object","required":["id","author_name","body","created_at"],"properties":{"author_name":{"type":"string"},"body":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":["string","null"]},"id":{"type":"integer","format":"int64"}}},"RegisterRequest":{"type":"object","required":["login_name","password"],"properties":{"login_name":{"type":"string","description":"Login handle the user chose — free-form, unique\ncase-insensitively; an email works but is never verified.\n1–64 chars, not all digits (those resolve as public_id)."},"nickname":{"type":["string","null"],"description":"Optional display-name override; absent keeps the generated\nnickname. Either way registration sets `known`."},"password":{"type":"string","description":"User-chosen password — min 8 chars (hyphens stripped)."}}},"Relation":{"type":"string","enum":["inside","linked"]},"Retention":{"type":"string","enum":["ephemeral","persistent"]},"RoomDetailDto":{"type":"object","required":["id","title","depth","share_url","ancestors"],"properties":{"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/RoomDto"},"description":"Ancestor chain, root first — for breadcrumbs."},"depth":{"type":"integer","format":"int32"},"id":{"type":"string"},"parent_id":{"type":["string","null"]},"share_url":{"type":"string","description":"Absolute public share URL — same as `RoomDto.share_url`."},"title":{"type":"string"}}},"RoomDto":{"type":"object","required":["id","title","depth","share_url"],"properties":{"depth":{"type":"integer","format":"int32"},"id":{"type":"string"},"parent_id":{"type":["string","null"]},"share_url":{"type":"string","description":"Absolute public share URL (`{origin}/r/{share_key}`) — stable,\nprintable, works for anonymous recipients (spec FR-11)."},"title":{"type":"string"}}},"RoomMessageDto":{"type":"object","required":["id","author_state","is_mine","body","created_at"],"properties":{"author":{"oneOf":[{"$ref":"#/components/schemas/MessageAuthorDto"},{"type":"null"}]},"author_state":{"$ref":"#/components/schemas/AuthorState","description":"`known` → `author` present · `unknown` → live guest, no handle ·\n`deleted` → the author's identity was erased."},"body":{"type":"string"},"created_at":{"type":"string"},"id":{"type":"integer","format":"int64"},"is_mine":{"type":"boolean","description":"True when the caller authored this message. REST computes it;\nWS broadcasts always send false (one event, many recipients)."}}},"RoomMessageQuery":{"type":"object","properties":{"before":{"type":["integer","null"],"format":"int64"},"limit":{"type":["integer","null"],"format":"int64"}}},"RoomQuery":{"type":"object","properties":{"parent":{"type":["string","null"],"description":"Parent room id; absent lists boards (depth 0)."}}},"UpdateMeRequest":{"type":"object","required":["nickname"],"properties":{"nickname":{"type":"string"}}},"VisibleCircleDto":{"type":"object","required":["id","title","lat","lng","radius_m","retention","relation"],"properties":{"id":{"type":"string"},"lat":{"type":"number","format":"double"},"lng":{"type":"number","format":"double"},"radius_m":{"type":"integer","format":"int32"},"relation":{"$ref":"#/components/schemas/Relation"},"retention":{"$ref":"#/components/schemas/Retention"},"title":{"type":"string"}}}},"securitySchemes":{"bearer_auth":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"identity","description":"Persona identity and nickname"},{"name":"auth","description":"Account registration, login, sessions"},{"name":"circles","description":"Geo-visible circles"},{"name":"messages","description":"Circle messages"},{"name":"rooms","description":"v1 chat rooms and messages"},{"name":"share","description":"Public room share links and QR codes"},{"name":"config","description":"Instance config for clients"}]}