{"openapi":"3.1.0","info":{"title":"uscode-redesign","summary":"Versioned US Code retrieval: any provision, at any release point.","description":"\nAny provision of the US Code, at any release point, addressed by a URL that mirrors\nthe USLM `@identifier`.\n\n* `/api/v1/us/usc/t16/s45f/c/5?date=07/12/2026` — a provision, in the context of\n  its section, at the release point current on that date.\n* `/api/v1/us/usc/?id=id0b32dff7-810c-11f1-b7ce-bdea3d14cbdd` — the same provision\n  by its XML `@id`. A guid identifies (provision, release point), so no release\n  parameter is needed, and the link keeps meaning the same text forever.\n* `/api/v1/us/usc/t16/ch1` — a table of contents at a release point.\n\nThe bare citation URL — `/us/usc/t16/s45f/c/5` — is not documented here because it\nis not a machine route: it is a **307 redirect** to whichever surface the caller\ncan read (`/app` for HTML, `/api/v1` otherwise), so `curl` it with `-L` or address\n`/api/v1` directly. ADR-0010.\n\nRelease points are named for the last public law they incorporate, and `not` in a\nlabel means a law that was *skipped*: at `119-102not101` the text is current\nthrough 07/12/2026 **except** for Public Law 119-101. Responses carry that caveat\nrather than only a date.\n","version":"0.1.0"},"paths":{"/api/v1/releases":{"get":{"tags":["api"],"summary":"All release points","description":"Every known release point, newest first.\n\n`titles_affected` is what OLRC says the release point changed;\n`ingested_titles` is what this database actually holds for it. The two differ\nfor as long as the backfill is incomplete, and conflating them would make an\nempty answer look like a missing law — which is why they are two parameters\nand not one.","operationId":"list_releases_api_v1_releases_get","parameters":[{"name":"title","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only release points that changed this title.","title":"Title"},"description":"Only release points that changed this title."},{"name":"ingested_title","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only release points this database actually holds this title at — what a release picker can offer without offering empty answers.","title":"Ingested Title"},"description":"Only release points this database actually holds this title at — what a release picker can offer without offering empty answers."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseOut"},"title":"Response List Releases Api V1 Releases Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/status":{"get":{"tags":["api"],"summary":"How current this mirror is, and when it last checked","description":"What this deployment holds, and when it last asked OLRC what exists.\n\nA versioned mirror of a living source has two ways of being wrong and only\none of them is visible from the text: it can be missing a release point\nthat was published last week, or it can have stopped asking altogether. The\nsecond is the dangerous one, because a corpus that has quietly stopped\nupdating is indistinguishable from a corpus with nothing to update — every\npage still renders, every date still looks authoritative. So the answer\nhere is two facts side by side: the newest release point loaded, and the\ntimestamp of the last poll of uscode.house.gov.\n\nPolled daily; `stale` goes true after a week without a successful check\n(`storage.SOURCE_CHECK_STALE_AFTER`).","operationId":"status_api_v1_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusOut"}}}}}}},"/api/v1/titles":{"get":{"tags":["api"],"summary":"Ingested titles","description":"Every ingested title, in the Code's own order — `1, 2, … 5, 5a, 6, … 11,\n11a, 12, …` (ADR-0025). The ordering is the Repository's contract, not this\nhandler's, so the same list arrives sorted from any implementation.","operationId":"list_titles_api_v1_titles_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/TitleOut"},"type":"array","title":"Response List Titles Api V1 Titles Get"}}}}}}},"/api/v1/citation":{"get":{"tags":["api"],"summary":"A typed citation, resolved to an identifier","description":"`11 usc 523(a)(1)` → `/us/usc/t11/s523/a/1`, and whether it is there.\n\nParsing is `citeparse.parse_citation`, which is pure — it knows what string\na citation names and nothing about what exists. Existence is answered here,\nwith the batched `labels()` lookup already built for citation hover text, so\nthis costs one query and needs no new `Repository` method (architecture\nrule 1).\n\nA string that cannot be parsed is a 422: the request was malformed. A string\nthat parses but names nothing loaded is a **200 with `exists: false`** — it\nis a well-formed question with the answer \"not here\", and telling the reader\nwhich part was wrong beats an error page.","operationId":"citation_lookup_api_v1_citation_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","description":"A citation in more or less any written form.","examples":["11 usc 523(a)(1)","16 U.S.C. § 45f(c)(5)","5 USC App. 3"],"title":"Q"},"description":"A citation in more or less any written form."},{"name":"release","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Release-point label, e.g. `119-102not101`. A bare `119-102` resolves to it with a note.","examples":["119-102not101"],"title":"Release"},"description":"Release-point label, e.g. `119-102not101`. A bare `119-102` resolves to it with a note."},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Resolve to the newest release point on or before this date. `YYYY-MM-DD` or `MM/DD/YYYY`.","examples":["07/12/2026"],"title":"Date"},"description":"Resolve to the newest release point on or before this date. `YYYY-MM-DD` or `MM/DD/YYYY`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationOut"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}},"description":"Too Many Requests"}}}},"/api/v1/sections/{identifier}/neighbors":{"get":{"tags":["api"],"summary":"Previous and next section in reading order","description":"Reading order at one release point, skipping nothing: repealed, omitted and\ntransferred sections keep their place and arrive badged (gotcha 9).","operationId":"neighbors_api_v1_sections__identifier__neighbors_get","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}},{"name":"release","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Release-point label, e.g. `119-102not101`. A bare `119-102` resolves to it with a note.","examples":["119-102not101"],"title":"Release"},"description":"Release-point label, e.g. `119-102not101`. A bare `119-102` resolves to it with a note."},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Resolve to the newest release point on or before this date. `YYYY-MM-DD` or `MM/DD/YYYY`.","examples":["07/12/2026"],"title":"Date"},"description":"Resolve to the newest release point on or before this date. `YYYY-MM-DD` or `MM/DD/YYYY`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeighborsOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/labels":{"get":{"tags":["api"],"summary":"Num and heading for many identifiers at once","description":"What a list of citations *say*, in one request.\n\nA section's text can carry forty cross references, and a reader that labels\nthem — hover text, so a citation is legible without following it — has to ask\nonce, not forty times.","operationId":"labels_api_v1_labels_get","parameters":[{"name":"identifier","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Repeat once per identifier. Unknown ones are absent from the answer rather than an error.","examples":[["/us/usc/t16/s45f","/us/usc/t16/s1"]],"title":"Identifier"},"description":"Repeat once per identifier. Unknown ones are absent from the answer rather than an error."},{"name":"release","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Release-point label, e.g. `119-102not101`. A bare `119-102` resolves to it with a note.","examples":["119-102not101"],"title":"Release"},"description":"Release-point label, e.g. `119-102not101`. A bare `119-102` resolves to it with a note."},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Resolve to the newest release point on or before this date. `YYYY-MM-DD` or `MM/DD/YYYY`.","examples":["07/12/2026"],"title":"Date"},"description":"Resolve to the newest release point on or before this date. `YYYY-MM-DD` or `MM/DD/YYYY`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TocEntryOut"},"title":"Response Labels Api V1 Labels Get"}}}},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sections/{identifier}/versions":{"get":{"tags":["api"],"summary":"Release points at which a section changed","description":"The section's change timeline — one entry per distinct text, not one per\nrelease point, since most release points leave most sections untouched.","operationId":"versions_api_v1_sections__identifier__versions_get","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionsOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sections/{identifier}/diff":{"get":{"tags":["api"],"summary":"A redline between two release points of a section","description":"Diffs the two release points' verbatim XML (docs/adr/0016): a generic\ntext diff, computed here because it needs no USLM vocabulary at all —\npresentation (wrapping `ops` in `<ins>`/`<del>`) is `frontend/src/lib`'s\njob, same as the section renderer itself.","operationId":"diff_api_v1_sections__identifier__diff_get","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}},{"name":"from","in":"query","required":true,"schema":{"type":"string","description":"Release point label to diff from.","examples":["119-99"],"title":"From"},"description":"Release point label to diff from."},{"name":"to","in":"query","required":true,"schema":{"type":"string","description":"Release point label to diff to.","examples":["119-102not101"],"title":"To"},"description":"Release point label to diff to."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiffOut"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}},"description":"Not Found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/us/usc/":{"get":{"tags":["api","us code"],"summary":"Look a provision up by its XML @id","description":"No release parameter, by design: a guid identifies (provision, release point)\non its own, which makes it the stable citation for *this exact text at this\nexact moment* (ADR-0003).","operationId":"lookup_by_guid_api_v1_us_usc__get","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"An `@id` guid from the USLM, e.g. `id0b32dff7-810c-11f1-b7ce-bdea3d14cbdd`.","examples":["id0b32dff7-810c-11f1-b7ce-bdea3d14cbdd"],"title":"Id"},"description":"An `@id` guid from the USLM, e.g. `id0b32dff7-810c-11f1-b7ce-bdea3d14cbdd`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuidOut"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/us/usc/{identifier}":{"get":{"tags":["api","us code"],"summary":"A provision, section, or table-of-contents node by identifier","description":"Resolve a US Code identifier at a release point.\n\nLongest-prefix match means `/us/usc/t16/s45f/c/5` returns section 45f *with*\nparagraph (c)(5) extracted and anchored, rather than the paragraph alone —\nsub-section provisions are cut from the section at request time (ADR-0001), so\nthe reader never loses context.\n\nIf the identifier names no section, it is tried as a structural node, and a\ntable of contents comes back instead.","operationId":"get_by_identifier_api_v1_us_usc__identifier__get","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}},{"name":"release","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Release-point label, e.g. `119-102not101`. A bare `119-102` resolves to it with a note.","examples":["119-102not101"],"title":"Release"},"description":"Release-point label, e.g. `119-102not101`. A bare `119-102` resolves to it with a note."},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Resolve to the newest release point on or before this date. `YYYY-MM-DD` or `MM/DD/YYYY`.","examples":["07/12/2026"],"title":"Date"},"description":"Resolve to the newest release point on or before this date. `YYYY-MM-DD` or `MM/DD/YYYY`."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"enum":["json","xml","html"],"type":"string"},{"type":"null"}],"description":"Response format. Defaults to content negotiation on Accept.","title":"Format"},"description":"Response format. Defaults to content negotiation on Accept."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}},"application/xml":{}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}},"description":"Not Found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}},"description":"Conflict"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/signup":{"post":{"tags":["auth"],"summary":"Signup","operationId":"signup_api_v1_auth_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupIn"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/login":{"post":{"tags":["auth"],"summary":"Login","operationId":"login_api_v1_auth_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/logout":{"post":{"tags":["auth"],"summary":"Logout","operationId":"logout_api_v1_auth_logout_post","parameters":[{"name":"x-csrf-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Csrf-Token"}},{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/me":{"get":{"tags":["auth"],"summary":"Me","operationId":"me_api_v1_auth_me_get","parameters":[{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/watchlists":{"get":{"tags":["watchlists"],"summary":"List Watchlists","operationId":"list_watchlists_api_v1_watchlists_get","parameters":[{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WatchlistSummaryOut"},"title":"Response List Watchlists Api V1 Watchlists Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["watchlists"],"summary":"Create Watchlist","operationId":"create_watchlist_api_v1_watchlists_post","parameters":[{"name":"x-csrf-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Csrf-Token"}},{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistCreateIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistSummaryOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/watchlists/{watchlist_id}":{"delete":{"tags":["watchlists"],"summary":"Delete Watchlist","operationId":"delete_watchlist_api_v1_watchlists__watchlist_id__delete","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"integer","title":"Watchlist Id"}},{"name":"x-csrf-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Csrf-Token"}},{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/watchlists/{watchlist_id}/items":{"get":{"tags":["watchlists"],"summary":"List Items","operationId":"list_items_api_v1_watchlists__watchlist_id__items_get","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"integer","title":"Watchlist Id"}},{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["watchlists"],"summary":"Add Item","operationId":"add_item_api_v1_watchlists__watchlist_id__items_post","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"integer","title":"Watchlist Id"}},{"name":"x-csrf-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Csrf-Token"}},{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistItemCreateIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistItemOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/watchlists/{watchlist_id}/items/{item_id}":{"patch":{"tags":["watchlists"],"summary":"Update Item","operationId":"update_item_api_v1_watchlists__watchlist_id__items__item_id__patch","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"integer","title":"Watchlist Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"integer","title":"Item Id"}},{"name":"x-csrf-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Csrf-Token"}},{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistItemUpdateIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistItemOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["watchlists"],"summary":"Delete Item","operationId":"delete_item_api_v1_watchlists__watchlist_id__items__item_id__delete","parameters":[{"name":"watchlist_id","in":"path","required":true,"schema":{"type":"integer","title":"Watchlist Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"integer","title":"Item Id"}},{"name":"x-csrf-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Csrf-Token"}},{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/watchlist":{"get":{"tags":["watchlists"],"summary":"Get Default Watchlist","description":"\"My Provisions\": the current user's first watchlist, auto-created.","operationId":"get_default_watchlist_api_v1_watchlist_get","parameters":[{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/watchlist/items":{"post":{"tags":["watchlists"],"summary":"Add To Default Watchlist","operationId":"add_to_default_watchlist_api_v1_watchlist_items_post","parameters":[{"name":"x-csrf-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Csrf-Token"}},{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistItemCreateIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistItemOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/watchlist/items/{item_id}":{"delete":{"tags":["watchlists"],"summary":"Remove From Default Watchlist","operationId":"remove_from_default_watchlist_api_v1_watchlist_items__item_id__delete","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"integer","title":"Item Id"}},{"name":"x-csrf-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Csrf-Token"}},{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/settings":{"get":{"tags":["settings"],"summary":"Get Settings","description":"Defaults for a user who has never saved a preference — `get_settings`\ndoes not write, so reading this costs no row (storage/accounts.py).","operationId":"get_settings_api_v1_settings_get","parameters":[{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["settings"],"summary":"Update Settings","operationId":"update_settings_api_v1_settings_put","parameters":[{"name":"x-csrf-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Csrf-Token"}},{"name":"usc_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usc Session"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsUpdateIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/search":{"get":{"tags":["search"],"summary":"Search US Code sections and structure","operationId":"search_api_v1_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500,"description":"The keyword or phrase to search for.","title":"Q"},"description":"The keyword or phrase to search for."},{"name":"release","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Release-point label, e.g. `119-102not101`. A bare `119-102` resolves to it with a note.","examples":["119-102not101"],"title":"Release"},"description":"Release-point label, e.g. `119-102not101`. A bare `119-102` resolves to it with a note."},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Resolve to the newest release point on or before this date. `YYYY-MM-DD` or `MM/DD/YYYY`.","examples":["07/12/2026"],"title":"Date"},"description":"Resolve to the newest release point on or before this date. `YYYY-MM-DD` or `MM/DD/YYYY`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Max number of results to return.","default":20,"title":"Limit"},"description":"Max number of results to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":0,"description":"Pagination offset.","default":0,"title":"Offset"},"description":"Pagination offset."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["ops"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}}},"components":{"schemas":{"CitationOut":{"properties":{"query":{"type":"string","title":"Query"},"identifier":{"type":"string","title":"Identifier"},"section_identifier":{"type":"string","title":"Section Identifier"},"title_num":{"type":"string","title":"Title Num"},"section_num":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section Num"},"subdivisions":{"items":{"type":"string"},"type":"array","title":"Subdivisions"},"kind":{"type":"string","title":"Kind"},"note":{"type":"boolean","title":"Note","default":false},"et_seq":{"type":"boolean","title":"Et Seq","default":false},"exists":{"type":"boolean","title":"Exists","default":false},"heading":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heading"},"num":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Num"},"release":{"anyOf":[{"$ref":"#/components/schemas/ReleaseOut"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["query","identifier","section_identifier","title_num","kind"],"title":"CitationOut","description":"What a typed citation resolved to — the parse, plus whether it is there.\n\n`identifier` is the deepest thing the citation named; `section_identifier` is\nthe section containing it, and the one `exists` is about — a provision path\nis extracted from the section's XML at request time (ADR-0001), so\n`/us/usc/t11/s523/a/1` is never a row and could not be looked up directly.\n\n`exists` is `False`, not a 404: \"Title 99 has no section 1\" is an *answer*,\nand the reader that asked deserves to be told which part was wrong rather\nthan handed an error page."},"CorpusStatusOut":{"properties":{"latest_release":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Release","description":"Newest release point with content loaded."},"latest_currency_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Latest Currency Date"},"release_points_known":{"type":"integer","title":"Release Points Known","description":"Rows in the release-point inventory — including ones not yet ingested."},"behind_by":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Behind By","description":"Release points published since the newest one loaded here. null when the last check never succeeded, because then there is nothing trustworthy to compare against — which is not the same as zero."}},"type":"object","required":["release_points_known"],"title":"CorpusStatusOut","description":"What this database actually holds, against what the source publishes."},"DiffOpOut":{"properties":{"op":{"type":"string","title":"Op","description":"equal | insert | delete"},"text":{"type":"string","title":"Text"}},"type":"object","required":["op","text"],"title":"DiffOpOut"},"DiffOut":{"properties":{"identifier":{"type":"string","title":"Identifier"},"from":{"$ref":"#/components/schemas/DiffSectionOut"},"to":{"$ref":"#/components/schemas/DiffSectionOut"},"ops":{"items":{"$ref":"#/components/schemas/DiffOpOut"},"type":"array","title":"Ops"}},"type":"object","required":["identifier","from","to","ops"],"title":"DiffOut","description":"A redline between two release points of one section (Day 4).\n\nDiffs the verbatim XML — a generic text diff, computed here because doing\nso needs no USLM vocabulary at all (docs/adr/0016); wrapping `ops` in\n`<ins>`/`<del>` for the reading column is `frontend/src/lib`'s job."},"DiffSectionOut":{"properties":{"release":{"$ref":"#/components/schemas/ReleaseOut"},"num":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Num"},"heading":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heading"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"content_hash":{"type":"string","title":"Content Hash"}},"type":"object","required":["release","num","heading","status","content_hash"],"title":"DiffSectionOut","description":"One side of a diff: enough to label it, not the whole `SectionOut` —\nthe fragment itself only exists as `ops`, never duplicated here."},"ErrorOut":{"properties":{"detail":{"type":"string","title":"Detail"},"candidates":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Candidates"}},"type":"object","required":["detail"],"title":"ErrorOut"},"GuidOut":{"properties":{"guid":{"type":"string","title":"Guid"},"identifier":{"type":"string","title":"Identifier"},"release":{"$ref":"#/components/schemas/ReleaseOut"},"is_section":{"type":"boolean","title":"Is Section"},"section_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section Identifier"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Where to open this provision in the reader."}},"type":"object","required":["guid","identifier","release","is_section","section_identifier"],"title":"GuidOut"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LoginIn":{"properties":{"email":{"type":"string","title":"Email"},"password":{"type":"string","title":"Password"}},"type":"object","required":["email","password"],"title":"LoginIn"},"NeighborsOut":{"properties":{"identifier":{"type":"string","title":"Identifier"},"previous":{"anyOf":[{"$ref":"#/components/schemas/TocEntryOut"},{"type":"null"}]},"next":{"anyOf":[{"$ref":"#/components/schemas/TocEntryOut"},{"type":"null"}]},"release":{"$ref":"#/components/schemas/ReleaseOut"},"served_from":{"$ref":"#/components/schemas/ReleaseOut"}},"type":"object","required":["identifier","previous","next","release","served_from"],"title":"NeighborsOut"},"ReleaseOut":{"properties":{"label":{"type":"string","title":"Label","examples":["119-102not101"]},"currency_date":{"type":"string","format":"date","title":"Currency Date"},"congress":{"type":"integer","title":"Congress"},"law_num":{"type":"integer","title":"Law Num"},"excluded_laws":{"items":{"type":"integer"},"type":"array","title":"Excluded Laws","description":"Public laws enacted by the currency date but NOT incorporated."},"update_num":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Update Num","description":"The `u1` suffix, for re-issued release points."},"seq":{"type":"integer","title":"Seq","description":"Global ordering. Release-point labels do not sort."},"is_partial":{"type":"boolean","title":"Is Partial","description":"True when laws are excluded — the text is not fully current through currency_date."},"caveat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caveat"},"titles_affected":{"items":{"type":"string"},"type":"array","title":"Titles Affected"},"ingested_titles":{"items":{"type":"string"},"type":"array","title":"Ingested Titles"}},"type":"object","required":["label","currency_date","congress","law_num","seq","is_partial"],"title":"ReleaseOut"},"SearchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/SearchResultItem"},"type":"array","title":"Results"},"total":{"type":"integer","title":"Total"},"release":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Release"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"}},"type":"object","required":["results","total"],"title":"SearchResponse"},"SearchResultItem":{"properties":{"identifier":{"type":"string","title":"Identifier"},"heading":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heading"},"num":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Num"},"level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Level"},"type":{"type":"string","title":"Type"},"snippets":{"items":{"$ref":"#/components/schemas/SearchSnippet"},"type":"array","title":"Snippets","default":[]},"first_release":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Release"},"is_current":{"type":"boolean","title":"Is Current","default":true}},"type":"object","required":["identifier","type"],"title":"SearchResultItem"},"SearchSnippet":{"properties":{"field":{"type":"string","title":"Field"},"text":{"type":"string","title":"Text"}},"type":"object","required":["field","text"],"title":"SearchSnippet"},"SettingsOut":{"properties":{"open_links_in_new_tab":{"type":"boolean","title":"Open Links In New Tab"}},"type":"object","required":["open_links_in_new_tab"],"title":"SettingsOut"},"SettingsUpdateIn":{"properties":{"open_links_in_new_tab":{"type":"boolean","title":"Open Links In New Tab"}},"type":"object","required":["open_links_in_new_tab"],"title":"SettingsUpdateIn"},"SignupIn":{"properties":{"email":{"type":"string","title":"Email"},"password":{"type":"string","maxLength":200,"minLength":8,"title":"Password"}},"type":"object","required":["email","password"],"title":"SignupIn"},"SourceCheckOut":{"properties":{"url":{"type":"string","title":"Url","description":"The page that is polled — one request per check.","examples":["https://uscode.house.gov/download/priorreleasepoints.htm"]},"last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked At","description":"null means no check has ever been recorded here."},"hours_since_check":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Hours Since Check"},"ok":{"type":"boolean","title":"Ok","description":"Did the last check reach and parse the page?"},"stale":{"type":"boolean","title":"Stale","description":"True when the last check failed, is over a week old, or has never happened. A stale check does not mean the text is wrong — it means nobody has confirmed lately that it is still the newest published."},"release_points_seen":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Release Points Seen","description":"How many release points the page listed."},"new_release_points":{"items":{"type":"string"},"type":"array","title":"New Release Points","description":"Release points that check found and this database had not seen before. Non-empty means an ingest is pending, not that it failed."},"latest_published_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Published Label","description":"The newest release point OLRC published, as of that check."},"latest_published_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Latest Published Date"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why the last check failed, if it did."}},"type":"object","required":["url","ok","stale"],"title":"SourceCheckOut","description":"When this mirror last asked uscode.house.gov what exists."},"StatusOut":{"properties":{"source":{"$ref":"#/components/schemas/SourceCheckOut"},"corpus":{"$ref":"#/components/schemas/CorpusStatusOut"}},"type":"object","required":["source","corpus"],"title":"StatusOut","description":"`GET /api/v1/status` — how current this mirror is, and how it knows.\n\nTwo independent facts, deliberately not collapsed into one \"up to date\"\nflag: what we hold, and when we last confirmed that is everything there is.\nA mirror can be current and unverified, or verified and behind, and the two\ncall for different responses."},"TitleOut":{"properties":{"num":{"type":"string","title":"Num"},"name":{"type":"string","title":"Name"},"is_positive_law":{"type":"boolean","title":"Is Positive Law"},"ingested_releases":{"items":{"type":"string"},"type":"array","title":"Ingested Releases"}},"type":"object","required":["num","name","is_positive_law","ingested_releases"],"title":"TitleOut"},"TocEntryOut":{"properties":{"identifier":{"type":"string","title":"Identifier"},"level":{"type":"string","title":"Level"},"num":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Num"},"heading":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heading"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"is_section":{"type":"boolean","title":"Is Section","default":false}},"type":"object","required":["identifier","level","num","heading"],"title":"TocEntryOut"},"UserOut":{"properties":{"id":{"type":"string","title":"Id"},"email":{"type":"string","title":"Email"}},"type":"object","required":["id","email"],"title":"UserOut"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VersionOut":{"properties":{"content_hash":{"type":"string","title":"Content Hash"},"first_seen":{"$ref":"#/components/schemas/ReleaseOut"},"releases":{"items":{"type":"string"},"type":"array","title":"Releases"},"num":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Num"},"heading":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heading"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},"type":"object","required":["content_hash","first_seen","releases","num","heading","status"],"title":"VersionOut"},"VersionsOut":{"properties":{"identifier":{"type":"string","title":"Identifier"},"versions":{"items":{"$ref":"#/components/schemas/VersionOut"},"type":"array","title":"Versions","description":"One entry per distinct content, oldest first. Consecutive release points publishing identical text share an entry."}},"type":"object","required":["identifier","versions"],"title":"VersionsOut"},"WatchlistCreateIn":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"}},"type":"object","required":["name"],"title":"WatchlistCreateIn"},"WatchlistItemCreateIn":{"properties":{"identifier":{"type":"string","title":"Identifier","description":"A US Code identifier, e.g. /us/usc/t16/s45f"},"pinned_release":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pinned Release","description":"An exact release label to pin, e.g. 119-99."},"note":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Note"}},"type":"object","required":["identifier"],"title":"WatchlistItemCreateIn"},"WatchlistItemOut":{"properties":{"id":{"type":"integer","title":"Id"},"identifier":{"type":"string","title":"Identifier"},"title_num":{"type":"string","title":"Title Num"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"},"pinned_release_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pinned Release Label","description":"An exact release label the user pinned, or null to always open at the newest release this title is ingested at."},"created_at":{"type":"string","format":"date-time","title":"Created At"},"num":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Num","description":"Absent when enrichment failed."},"heading":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heading"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},"type":"object","required":["id","identifier","title_num","note","pinned_release_label","created_at"],"title":"WatchlistItemOut","description":"One watched provision, enriched with what it currently says (Day 5) — a\nbadge that went `repealed`/`transferred` since it was added is just this\nitem's current `status`, fetched the same way a page's citations are\n(`Repository.labels`, batched)."},"WatchlistItemUpdateIn":{"properties":{"pinned_release":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pinned Release"},"note":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Note"}},"type":"object","title":"WatchlistItemUpdateIn"},"WatchlistOut":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"items":{"items":{"$ref":"#/components/schemas/WatchlistItemOut"},"type":"array","title":"Items"}},"type":"object","required":["id","name","items"],"title":"WatchlistOut"},"WatchlistSummaryOut":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"item_count":{"type":"integer","title":"Item Count"}},"type":"object","required":["id","name","item_count"],"title":"WatchlistSummaryOut"}}}}