{"openapi":"3.1.0","info":{"title":"ChassidusHub API","version":"1.0.0","summary":"The open, community-edited index of Chabad Torah and media","description":"Reading needs nothing. Reporting a problem needs no account. Suggesting and reviewing need a signed-in person: a personal API token (`Authorization: Bearer rhp_…`, made on the account page) or the site's session. What a token sends is a suggestion, reviewed like any other.\n\nErrors are `{ error, message, detail? }` with the HTTP status of their kind. Lists that page answer `next`; pass it back as `cursor`. JSON answers carry an ETag (send If-None-Match for a 304). Requests are limited per address and, with a token, per token (RateLimit-Policy; 429 with Retry-After). Words a machine read or heard are marked until a person checks them. /v1 changes only by adding; see the developer docs.","license":{"name":"AGPL-3.0-only (code); CC0-1.0 (catalog facts); CC-BY-SA-4.0 (community text)","identifier":"AGPL-3.0-only"},"contact":{"name":"ChassidusHub","url":"https://github.com/ChassidusHub/ChassidusHub"}},"externalDocs":{"description":"Developer docs","url":"https://chassidushub.org/developers"},"servers":[{"url":"https://api.chassidushub.org","description":"ChassidusHub"}],"tags":[{"name":"About","description":"This API, the catalog in numbers"},{"name":"Items","description":"Every sefer, sicha, letter, farbrengen, printing, scan and recording: by id, path, type, set and date, with history"},{"name":"Search","description":"By names and dates, inside the words, and by meaning"},{"name":"Texts","description":"Scans' texts line by line, printings compared, translations"},{"name":"Media","description":"Transcripts and their sync"},{"name":"Machine","description":"Asking the machines to read a scan or transcribe a recording, and their queue"},{"name":"Files","description":"File bytes (while their rights allow), page images, uploads"},{"name":"Suggestions","description":"Every change is a suggestion, checked and reviewed"},{"name":"Organize","description":"Moving, renaming, ordering, merging and splitting: the catalog's tree put in order, as suggestions"},{"name":"Talk","description":"The conversation on each page"},{"name":"Reports","description":"Reporting a problem, takedowns, families' requests"},{"name":"Issues","description":"Reports kept like issues: titles, labels, assignees, comments, closing"},{"name":"People","description":"Handles and profiles; people and conversations to @mention and #mention"},{"name":"Inbox","description":"What concerns you: mentions, review requests, assignments, what you follow"},{"name":"Projects","description":"Group efforts through a gap, the Missing board"},{"name":"Personal","description":"What you follow, where you stopped"},{"name":"Webhooks","description":"Every merge posted to your address, signed"},{"name":"Tokens","description":"Personal API tokens, made on the account page, and apps connected with OAuth"},{"name":"OAuth","description":"Connecting an app (Claude, other MCP clients) as a person: OAuth 2.1 with PKCE, registration and metadata"},{"name":"Mirrors","description":"Editions and their signed dumps"},{"name":"Apps","description":"The Sichos Kodesh apps' catalog, at the paths and in the shapes they read"},{"name":"Libraries","description":"OAI-PMH and IIIF"},{"name":"Agents","description":"llms.txt and the MCP server"},{"name":"Sign-in","description":"The site's own sign-in; listed for completeness, not for other clients"},{"name":"Stewards","description":"The stewards' tools on the site; listed for completeness"}],"components":{"securitySchemes":{"token":{"type":"http","scheme":"bearer","bearerFormat":"rhp_… or rho_…","description":"A personal API token from the account page, or an OAuth access token given to a connected app, with the read or write scope."},"session":{"type":"apiKey","in":"cookie","name":"__Host-rh_session","description":"The site's own session, from its own pages only."}},"schemas":{"Via":{"type":"object","properties":{"kind":{"enum":["token","oauth"],"description":"A personal API token, or an app connected with OAuth"},"id":{"type":"string","description":"The token (tok-…) or the connection (oac-…)"},"name":{"type":"string","description":"The token's name, or the app's (Claude)"},"client":{"type":"string","description":"A connected app's client id"}},"required":["kind","id","name"],"description":"Sent by an agent for its author, not by their own hands; null otherwise. The site shows it as \"Claude · for @person\"."},"ApiError":{"type":"object","properties":{"error":{"enum":["bad-request","unauthorized","forbidden","not-found","conflict","invalid","rate-limited","internal","state","too-large","upstream","busy"],"description":"What kind of error, for programs"},"message":{"type":"string","description":"What went wrong, for people"},"detail":{"description":"More, when there is more (a check that failed, the clashes of a merge)"},"conflicts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"For a merge that clashes"}},"required":["error","message"]},"StatusReport":{"type":"object","properties":{"checkedAt":{"type":"string","description":"When the checks last ran","format":"date-time"},"state":{"$ref":"#/components/schemas/CheckState"},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CheckId"},"state":{"$ref":"#/components/schemas/CheckState"},"ms":{"oneOf":[{"type":"integer","description":"How long it took to answer"},{"type":"null"}]},"detail":{"oneOf":[{"type":"string","description":"A sentence for people, when something is wrong"},{"type":"null"}]}},"required":["id","state","ms","detail"]}},"quota":{"oneOf":[{"type":"object","properties":{"used":{"type":"integer","description":"Queries through Hyperdrive since 00:00 UTC"},"limit":{"oneOf":[{"type":"integer","description":"The daily allowance; null on a plan without one"},{"type":"null"}]},"resetsAt":{"type":"string","format":"date-time"},"runsOutAt":{"oneOf":[{"type":"string","description":"At today's pace, when it runs out, if before it resets","format":"date-time"},{"type":"null"}]}},"required":["used","limit","resetsAt","runsOutAt"]},{"type":"null"}]},"workers":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"script":{"type":"string","description":"The Worker's name"},"requests":{"type":"integer","description":"Requests since 00:00 UTC"},"errors":{"type":"integer","description":"Of them, ended by the runtime with an error"},"exceeded":{"type":"integer","description":"Of them, stopped for going over the CPU allowance (error 1102)"},"cpuP50Ms":{"oneOf":[{"type":"number","description":"The CPU a request takes, in milliseconds: the median"},{"type":"null"}]},"cpuP99Ms":{"oneOf":[{"type":"number","description":"The slowest hundredth"},{"type":"null"}]}},"required":["script","requests","errors","exceeded","cpuP50Ms","cpuP99Ms"]},"description":"Each Worker's load today; missing in reports made before it was measured"},{"type":"null"}]},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"YYYY-MM-DD, UTC"},"checks":{"type":"object","additionalProperties":{"type":"object","properties":{"runs":{"type":"integer"},"up":{"type":"integer"},"degraded":{"type":"integer"},"down":{"type":"integer"}},"required":["runs","up","degraded","down"]}}},"required":["date","checks"]},"description":"Oldest first, at most 90"},"incidents":{"type":"array","items":{"type":"object","properties":{"check":{"$ref":"#/components/schemas/CheckId"},"state":{"enum":["degraded","down"]},"from":{"type":"string","format":"date-time"},"to":{"oneOf":[{"type":"string","description":"Null while it goes on","format":"date-time"},{"type":"null"}]},"detail":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["check","state","from","to","detail"]},"description":"Newest first, at most 30"}},"required":["checkedAt","state","checks","quota","days","incidents"]},"CheckId":{"enum":["site","api","mcp","database","quota","workers","jobs"]},"CheckState":{"enum":["up","degraded","down","unknown"],"description":"unknown: not checked this time; it counts for nothing"},"About":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"head":{"type":"integer","description":"The latest commit's seq"},"docs":{"type":"string"},"developers":{"type":"string"},"mcp":{"type":"string","description":"The MCP server"},"licence":{"type":"object","additionalProperties":true}},"required":["name","version","head"]},"Item":{"type":"object","properties":{"id":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"type":{"type":"string"},"path":{"oneOf":[{"type":"string"},{"type":"null"}]},"rev":{"type":"integer","description":"The revision shown"},"data":{"type":"object","additionalProperties":true,"description":"The item's data, as its type's JSON Schema (/v1/types) says. In a list, without `body` (the words a page keeps in itself, kilobytes each): read the item by id, or several with /v1/entities/batch, for them"},"withheld":{"type":"string","description":"Set when its words are held back for rights: the item is listed, its text is not served"},"recordings":{"type":"integer","description":"For events: how many recordings it has"}},"required":["id","type","path","rev","data"]},"ItemPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"next":{"oneOf":[{"type":"string","description":"Pass back as cursor for the next page; null on the last"},{"type":"null"}]}},"required":["items","next"]},"AppCatalogManifest":{"type":"object","properties":{"schemaVersion":{"type":"integer","description":"1, 2 or 3"},"version":{"type":"string","description":"X.Y.Z: 2.<commit>.0, or 0.<commit>.0 while a part is missing"},"releasedAt":{"type":"string","format":"date-time"},"url":{"type":"string","description":"Where its catalog.json is"},"bytes":{"type":"integer"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"years":{"type":"array","items":{"type":"integer"}},"occasions":{"type":"integer"},"changelog":{"type":"array","items":{"type":"object","properties":{"version":{"type":"string"},"date":{"type":"string"},"en":{"type":"array","items":{"type":"string"}},"he":{"type":"array","items":{"type":"string"}}},"required":["version","date","en","he"]}},"collections":{"type":"object","additionalProperties":{"type":"integer"},"description":"v2 and v3: items per library collection"},"works":{"type":"object","properties":{"works":{"type":"integer"},"units":{"type":"integer"}},"required":["works","units"],"description":"v3: how many works, and how many units their contents have"},"missing":{"type":"array","items":{"type":"string"},"description":"Parts ChassidusHub does not hold yet (farbrengens, library, works)"}},"required":["schemaVersion","version","releasedAt","url","bytes","sha256","years","occasions","changelog"]},"Commit":{"type":"object","properties":{"seq":{"type":"integer"},"at":{"type":"string","format":"date-time"},"message":{"type":"string"},"mergedBy":{"type":"string"},"author":{"type":"string"},"via":{"oneOf":[{"$ref":"#/components/schemas/Via"},{"type":"null"}]},"changed":{"type":"integer","description":"How many items it changed in all"},"types":{"type":"array","items":{"type":"string","description":"The kinds of items it changed"}},"changes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"type":{"type":"string"},"path":{"oneOf":[{"type":"string"},{"type":"null"}]},"rev":{"type":"integer"},"data":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]}}}}},"required":["seq","at","message","mergedBy","author","changed","types","changes"]},"TreeNode":{"type":"object","properties":{"id":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"type":{"type":"string"},"path":{"oneOf":[{"type":"string"},{"type":"null"}]},"name":{"oneOf":[{"type":"object","additionalProperties":true,"description":"Its name, Hebrew and English"},{"type":"null"}]},"order":{"oneOf":[{"type":"string","description":"Its sort key among its siblings, when it has one"},{"type":"null"}]},"counts":{"type":"object","properties":{"sets":{"type":"integer","description":"Sets under it"},"items":{"type":"integer","description":"Items in it (a set)"},"units":{"type":"integer","description":"Units of it (a sefer)"}}},"children":{"type":"array","items":{"$ref":"#/components/schemas/TreeNode"}},"more":{"type":"integer","description":"Children left out past the limit"},"addition":{"type":"object","properties":{"kind":{"enum":["commentary","index","about","collection","other"]},"to":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},"required":["kind"],"description":"A sefer that is an addition, not an official sefer: its kind, and the official sefer it belongs to"}},"required":["id","type","path","name","counts"]},"OrganizeOperation":{"type":"object","description":"One step of a plan. Items are ids (rh-…), or new:<key> for a set made earlier in the same plan. Positions are \"start\", \"end\", { after: id } or { before: id }.\n- move { items, to, from?, mode?: add | only, position? }: into a set (a sefer joins it, leaving `from` when given); `to: null` with `from` takes it out; a set under a set or to the top (to: null); a unit to another work, a printing to a work, a scan to a printing, a recording to an event.\n- move-up { items, from? }: a set to its parent's parent; an item out of a set into that set's parent.\n- rename { item, name?: { he?, en? }, slug?, path? }: old paths redirect, and paths made from it (a sefer's units) move along.\n- reorder { items, parent?, position? }: without position, the items take the places they hold in the order given.\n- create-set { key?, name: { he, en? }, slug, parent?, description?, items? }\n- delete-set { item }: only a set that holds nothing.\n- merge { from, into }: everything under or pointing at `from` moves to `into`; `from` is deleted and its paths lead to `into`.\n- split { work, units? | range: { from, to }, title: { he, en? }, slug }: units into a new sefer.\n- addition { item, to?, kind: commentary | index | about | collection | other }: a sefer is not one of the official sefarim the tree is built of but an addition, listed on the page of the official sefer `to` (or, without it, apart at the end of its shelf).\n- official { item }: an addition becomes an official sefer again.","properties":{"op":{"enum":["move","move-up","rename","reorder","create-set","delete-set","merge","split","addition","official"]},"kind":{"enum":["commentary","index","about","collection","other"]},"items":{"type":"array","items":{"type":"string"}},"item":{"type":"string"},"to":{"oneOf":[{"type":"string"},{"type":"null"}]},"from":{"type":"string"},"into":{"type":"string"},"mode":{"enum":["add","only"]},"position":{"oneOf":[{"enum":["start","end"]},{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},{"type":"object","properties":{"before":{"type":"string"}},"required":["before"]}]},"parent":{"oneOf":[{"type":"string"},{"type":"null"}]},"name":{"type":"object","additionalProperties":true,"description":"{ he, en }"},"title":{"type":"object","additionalProperties":true,"description":"{ he, en }"},"slug":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"},"path":{"type":"string"},"key":{"type":"string"},"description":{"type":"object","additionalProperties":true,"description":"{ he, en }"},"work":{"type":"string"},"units":{"type":"array","items":{"type":"string"}},"range":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]}},"required":["op"]},"OrganizePlan":{"type":"object","properties":{"operations":{"type":"array","items":{"$ref":"#/components/schemas/OrganizeOperation"},"description":"Done in order, each seeing what the ones before it did"},"title":{"type":"string","description":"The suggestion's title; made from the operations when left out","maxLength":200},"description":{"type":"string"},"draft":{"type":"boolean","description":"Keep it a draft instead of sending it for review (organize only)"},"apply":{"type":"boolean","description":"Approve it at once where you may approve it yourself (organize only)"}},"required":["operations"]},"OrganizePreview":{"type":"object","properties":{"title":{"type":"string"},"summary":{"type":"array","items":{"type":"string"},"description":"One line per operation"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"type":{"type":"string"},"name":{"type":"string"},"isNew":{"type":"boolean"},"deleted":{"type":"boolean"},"pathBefore":{"oneOf":[{"type":"string"},{"type":"null"}]},"path":{"oneOf":[{"type":"string"},{"type":"null"}]},"changes":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"before":{},"after":{}}}}},"required":["id","type","changes"]}},"redirects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"from":{"type":"string"},"to":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"description":"Old paths and where they lead once approved"},"forwards":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"to":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}},"description":"Items merged into others"},"warnings":{"type":"array","items":{"type":"string"}},"created":{"type":"object","additionalProperties":true,"description":"The new sets, by their key"}},"required":["title","summary","items","redirects","forwards","warnings"]},"Suggestion":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"oneOf":[{"type":"string"},{"type":"null"}]},"author":{"type":"string"},"via":{"oneOf":[{"$ref":"#/components/schemas/Via"},{"type":"null"}]},"status":{"enum":["draft","open","merged","sent_back","withdrawn"]},"kind":{"type":"string"},"project_id":{"oneOf":[{"type":"integer"},{"type":"null"}]},"base_commit":{"type":"integer"},"merged_commit":{"oneOf":[{"type":"integer"},{"type":"null"}]},"post_review":{"enum":["pending","done",null]},"checks":{"type":"array","items":{"type":"object","properties":{"check":{"type":"string"},"status":{"enum":["pass","fail","warn"]},"message":{"type":"string"}}},"description":"The checks that did not pass, of this page's items and of the whole; `checkCounts` counts them all"},"checkCounts":{"type":"object","properties":{"pass":{"type":"integer"},"warn":{"type":"integer"},"fail":{"type":"integer"}},"required":["pass","warn","fail"],"description":"All its checks, by status"},"created_at":{"type":"string"},"submitted_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"closed_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"number":{"oneOf":[{"type":"integer","description":"Its #number; an import has none"},{"type":"null"}]},"items":{"type":"integer","description":"How many items it changes"}},"required":["id","title","author","status"]},"SuggestionListItem":{"type":"object","properties":{"id":{"type":"integer"},"number":{"type":"integer"},"title":{"type":"string"},"status":{"enum":["draft","open","merged","sent_back","withdrawn"]},"kind":{"type":"string"},"author":{"type":"string"},"createdAt":{"type":"string"},"submittedAt":{"oneOf":[{"type":"string"},{"type":"null"}]},"closedAt":{"oneOf":[{"type":"string"},{"type":"null"}]},"comments":{"type":"integer"},"reviewers":{"type":"array","items":{"type":"string"}},"approvals":{"type":"integer"},"changesRequested":{"type":"boolean"},"fixes":{"type":"array","items":{"type":"integer"},"description":"Issues it closes, by number"},"via":{"oneOf":[{"$ref":"#/components/schemas/Via"},{"type":"null"}]},"types":{"type":"array","items":{"type":"string"},"description":"The kinds of items it changes"},"first":{"description":"The first item it changes, by id","oneOf":[{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},{"type":"null"}]}},"required":["id","number","title","status","author"]},"Issue":{"type":"object","properties":{"id":{"type":"integer"},"number":{"type":"integer","description":"Its number, shared with suggestions: #12"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"typeTitle":{"type":"object","properties":{"he":{"type":"string"},"en":{"type":"string"}}},"type":{"type":"string"},"state":{"enum":["open","closed"]},"stateReason":{"enum":["completed","not_planned",null]},"body":{"oneOf":[{"type":"string"},{"type":"null"}]},"private":{"type":"boolean"},"author":{"oneOf":[{"type":"string","description":"An account id; null for a reader without an account"},{"type":"null"}]},"via":{"oneOf":[{"$ref":"#/components/schemas/Via"},{"type":"null"}]},"entity":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"set":{"oneOf":[{"type":"string"},{"type":"null"}]},"labels":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"oneOf":[{"type":"string"},{"type":"null"}]},"color":{"type":"string"}}}},"assignees":{"type":"array","items":{"type":"string"}},"comments":{"type":"integer"},"createdAt":{"type":"string"},"updatedAt":{"oneOf":[{"type":"string"},{"type":"null"}]},"closedAt":{"oneOf":[{"type":"string"},{"type":"null"}]},"closedBy":{"oneOf":[{"type":"string"},{"type":"null"}]},"closedBySuggestion":{"oneOf":[{"type":"integer"},{"type":"null"}]}},"required":["id","number","type","state","private","labels","assignees","createdAt"]},"InboxLine":{"type":"object","properties":{"id":{"type":"integer"},"reason":{"enum":["mention","review_requested","assigned","author","comment","review","state","followed"]},"subject":{"type":"object","additionalProperties":true,"description":"What it is about: a suggestion or issue (number, title, state) or an item's talk page (path, name)"},"actor":{"oneOf":[{"type":"string"},{"type":"null"}]},"actorName":{"oneOf":[{"type":"string"},{"type":"null"}]},"actorUsername":{"oneOf":[{"type":"string"},{"type":"null"}]},"count":{"type":"integer"},"detail":{"type":"object","additionalProperties":true},"at":{"type":"string"},"read":{"type":"boolean"}},"required":["id","reason","subject","count","at","read"]},"Comment":{"type":"object","properties":{"id":{"type":"integer"},"parent":{"oneOf":[{"type":"integer"},{"type":"null"}]},"author":{"type":"string"},"authorName":{"type":"string"},"body":{"oneOf":[{"type":"string"},{"type":"null"}]},"at":{"type":"string"},"hidden":{"type":"boolean"}},"required":["id","author","body","at"]},"ScanTextPage":{"type":"object","properties":{"scan":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"page":{"type":"integer"},"pages":{"type":"integer"},"machine":{"type":"boolean","description":"Still an OCR page, untouched by people"},"engine":{"oneOf":[{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}},{"type":"null"}]},"level":{"type":"integer","description":"Proofread: 0 not yet, 1 once, 2 twice","minimum":0,"maximum":2},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"checked":{"type":"boolean","description":"false: machine reading nobody has checked"},"level":{"type":"integer"}},"required":["id","text","checked"]}},"layers":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["scan","page","pages","lines"]},"MachineRequest":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"enum":["ocr","transcript"]},"item":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"requestedBy":{"type":"string"},"status":{"enum":["waiting","running","done","failed"]},"note":{"oneOf":[{"type":"string","description":"Why it failed, or what the machine found"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"startedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"finishedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"position":{"oneOf":[{"type":"integer","description":"Its place among the waiting requests of its kind, 1 is next"},{"type":"null"}]}},"required":["id","kind","item","status","createdAt"]},"Transcript":{"type":"object","properties":{"recording":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"text":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"language":{"type":"string"},"alignment":{"oneOf":[{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},{"type":"null"}]},"granularity":{"enum":["word","paragraph",null]},"paragraphs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"content":{"type":"string"},"startMs":{"oneOf":[{"type":"integer"},{"type":"null"}]},"endMs":{"oneOf":[{"type":"integer"},{"type":"null"}]},"words":{"oneOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"null"}]},"locked":{"type":"boolean"},"checked":{"type":"boolean","description":"false: machine hearing nobody has checked"},"edited":{"type":"boolean","description":"a person fixed some words but did not check the whole paragraph"},"syncChecked":{"type":"boolean"}},"required":["id","content","checked"]}},"pending":{"type":"array","items":{"type":"object","properties":{"segment":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"content":{"type":"string","description":"The paragraph as the fix would make it"},"complete":{"type":"boolean","description":"The person checked all of it"},"author":{"type":"string"},"authorName":{"oneOf":[{"type":"string"},{"type":"null"}]},"at":{"type":"string"},"suggestion":{"oneOf":[{"type":"integer","description":"Its #number"},{"type":"null"}]}},"required":["segment","content","complete","author","at","suggestion"]},"description":"Fixes of the words waiting for approval, a suggestion's together in the transcript's order"}},"required":["recording","text","paragraphs"]},"File":{"type":"object","properties":{"sha256":{"type":"string"},"bytes":{"type":"integer"},"mime":{"type":"string"},"rights":{"enum":["open","credit","link","preserved"]},"credit":{"oneOf":[{"type":"string"},{"type":"null"}]},"url":{"oneOf":[{"type":"string","description":"Where its bytes are served; null while its rights keep it private"},{"type":"null"}]},"derivations":{"type":"array","items":{"type":"object","additionalProperties":true}},"pageFix":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"pageImages":{"type":"integer"}},"required":["sha256","bytes","mime","rights","url"]},"Cover":{"type":"object","properties":{"file":{"type":"string","description":"A file, named by its sha256","pattern":"^[0-9a-f]{64}$"},"page":{"type":"integer","description":"The PDF page drawn","minimum":1},"machine":{"type":"boolean","description":"true: a machine chose the title page and no person has yet"},"reasons":{"type":"array","items":{"type":"string"}},"credit":{"oneOf":[{"type":"string"},{"type":"null"}]},"image":{"type":"object","properties":{"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["url","width","height"]},"thumb":{"type":"object","properties":{"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["url","width","height"]}},"required":["file","page","machine","image","thumb"]},"ApiToken":{"type":"object","properties":{"id":{"type":"string"},"kind":{"enum":["personal","oauth"],"description":"A personal token, or an app connected with OAuth (its name is the app's)"},"name":{"type":"string"},"prefix":{"type":"string","description":"Its first characters, to recognise it"},"scopes":{"type":"array","items":{"enum":["read","write"]}},"createdAt":{"type":"string"},"lastUsedAt":{"oneOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"oneOf":[{"type":"string"},{"type":"null"}]},"revokedAt":{"oneOf":[{"type":"string"},{"type":"null"}]},"client":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"uri":{"oneOf":[{"type":"string"},{"type":"null"}]},"host":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"]}},"required":["id","kind","name","prefix","scopes","createdAt"]},"ProtectedResource":{"type":"object","properties":{"resource":{"type":"string"},"authorization_servers":{"type":"array","items":{"type":"string"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}},"resource_name":{"type":"string"},"resource_documentation":{"type":"string"}},"required":["resource","authorization_servers"]}},"responses":{"400":{"description":"A mistake in the request (an id that is not one, a missing field)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Not signed in, or a token that is not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Not allowed: a read-only token, or not a keeper","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not there, or withheld for its rights","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many requests: wait (Retry-After) or send a token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"paths":{"/":{"get":{"operationId":"root","tags":["About"],"summary":"Redirects to /v1","x-access":"public","responses":{"302":{"description":"To /v1"},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1":{"get":{"operationId":"about","tags":["About"],"summary":"About this API: its version, the latest commit, where the docs are","x-access":"public","responses":{"200":{"description":"About","content":{"application/json":{"schema":{"$ref":"#/components/schemas/About"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/openapi.json":{"get":{"operationId":"openapi","tags":["About"],"summary":"This document","x-access":"public","responses":{"200":{"description":"OpenAPI 3.1","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/llms.txt":{"get":{"operationId":"llmsTxt","tags":["Agents"],"summary":"A short guide for AI agents (llms.txt)","x-access":"public","responses":{"200":{"description":"Markdown","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/robots.txt":{"get":{"operationId":"robotsTxt","tags":["Agents"],"summary":"What crawlers may read on the API: the guides and the files, not the routes","x-access":"public","responses":{"200":{"description":"robots.txt","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/types":{"get":{"operationId":"types","tags":["Items"],"summary":"Every kind of item and its JSON Schema","x-access":"public","responses":{"200":{"description":"Types and schemas","content":{"application/json":{"schema":{"type":"object","properties":{"types":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"schema":{"type":"object","additionalProperties":true}},"required":["type","schema"]}}},"required":["types"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/stats":{"get":{"operationId":"stats","tags":["About"],"summary":"How many items of each type, and the latest commit","x-access":"public","responses":{"200":{"description":"Counts","content":{"application/json":{"schema":{"type":"object","properties":{"head":{"type":"integer"},"counts":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["head","counts"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/community":{"get":{"operationId":"community","tags":["About"],"summary":"The community page in numbers: the latest merges, reports and suggestions waiting, people, gaps","x-access":"public","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":8},"description":"How many (at most 50)"}],"responses":{"200":{"description":"Numbers and the latest merges","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/status":{"get":{"operationId":"status","tags":["About"],"summary":"Whether ChassidusHub is up: the last checks of the site, the API, the MCP server, the database, its daily query allowance, the Workers' load and the scheduled jobs, with 90 days of them and the latest incidents","description":"Checked every five minutes; read from storage, never from the database, so it answers when the database does not. `report` is null until the first check. When `report.checkedAt` is much older than `now`, the checks have stopped running.","x-access":"public","responses":{"200":{"description":"The last report","content":{"application/json":{"schema":{"type":"object","properties":{"now":{"type":"string","format":"date-time"},"report":{"oneOf":[{"$ref":"#/components/schemas/StatusReport"},{"type":"null"}]}},"required":["now","report"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/health":{"get":{"operationId":"health","tags":["About"],"summary":"The health of the catalog: coverage per year and set, unchecked pages, unsynced recordings, dead links, the oldest open suggestions","x-access":"public","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":20},"description":"How many (at most 500)"}],"responses":{"200":{"description":"Health","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities":{"get":{"operationId":"listItems","tags":["Items"],"summary":"Items on main, by type and set, in path order, a page at a time","x-access":"public","x-paged":true,"parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","description":"One of set, author, work, unit, event, publication, scan, contents-map, text-layer, text-page, text, segment, recording, alignment, alignment-span, relation, person, place, topic, source, schema"}},{"name":"set","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"Only items in this set"},{"name":"shelf","in":"query","required":false,"schema":{"type":"boolean"},"description":"What a shelf lists: leaves out the additions to a sefer (a work's addition.to), which are listed on that sefer's page"},{"name":"official","in":"query","required":false,"schema":{"type":"boolean"},"description":"true: only the official sefarim the tree is built of (no additions); false: only additions"},{"name":"additions-of","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"Only the additions to this sefer"},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Deprecated: the same as cursor"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"description":"How many (at most 500)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `next` of the page before"}],"responses":{"200":{"description":"A page of items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPage"}}},"headers":{"Link":{"description":"rel=\"next\": the next page","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/batch":{"get":{"operationId":"getItems","tags":["Items"],"summary":"Several items at once, in the order asked (missing ones left out)","x-access":"public","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string","description":"Comma separated, at most 200"},"description":"The ids"}],"responses":{"200":{"description":"The items","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{id}":{"get":{"operationId":"getItem","tags":["Items"],"summary":"One item, on main or as of a commit","description":"Words whose rights forbid copies are left out, and `withheld` says why.","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},{"name":"at","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"A commit's seq: the item as it was then"}],"responses":{"200":{"description":"The item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{id}/children":{"get":{"operationId":"listChildren","tags":["Items"],"summary":"An item's children in their own order (a work's units, a text's paragraphs), a page at a time","x-access":"public","x-paged":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},{"name":"field","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-z][a-zA-Z]*$"},"description":"The children's field that points at this item (work, text, event…)"},{"name":"type","in":"query","required":true,"schema":{"type":"string"},"description":"The children's type (unit, segment, recording…)"},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Deprecated: the same as cursor"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"How many (at most 1000)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `next` of the page before"}],"responses":{"200":{"description":"A page of children","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPage"}}},"headers":{"Link":{"description":"rel=\"next\": the next page","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{id}/linked/counts":{"get":{"operationId":"linkedCounts","tags":["Items"],"summary":"What points at an item, by type and field, with how many of each","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"The groups, largest first","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"field":{"type":"string"},"count":{"type":"integer"}},"required":["type","field","count"]}}},"required":["groups"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/batch/linked":{"get":{"operationId":"linkedOfEach","tags":["Items"],"summary":"One group of what points at each of several items, a few of each in the group's order: what a list needs of every row in one request (a sefer's sichos' texts, a farbrengen's sichos' words)","x-access":"public","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string","description":"Comma separated, at most 200"},"description":"The items"},{"name":"field","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-z][a-zA-Z]*(\\.[a-z][a-zA-Z]*)?$"},"description":"The field that points at them (unit, text, publication…)"},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Only items of this type"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"description":"How many (at most 500)"}],"responses":{"200":{"description":"By item: the items pointing at it, in order, at most `limit` each; an item nothing points at is left out","content":{"application/json":{"schema":{"type":"object","properties":{"linked":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/Item"}}}},"required":["linked"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/texts/batch/progress":{"get":{"operationId":"textsProgress","tags":["Texts"],"summary":"How many paragraphs each of several texts has, how many of them a person checked, and how many a machine made that nobody checked yet","x-access":"public","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string","description":"Comma separated, at most 200"},"description":"The texts"}],"responses":{"200":{"description":"By text; a text without paragraphs is left out","content":{"application/json":{"schema":{"type":"object","properties":{"progress":{"type":"object","additionalProperties":{"type":"object","properties":{"paragraphs":{"type":"integer"},"checked":{"type":"integer"},"machine":{"type":"integer"}},"required":["paragraphs","checked","machine"]}}},"required":["progress"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{id}/linked":{"get":{"operationId":"listLinked","tags":["Items"],"summary":"One group of what points at an item, in its own order, a page at a time, with the total","x-access":"public","x-paged":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},{"name":"field","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-z][a-zA-Z]*(\\.[a-z][a-zA-Z]*)?$"},"description":"The field that points here (work, event, sets…; addition.to for the additions to a sefer)"},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Only items of this type"},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Deprecated: the same as cursor"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"How many (at most 500)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `next` of the page before"}],"responses":{"200":{"description":"A page of items and the total","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"total":{"type":"integer"},"next":{"oneOf":[{"type":"string","description":"Pass back as cursor for the next page; null on the last"},{"type":"null"}]}},"required":["items","total","next"]}}},"headers":{"Link":{"description":"rel=\"next\": the next page","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{id}/shaar":{"get":{"operationId":"getShaar","tags":["Items"],"summary":"A sefer's shaar file, the README of a sefer, in its fixed form (docs/shaar.md)","description":"For a sefer no person has written one for, the one the catalog makes from its data, with `machine` true. `?format=text` gives the file itself.","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},{"name":"format","in":"query","required":false,"schema":{"enum":["json","text"]},"description":"text: the file itself, as text/markdown"}],"responses":{"200":{"description":"The file, and whether the catalog made it","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"machine":{"type":"boolean"}},"required":["text","machine"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{id}/history":{"get":{"operationId":"itemHistory","tags":["Items"],"summary":"Every merged change to an item, newest first: who, when, and what changed field by field","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"History","content":{"application/json":{"schema":{"type":"object","properties":{"history":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["history"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{id}/backlinks":{"get":{"operationId":"itemBacklinks","tags":["Items"],"summary":"Items that point at this one","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},{"name":"field","in":"query","required":false,"schema":{"type":"string"},"description":"Only links in this field"},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Only items of this type"}],"responses":{"200":{"description":"Backlinks","content":{"application/json":{"schema":{"type":"object","properties":{"backlinks":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"type":{"type":"string"},"field":{"type":"string"},"path":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["from","type","field","path"]}}},"required":["backlinks"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{id}/relations":{"get":{"operationId":"itemRelations","tags":["Items"],"summary":"An item's links both ways: cites, printed in, based on, cited by","description":"Each is `machine: true` while a machine found it and no person has checked it.","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"Relations","content":{"application/json":{"schema":{"type":"object","properties":{"relations":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["relations"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{id}/restore":{"post":{"operationId":"restoreItem","tags":["Suggestions"],"summary":"Suggest restoring an earlier version of an item","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rev":{"type":"integer","description":"The revision to restore"}},"required":["rev"]}}}},"responses":{"201":{"description":"The suggestion made","content":{"application/json":{"schema":{"type":"object","properties":{"suggestion":{"type":"integer"}},"required":["suggestion"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/revisions/{rev}":{"get":{"operationId":"getRevision","tags":["Items"],"summary":"One stored version of an item","x-access":"public","parameters":[{"name":"rev","in":"path","required":true,"schema":{"type":"integer","description":"A revision id","minimum":1}}],"responses":{"200":{"description":"The revision","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/resolve":{"get":{"operationId":"resolvePath","tags":["Items"],"summary":"The item at a readable path (an old path answers with where it moved)","x-access":"public","parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string","examples":["/events/5742-05-10"]},"description":"A path such as /likkutei-sichos/12/3"}],"responses":{"200":{"description":"Its id and current path","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"redirected":{"type":"boolean"},"path":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["id","redirected","path"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/events":{"get":{"operationId":"listEvents","tags":["Items"],"summary":"Farbrengens and other events by Hebrew date, each with how many recordings it has","x-access":"public","parameters":[{"name":"within","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}(-(0[1-9]|1[0-2]|06A|06B))?$"},"description":"A year (5742) or a month (5742-05)"},{"name":"day","in":"query","required":false,"schema":{"type":"string"},"description":"A day of any year (05-10), or several, comma separated"},{"name":"dates","in":"query","required":false,"schema":{"type":"string"},"description":"Exact dates, comma separated (5742-05-10,5743-05-10)"},{"name":"missing","in":"query","required":false,"schema":{"enum":["recordings","texts"]},"description":"Only those without"},{"name":"brief","in":"query","required":false,"schema":{"enum":["1"]},"description":"With 1: each event's facts with each link's kind alone, not its label and pages, for a calendar's rows (well under half the bytes)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":2000,"default":500},"description":"How many (at most 2000)"}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/daily":{"get":{"operationId":"dailyLearning","tags":["Texts"],"summary":"A day's learning: Chitas (Tanya, the day's portion, each chapter it touches cut to it; Chumash with Rashi; Tehillim), Hayom Yom, and the Rambam's three tracks","description":"The day is the civil day it is learned on. Tanya follows the yearly cycle from 19 Kislev (Sefaria's Tanya Yomi); Hayom Yom gives both Adars' entries in a plain year's Adar. Each Tanya chapter says where the portion starts (`from`) and the first segment after it (`to`, null to its end). Chumash (the week's parsha, an aliyah a day, outside the Land of Israel), Tehillim (the monthly cycle, with Elul's and the ten days' three more) and the Rambam (three chapters, one chapter, Sefer HaMitzvos) are named in Hebrew and by Sefaria's references.","x-access":"public","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2026-09-30"]},"description":"The civil day"}],"responses":{"200":{"description":"The day","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"hebrew":{"type":"string","description":"Its Hebrew date key (5787-01-19)"},"tanya":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"hayomYom":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"chumash":{"oneOf":[{"type":"object","properties":{"label":{"type":"string","examples":["בא, ראשון עם פירש״י"]},"ref":{"type":"string","examples":["Exodus 10:1-11"]},"path":{"oneOf":[{"type":"string","description":"Where it starts on ChassidusHub, once the catalog has it"},{"type":"null"}]},"rashi":{"oneOf":[{"type":"string","description":"Its Rashi on ChassidusHub"},{"type":"null"}]}},"required":["label","ref","path","rashi"]},{"type":"null"}]},"tehillim":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"ref":{"oneOf":[{"type":"string"},{"type":"null"}]},"path":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["text","ref","path"]}},"rambam":{"type":"object","properties":{"three":{"type":"object","properties":{"label":{"type":"string"},"refs":{"type":"array","items":{"type":"string"}},"paths":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"null"}]},"description":"Each reference's page on ChassidusHub, null until the catalog has it"}},"required":["label","refs","paths"]},"one":{"type":"object","properties":{"label":{"type":"string"},"refs":{"type":"array","items":{"type":"string"}},"paths":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"null"}]},"description":"Each reference's page on ChassidusHub, null until the catalog has it"}},"required":["label","refs","paths"]},"mitzvos":{"oneOf":[{"type":"object","properties":{"label":{"type":"string"},"refs":{"type":"array","items":{"type":"string"}},"paths":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"null"}]},"description":"Each reference's page on ChassidusHub, null until the catalog has it"}},"required":["label","refs","paths"]},{"type":"null"}]}},"required":["three","one","mitzvos"]}},"required":["date","hebrew","tanya","hayomYom","chumash","tehillim","rambam"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/shiurim":{"get":{"operationId":"shiurim","tags":["Texts"],"summary":"The shiurim's words, each page cut to what is learned: a day's (Chumash by aliyah with Rashi, Tehillim, Tanya, the Rambam's three tracks), or any by Sefaria's references","description":"Give `date` for a day's shiurim, or `ref` (up to ten, with `rashi=1` for a Chumash reference's Rashi too) for any. Each section names what it is (`chumash`, `tehillim`, `tanya`, `three`, `one`, `mitzvos`, or `passage`) and holds its pages, each in its Hebrew only, cut to the stretch learned (`from`, and `to` the first segment after it, null to its end); a Rashi page is marked `rashi`. A reference the catalog has no page for is left out.","x-access":"public","parameters":[{"name":"date","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2026-10-02"]},"description":"The civil day"},{"name":"ref","in":"query","required":false,"schema":{"type":"string","examples":["Exodus 10:1-11"]},"description":"A Sefaria reference; repeat for more"},{"name":"rashi","in":"query","required":false,"schema":{"type":"string","examples":["1"]},"description":"With a Chumash reference, its Rashi too"}],"responses":{"200":{"description":"The shiurim","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"oneOf":[{"type":"string"},{"type":"null"}]},"hebrew":{"oneOf":[{"type":"string"},{"type":"null"}]},"sections":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"parts":{"type":"array","items":{"$ref":"#/components/schemas/Item"}}},"required":["key","label","parts"]}}},"required":["date","hebrew","sections"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/refcounts":{"get":{"operationId":"refCounts","tags":["Items"],"summary":"How many items point at each item through a field (field=work&type=unit: each work's units)","x-access":"public","parameters":[{"name":"field","in":"query","required":true,"schema":{"type":"string"},"description":"The field"},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Only items of this type"}],"responses":{"200":{"description":"Counts by id","content":{"application/json":{"schema":{"type":"object","properties":{"counts":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["counts"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/sitemap":{"get":{"operationId":"sitemaps","tags":["Items"],"summary":"Every sitemap there is: each kind of item with a page of its own, in pages of pageSize items (id order), with when each page last changed","description":"What the site's /sitemap.xml is made from. Kinds: set, author, person, work, unit, event, publication, recording.","x-access":"public","responses":{"200":{"description":"The sitemaps","content":{"application/json":{"schema":{"type":"object","properties":{"pageSize":{"type":"integer"},"sitemaps":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"page":{"type":"integer","minimum":1},"count":{"type":"integer"},"lastmod":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["type","page","count","lastmod"]}}},"required":["pageSize","sitemaps"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/sitemap/{type}/{page}":{"get":{"operationId":"sitemapPage","tags":["Items"],"summary":"One sitemap's items: their ids, paths and when each last changed","x-access":"public","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","description":"A kind of item with a page of its own","enum":["set","author","person","work","unit","event","publication","recording"]}},{"name":"page","in":"path","required":true,"schema":{"type":"integer","description":"From 1","minimum":1}}],"responses":{"200":{"description":"The items","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"page":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"path":{"oneOf":[{"type":"string"},{"type":"null"}]},"lastmod":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","path","lastmod"]}}},"required":["type","page","items"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/works/{id}/outline":{"get":{"operationId":"workOutline","tags":["Items"],"summary":"A work's volumes (its top-level parts), with how many units each holds","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"Parts","content":{"application/json":{"schema":{"type":"object","properties":{"parts":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"units":{"type":"integer"}}}}},"required":["parts"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/works/{id}/parts/{part}":{"get":{"operationId":"workPart","tags":["Items"],"summary":"The units of one volume of a work","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},{"name":"part","in":"path","required":true,"schema":{"type":"string"},"description":"The volume, as the outline names it"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"description":"How many (at most 1000)"}],"responses":{"200":{"description":"Units","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/units/{id}/neighbours":{"get":{"operationId":"unitNeighbours","tags":["Items"],"summary":"The units just before and after a unit in its work's order, across volumes: a sicha's previous and next","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"Each is null at its end of the work, and both for a unit of no work","content":{"application/json":{"schema":{"type":"object","properties":{"previous":{"oneOf":[{"$ref":"#/components/schemas/Item"},{"type":"null"}]},"next":{"oneOf":[{"$ref":"#/components/schemas/Item"},{"type":"null"}]}},"required":["previous","next"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/missing":{"get":{"operationId":"missing","tags":["Projects"],"summary":"The Missing board: farbrengens without a recording or a text, sefarim without a scan, files lost upstream","x-access":"public","parameters":[{"name":"kind","in":"query","required":true,"schema":{"enum":["recordings","texts","scans","files"]},"description":"What is missing"},{"name":"within","in":"query","required":false,"schema":{"type":"string"},"description":"For recordings and texts: a year or a month"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"description":"How many (at most 500)"}],"responses":{"200":{"description":"What is missing","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string"},"total":{"type":"integer"},"items":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["kind","total","items"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/commits":{"get":{"operationId":"listCommits","tags":["Items"],"summary":"Every merge to main after a given one, in order, with what each changed: the way to follow the catalog without webhooks","x-access":"public","x-paged":true,"parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Start after this commit's seq (0: from the start)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"How many (at most 100)"},{"name":"changes","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Carry only so many of each commit's changes (an import's has thousands); `changed` and `types` still count them all"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `next` of the page before"}],"responses":{"200":{"description":"Commits","content":{"application/json":{"schema":{"type":"object","properties":{"commits":{"type":"array","items":{"$ref":"#/components/schemas/Commit"}},"next":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["commits","next"]}}},"headers":{"Link":{"description":"rel=\"next\": the next page","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/dates/parse":{"get":{"operationId":"parseDate","tags":["Search"],"summary":"Read a Hebrew date as people write it","x-access":"public","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","examples":["יו\"ד שבט תשכ\"ב","10 Shvat 5722"]},"description":"The date"}],"responses":{"200":{"description":"The date key, in Hebrew and English","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"string"},"he":{"type":"string"},"en":{"type":"string"}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"422":{"description":"Not a date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/search":{"get":{"operationId":"search","tags":["Search"],"summary":"Search names, text and dates, in Hebrew or English","description":"Ranked by relevance, not paged: ask for more with limit. A query that names a Hebrew date also answers with the date.","x-access":"public","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"The query"},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Only this type"},{"name":"work","in":"query","required":false,"schema":{"type":"string"},"description":"Only items of this sefer (its printings, its sichos)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"How many (at most 100)"}],"responses":{"200":{"description":"Results, and the date the query names if any","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"date":{"oneOf":[{"type":"object","properties":{"key":{"type":"string"},"he":{"type":"string"},"en":{"type":"string"}}},{"type":"null"}]},"results":{"type":"array","items":{"$ref":"#/components/schemas/Item"}}},"required":["query","date","results"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/mafteach":{"get":{"operationId":"mafteach","tags":["Search"],"summary":"A sefer's whole subject index on one page, gathered from its volumes' index pages: every topic once, each volume's places under it with their context and links (the sicha's PDF at that page, the sicha's page here); one first letter's topics, or those a search finds","description":"Built from the index pages as they are now, and kept until one changes. Places a machine read and no person checked are marked machine, volume by volume.","x-access":"public","parameters":[{"name":"index","in":"query","required":true,"schema":{"type":"string"},"description":"The index: a work whose units are its volumes' index pages (an id, or its path, like /likkutei-sichos-mafteach-inyanim)"},{"name":"sefer","in":"query","required":false,"schema":{"type":"string"},"description":"The sefer it indexes (an id or path), for the links to its sichos"},{"name":"letter","in":"query","required":false,"schema":{"type":"string"},"description":"One first letter's topics (the first letter when neither this nor q is given)"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Topics whose name, context or sicha holds these words"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":60},"description":"How many (at most 200)"},{"name":"places","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":400},"description":"Stop the page sooner, at about this many places (never at no topic)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Topics to skip: the `next` of the page before"}],"responses":{"200":{"description":"The index","content":{"application/json":{"schema":{"type":"object","properties":{"index":{"type":"object","additionalProperties":true,"description":"id, path, title"},"letters":{"type":"array","items":{"type":"object","properties":{"letter":{"type":"string"},"topics":{"type":"integer"}},"required":["letter","topics"]}},"totals":{"type":"object","properties":{"topics":{"type":"integer"},"places":{"type":"integer"},"volumes":{"type":"integer"}},"required":["topics","places","volumes"]},"topics":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string"},"letter":{"type":"string"},"volumes":{"type":"array","items":{"type":"object","properties":{"volume":{"type":"integer"},"label":{"type":"string"},"path":{"oneOf":[{"type":"string"},{"type":"null"}]},"machine":{"type":"boolean"},"places":{"type":"array","items":{"type":"object","properties":{"page":{"type":"integer"},"to":{"type":"integer"},"context":{"type":"string"},"pdf":{"type":"string","description":"The sicha's PDF"},"at":{"type":"integer","description":"The page of the PDF where the place is"},"sicha":{"type":"string"},"text":{"type":"string","description":"The sicha's page here"}},"required":["page"]}}},"required":["volume","label","path","machine","places"]}}},"required":["topic","letter","volumes"]}},"found":{"type":"integer"},"offset":{"type":"integer"},"next":{"oneOf":[{"type":"integer"},{"type":"null"}]}},"required":["index","letters","totals","topics","found","offset","next"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/search/moments":{"get":{"operationId":"searchMoments","tags":["Search"],"summary":"Where the words are: lines on scans' pages (open at the line) and paragraphs of texts and transcripts (open at the moment heard)","x-access":"public","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"The words"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"How many (at most 100)"}],"responses":{"200":{"description":"Moments, each saying whether a machine read it and nobody has checked it","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"moments":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["query","moments"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/search/similar":{"get":{"operationId":"searchSimilar","tags":["Search"],"summary":"Search by meaning (embeddings); every result is the machine's guess","description":"`available` is false until it is set up on the server.","x-access":"public","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":1000},"description":"A question or an idea, in Hebrew, Yiddish or English"},{"name":"types","in":"query","required":false,"schema":{"type":"string"},"description":"Some of unit, event, segment, text-page, work, comma separated"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"How many (at most 50)"}],"responses":{"200":{"description":"Results with their score","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"available":{"type":"boolean"},"machine":{"const":true},"model":{"type":"string"},"results":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["query","available","results"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/scans/{id}/text":{"get":{"operationId":"scanText","tags":["Texts"],"summary":"A page of a scan's text: the community page, else the seed layer's; each line with its proofread level","description":"Lines nobody has checked are machine reading (`checked: false`). Withheld when the scan may not be served.","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"The page"}],"responses":{"200":{"description":"The page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanTextPage"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/scans/{id}/progress":{"get":{"operationId":"scanProgress","tags":["Texts"],"summary":"How far each page of a scan is proofread (0, 1 or 2)","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"Pages and levels","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"integer"},"levels":{"type":"array","items":{"type":"integer","minimum":0,"maximum":2}}},"required":["pages","levels"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/scans/{id}/text/fix":{"post":{"operationId":"fixScanLine","tags":["Texts"],"summary":"Fix one line of a scan's text (a suggestion)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer"},"line":{"type":"string","description":"The line's id"},"text":{"type":"string"}},"required":["page","line","text"]}}}},"responses":{"201":{"description":"The suggestion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/scans/{id}/text/confirm":{"post":{"operationId":"confirmScanPage","tags":["Texts"],"summary":"This page is right: raise it a proofreading level, with any fixes (a suggestion)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer"},"fixes":{"type":"object","additionalProperties":{"type":"string"},"description":"Line id to its right text"}},"required":["page"]}}}},"responses":{"201":{"description":"The suggestion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/scans/{id}/ocr":{"post":{"operationId":"uploadOcr","tags":["Texts"],"summary":"Upload your own OCR of a scan (hOCR, ALTO, or plain text with form feeds between pages) as a new layer","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"format":{"enum":["hocr","alto","text"]},"engine":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}},"required":["name","version"]},"firstPage":{"type":"integer","minimum":1},"language":{"type":"string"}},"required":["content","engine"]}}}},"responses":{"201":{"description":"The suggestion, with pages and lines read","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/scans/{id}/text/seed":{"post":{"operationId":"seedScanText","tags":["Texts"],"summary":"Keepers: seed the community text from this OCR layer (checked lines are kept)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"layer":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},"required":["layer"]}}}},"responses":{"201":{"description":"The suggestion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/units/{id}/printings":{"get":{"operationId":"unitPrintings","tags":["Texts"],"summary":"The printings of a unit whose text the catalog has, to compare","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"Printings","content":{"application/json":{"schema":{"type":"object","properties":{"printings":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["printings"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/compare":{"get":{"operationId":"comparePrintings","tags":["Texts"],"summary":"Compare two printings word by word (Hebrew-aware)","x-access":"public","parameters":[{"name":"a","in":"query","required":true,"schema":{"type":"string"},"description":"text:<id> or scan:<id>:<from>-<to>"},{"name":"b","in":"query","required":true,"schema":{"type":"string"},"description":"The other printing"}],"responses":{"200":{"description":"Runs of same, removed and added words","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/units/{id}/translations":{"post":{"operationId":"addTranslation","tags":["Texts"],"summary":"Suggest a translation of a unit, as its own text","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"credit":{"type":"string"},"licence":{"enum":["public-domain","cc0","cc-by","cc-by-nc"]},"translationOf":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"content":{"type":"string","description":"A blank line between paragraphs"},"machine":{"type":"string","description":"The tool, when a machine translated it"}},"required":["language","credit","content"]}}}},"responses":{"201":{"description":"The suggestion made","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/translations/fix":{"post":{"operationId":"fixTranslation","tags":["Texts"],"summary":"Suggest a fix to one paragraph of a translation","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"segment":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"content":{"type":"string"}},"required":["segment","content"]}}}},"responses":{"201":{"description":"The suggestion made","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/hanachos/text":{"post":{"operationId":"addHanachaText","tags":["Texts"],"summary":"A hanacha's words for a farbrengen or sicha (or a new farbrengen), a paragraph to a segment","description":"Words of unsure rights are kept and not shown until a steward decides.\n\nSigned in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"for":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"eventTitle":{"type":"string","description":"For a farbrengen the catalog lacks: its name"},"eventDate":{"type":"string","description":"With eventTitle: its date key"},"content":{"type":"string","description":"A blank line between paragraphs"},"rights":{"enum":["mine","public-domain","free","unsure"]},"language":{"type":"string"},"credit":{"type":"string"}},"required":["content","rights"]}}}},"responses":{"201":{"description":"The suggestion sent for review, and the text","content":{"application/json":{"schema":{"type":"object","properties":{"suggestion":{"type":"integer"},"text":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"event":{"oneOf":[{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},{"type":"null"}]},"publication":{"oneOf":[{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},{"type":"null"}]}},"required":["suggestion","text"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/texts/{sha256}":{"get":{"operationId":"getSourceText","tags":["Texts"],"summary":"A text of a sefer as its source gave it (one chapter or letter, an HTML article)","x-access":"public","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","description":"A file, named by its sha256","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"HTML, shown as a document (sandboxed)","content":{"text/html":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/transcripts":{"get":{"operationId":"transcribedRecordings","tags":["Media"],"summary":"Every recording that has a transcript, the most checked first, then the longest","x-access":"public","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":50},"description":"How many (at most 1000)"}],"responses":{"200":{"description":"The recordings, with how many of their paragraphs people checked and how many are timed word by word","content":{"application/json":{"schema":{"type":"object","properties":{"recordings":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"recording, title, event, durationMs, paragraphs, checked, timedWords"}}},"required":["recordings"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/transcripts/fixes":{"get":{"operationId":"transcriptFixes","tags":["Media"],"summary":"Every transcript fix waiting for approval, to go through together: each paragraph on the site and as the fix would make it, where it is heard, who sent it, and whether you may approve it","description":"No account needed; signed in, a little more.","security":[{},{"token":[]},{"session":[]}],"x-access":"optional","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":200},"description":"How many (at most 200)"}],"responses":{"200":{"description":"The fixes, a farbrengen's together in the order they are heard","content":{"application/json":{"schema":{"type":"object","properties":{"fixes":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"id, number, author, authorName, bot, at, recording, recordingTitle, event, eventPath, eventTitle, date, language, mayApprove, mine, changes: segment, kind (words, check, timing or new), before, after, startMs, endMs, newStartMs"}}},"required":["fixes"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/transcripts/fixes/decide":{"post":{"operationId":"decideTranscriptFixes","tags":["Media"],"summary":"Keep some transcript fixes and remove others in one go: kept ones are approved; removed ones are withdrawn if they are yours, else sent back with the note","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"keep":{"type":"array","items":{"type":"integer"},"description":"Suggestions to approve"},"remove":{"type":"array","items":{"type":"integer"},"description":"Suggestions to take out"},"note":{"type":"string","description":"Said to the people whose fixes are sent back"}}}}}},"responses":{"200":{"description":"What became of each; one that could not be decided says why","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"id, done (kept, withdrawn, sent_back or null), error"}}},"required":["results"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/recordings/{id}/transcript":{"get":{"operationId":"recordingTranscript","tags":["Media"],"summary":"A recording's transcript, with its sync by paragraph and word","description":"A paragraph is machine hearing until a person checks it (`checked`).","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"The transcript","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/recordings/{id}/transcript/history":{"get":{"operationId":"transcriptHistory","tags":["Media"],"summary":"Everything that happened to a recording's transcript, newest first","description":"Each approved change with who made it and what it changed, paragraph by paragraph: `words` (before and after, and whether the whole paragraph was checked), `checked`, `sync` (where it is heard moved) and `made` (the machine's first hearing).","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"The changes","content":{"application/json":{"schema":{"type":"object","properties":{"history":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["history"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/recordings/{id}/transcript/fix":{"post":{"operationId":"fixTranscript","tags":["Media"],"summary":"Fix the words of one paragraph of a transcript (a suggestion)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"segment":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"content":{"type":"string"},"complete":{"type":"boolean","description":"false: only some words were fixed; the paragraph stays machine hearing (default true)"}},"required":["segment","content"]}}}},"responses":{"201":{"description":"The suggestion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/recordings/{id}/sync/anchor":{"post":{"operationId":"anchorSync","tags":["Media"],"summary":"The Rebbe is saying this line now: set a paragraph (or word) at atMs, lock it, move what follows","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"segment":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"atMs":{"type":"integer"},"word":{"type":"integer"}},"required":["segment","atMs"]}}}},"responses":{"201":{"description":"The suggestion and the spans as they now stand","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/recordings/{id}/sync/confirm":{"post":{"operationId":"confirmSync","tags":["Media"],"summary":"The sync is right: mark every paragraph checked","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"201":{"description":"The suggestion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/recordings/batch/hanacha":{"get":{"operationId":"recordingsHanacha","tags":["Media"],"summary":"Several recordings' synced hanachos at once (a farbrengen's parts), by recording; those with none are left out","x-access":"public","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string","description":"Comma separated, at most 200"},"description":"The recordings"}],"responses":{"200":{"description":"Each hanacha and its sync, by recording","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"object","additionalProperties":{"type":"object","additionalProperties":true}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/recordings/{id}/hanacha":{"get":{"operationId":"recordingHanacha","tags":["Media"],"summary":"The hanacha synced to this recording, paragraph by paragraph","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"The hanacha and its sync","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/batch":{"get":{"operationId":"getFiles","tags":["Files"],"summary":"Several files at once, in the order asked (missing ones left out)","x-access":"public","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string","description":"Comma separated sha256s, at most 200"},"description":"The files"}],"responses":{"200":{"description":"The files","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/File"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/{sha256}":{"get":{"operationId":"getFile","tags":["Files"],"summary":"A file's size, rights and address, what was made from it, and its page fix","x-access":"public","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","description":"A file, named by its sha256","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/{sha256}/similar":{"get":{"operationId":"similarFiles","tags":["Files"],"summary":"Held files that look like this one (the same scan or recording in other bytes): a machine's guess","x-access":"public","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","description":"A file, named by its sha256","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"Similar files, with the items that use each","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/page-fixes/drive/{id}":{"get":{"operationId":"driveFix","tags":["Files"],"summary":"What a PDF on Google Drive needs to read straight, by its Drive id, or the reading copy to open instead","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A Google Drive file id","pattern":"^[\\w-]{10,}$"}}],"responses":{"200":{"description":"The page fix","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/drive/{id}":{"get":{"operationId":"driveFile","tags":["Files"],"summary":"A Google Drive file the catalog links to (a hanacha's PDF, an Otzros scan), read for the site's reader and player","description":"Only files an item links to. Supports Range requests; the whole file is kept at the edge for a week. Files over the size ChassidusHub passes on (300 MB) answer 413.","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A Google Drive file id","pattern":"^[\\w-]{10,64}$"}}],"responses":{"200":{"description":"The bytes","content":{"application/octet-stream":{"schema":{"type":"string"}}}},"206":{"description":"Part of the bytes (Range)"},"400":{"$ref":"#/components/responses/400"},"404":{"description":"No item links to this file"},"413":{"description":"Too large to pass on"},"429":{"description":"Too many files read from Drive this minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Google Drive did not give the file"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/objects/{sha256}":{"get":{"operationId":"getObject","tags":["Files"],"summary":"A file's bytes, while its rights let it be served","description":"Supports Range requests. `X-Credit` carries the credit the rights ask for.","x-access":"public","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","description":"A file, named by its sha256","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"The bytes","content":{"application/octet-stream":{"schema":{"type":"string"}}}},"206":{"description":"Part of the bytes (Range)"},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"416":{"description":"A range outside the file"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/manifests/{collection}/{name}":{"get":{"operationId":"getManifest","tags":["Files"],"summary":"A published manifest: reading copies, page fixes (facts about files, open like the catalog)","x-access":"public","parameters":[{"name":"collection","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","description":"ends in .json","pattern":"^[a-z0-9-]+\\.json$"}}],"responses":{"200":{"description":"The manifest","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/scans/{id}/pages":{"get":{"operationId":"scanPages","tags":["Files"],"summary":"A served scan's page images and thumbnails, and its IIIF manifest","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"Pages","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/manifests/iiif/{file}":{"get":{"operationId":"iiifManifest","tags":["Libraries"],"summary":"A served scan as a IIIF Presentation 3 manifest, for any IIIF viewer","x-access":"public","parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string","description":"The scan's id and .json","pattern":"^rh-[0-9a-z]+\\.json$"}}],"responses":{"200":{"description":"The manifest","content":{"application/ld+json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/uploads":{"post":{"operationId":"upload","tags":["Files"],"summary":"Add a file: a recording of a farbrengen; a hanacha's PDF for a farbrengen or sicha; a scan (another scan of a printing, a new printing of a sefer, a teshura); or other material (a new sefer, a letter, a document)","description":"The file is the body, with its Content-Type (audio/…, application/pdf). A recording or hanacha may name a farbrengen the catalog lacks (eventTitle and eventDate) instead of `for`. New accounts wait a day, and everyone adds so many a day.\n\nSigned in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"what","in":"query","required":true,"schema":{"enum":["recording","hanacha","scan","document"]},"description":"What it is"},{"name":"for","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"The farbrengen, sicha, sefer, printing or Teshuros set it is added to"},{"name":"eventTitle","in":"query","required":false,"schema":{"type":"string","maxLength":300},"description":"For a recording or hanacha of a farbrengen the catalog lacks: its name"},{"name":"eventDate","in":"query","required":false,"schema":{"type":"string","examples":["5742-05-10"]},"description":"With eventTitle: its date key"},{"name":"kind","in":"query","required":false,"schema":{"enum":["bilti-mugah","mugah","maamar","hagahos","hosofos","english","other"],"default":"bilti-mugah"},"description":"For a hanacha: what kind"},{"name":"set","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"For a document: the set it belongs in"},{"name":"author","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"For a new sefer: its author"},{"name":"genre","in":"query","required":false,"schema":{"type":"string"},"description":"For a new sefer: its genre"},{"name":"unit","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"For a letter: the letter the catalog has that it reproduces"},{"name":"rights","in":"query","required":true,"schema":{"enum":["mine","free","public-domain","unsure"]},"description":"What you know of its rights"},{"name":"as","in":"query","required":false,"schema":{"enum":["scan-of","printing","teshura","sefer","letter","document"]},"description":"For a scan: scan-of, printing or teshura. For a document: sefer, letter or document"},{"name":"title","in":"query","required":false,"schema":{"type":"string"},"description":"Its name"},{"name":"publication","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"For scan-of: the printing"},{"name":"publisher","in":"query","required":false,"schema":{"type":"string"},"description":"For a printing"},{"name":"year","in":"query","required":false,"schema":{"type":"string"},"description":"For a printing: a Hebrew or civil year"},{"name":"printing","in":"query","required":false,"schema":{"type":"integer"},"description":"For a printing: 1 for the first"},{"name":"families","in":"query","required":false,"schema":{"type":"string"},"description":"For a teshura: its families, as printed"},{"name":"simcha","in":"query","required":false,"schema":{"type":"string"},"description":"For a teshura: wedding, bar-mitzvah, and so on"},{"name":"date","in":"query","required":false,"schema":{"type":"string"},"description":"For a teshura: the simcha's date key; for a letter or document, its date"}],"requestBody":{"required":true,"description":"The file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"We already have this file: where it is"},"201":{"description":"Stored, and a suggestion sent for review","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"description":"The day's allowance is used","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/uploads/check":{"post":{"operationId":"checkUpload","tags":["Files"],"summary":"Before an upload: whether we have it (its sha256, a few page hashes) and what it likely is","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"for":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"sha256":{"type":"string"},"pageHashes":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"null"}]}},"title":{"type":"string"}},"required":["for"]}}}},"responses":{"200":{"description":"The guess, files already held that look like it, and the sefer's printings","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/uploads/propose":{"post":{"operationId":"proposeUpload","tags":["Files"],"summary":"Before adding something new: the machine's guess of what it is and where it belongs, from its name (a date in it, words of a title), and files already held that look like it","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"what":{"enum":["hanacha","recording","document"]},"name":{"type":"string","description":"Its file name or title"},"sha256":{"type":"string","description":"A file, named by its sha256","pattern":"^[0-9a-f]{64}$"},"pageHashes":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"required":["what"]}}}},"responses":{"200":{"description":"The date read, what it likely is, the items it may belong to, and where the file already is","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/files/{sha256}/about":{"get":{"operationId":"fileAbout","tags":["Files"],"summary":"A file's own page: its rights, where it came from, what was made from it, and what uses it","x-access":"public","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","description":"A file, named by its sha256","pattern":"^[0-9a-f]{64}$"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"How many (at most 500)"}],"responses":{"200":{"description":"The file, and the items using it with their total","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/covers":{"get":{"operationId":"covers","tags":["Files"],"summary":"Sefarim's covers, drawn from their title pages, while their PDFs are served or linked","description":"A cover is `machine: true` until a person chose its page. A cover drawn from a PDF ChassidusHub only links to is served; the PDF is not (its file page links to the source).","x-access":"public","parameters":[{"name":"ids","in":"query","required":false,"schema":{"type":"string","description":"Comma separated, at most 200"},"description":"The sefarim"}],"responses":{"200":{"description":"Covers by id (none for a sefer without one)","content":{"application/json":{"schema":{"type":"object","properties":{"covers":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Cover"}}},"required":["covers"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/works/{id}/cover":{"get":{"operationId":"workCover","tags":["Files"],"summary":"A sefer's cover, the page a person chose, and the PDFs (served, or linked) its title page may be chosen from","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"The cover and its sources","content":{"application/json":{"schema":{"type":"object","properties":{"work":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"chosen":{"oneOf":[{"type":"object","properties":{"file":{"type":"string","description":"A file, named by its sha256","pattern":"^[0-9a-f]{64}$"},"page":{"type":"integer"}},"required":["file","page"]},{"type":"null"}]},"cover":{"oneOf":[{"$ref":"#/components/schemas/Cover"},{"type":"null"}]},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["work","chosen","cover","sources"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions":{"get":{"operationId":"listSuggestions","tags":["Suggestions"],"summary":"Suggestions, oldest sent first, by status or author; with `state`, the list of conversations, newest first (numbers, reviewers, approvals, the issues each closes) with counts","x-access":"public","x-paged":true,"parameters":[{"name":"status","in":"query","required":false,"schema":{"enum":["draft","open","merged","sent_back","withdrawn"]}},{"name":"state","in":"query","required":false,"schema":{"enum":["open","closed","all"]},"description":"The conversation list: open (waiting or sent back) or closed (merged or withdrawn)"},{"name":"author","in":"query","required":false,"schema":{"type":"string"},"description":"An account id, or (with state) a handle"},{"name":"reviewer","in":"query","required":false,"schema":{"type":"string"},"description":"With state: asked to review, or reviewed (a handle)"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"With state: words in the title, or #number"},{"name":"about","in":"query","required":false,"schema":{"type":"string","description":"Comma separated, at most 500"},"description":"With state: only suggestions that change these items, or what is in them (a sefer's sichos and their texts, a sicha's paragraphs, a farbrengen's sichos)"},{"name":"postReview","in":"query","required":false,"schema":{"enum":["true","false"]},"description":"true: live changes waiting to be reviewed after"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"description":"How many (at most 500)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `next` of the page before"}],"responses":{"200":{"description":"Suggestions (with state: SuggestionListItem, people and counts)","content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Suggestion"},{"$ref":"#/components/schemas/SuggestionListItem"}]}},"people":{"type":"object","additionalProperties":true,"description":"Who is named, by account id: name and handle"},"counts":{"type":"object","properties":{"open":{"type":"integer"},"closed":{"type":"integer"}}},"next":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["suggestions","next"]}}},"headers":{"Link":{"description":"rel=\"next\": the next page","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createSuggestion","tags":["Suggestions"],"summary":"Start a suggestion (a draft): add items to it, then submit it","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"project":{"type":"integer"}},"required":["title"]}}}},"responses":{"201":{"description":"The draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/quick":{"post":{"operationId":"suggestFix","tags":["Suggestions"],"summary":"Suggest a fix in one step: a new version of one item, with a few words on why, sent for review","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"data":{"type":"object","additionalProperties":true,"description":"The item's whole new data"},"title":{"type":"string","maxLength":200},"note":{"type":"string","maxLength":2000}},"required":["entityId","data"]}}}},"responses":{"201":{"description":"The suggestion with its checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}":{"get":{"operationId":"getSuggestion","tags":["Suggestions"],"summary":"The review view: each item before and after, clashes with main, and the reviewer's advice (machine-written, `machine: true`). A page of items at a time (`entries`, from `offset`), with `total`, `next` (the offset of the next page, or null) and, with summary=1, `summary`: the items grouped by how they change (\"500 units: links on the media proxy became links on Drive\"), with a few examples of each","description":"No account needed; signed in, a little more.","security":[{},{"token":[]},{"session":[]}],"x-access":"optional","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Items to skip: the `next` of the page before"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":25},"description":"How many (at most 200)"},{"name":"summary","in":"query","required":false,"schema":{"enum":["1"]},"description":"With 1: also `summary`, every item grouped by how it changes (all of them are read and compared for it)"},{"name":"brief","in":"query","required":false,"schema":{"enum":["1"]},"description":"With 1: each item's facts, not its words (`before` and `after` without `body`; what changed is whole in `changes`), for a feed"}],"responses":{"200":{"description":"The suggestion","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"changeset, entries (this page), total, offset, limit, next, summary, reviews, names, items (the items the changes on this page point at: type and name, by id), people, files, mayApprove, mine, advice"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"editSuggestion","tags":["Suggestions"],"summary":"Change the title or description of your suggestion (@mentions and \"Fixes #12\" are read again)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"The suggestion","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/conversation":{"get":{"operationId":"suggestionConversation","tags":["Suggestions"],"summary":"A suggestion's timeline (comments, reviews, events), the reviewers asked, and the issues it closes","description":"No account needed; signed in, a little more.","security":[{},{"token":[]},{"session":[]}],"x-access":"optional","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"responses":{"200":{"description":"The conversation","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"integer"},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true}},"people":{"type":"object","additionalProperties":true},"reviewRequests":{"type":"array","items":{"type":"object","additionalProperties":true}},"fixes":{"type":"array","items":{"type":"object","additionalProperties":true}},"subscribed":{"type":"boolean"}},"required":["number","timeline"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/comments":{"post":{"operationId":"commentOnSuggestion","tags":["Suggestions"],"summary":"Comment on a suggestion, answer a comment, or comment on one field of one item","description":"@handles are told (their inbox), and #12 links to that suggestion or issue.\n\nSigned in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"parent":{"type":"integer","description":"The comment this answers"},"anchor":{"type":"object","properties":{"entity":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"field":{"type":"string"}},"required":["entity","field"]}},"required":["body"]}}}},"responses":{"201":{"description":"The comment id","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"}},"required":["id"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/reviews":{"post":{"operationId":"reviewSuggestion","tags":["Suggestions"],"summary":"Review: approve (it goes into the catalog, where you may merge it), request changes (sent back), or comment; with comments on fields","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"enum":["approve","request_changes","comment"]},"body":{"type":"string"},"comments":{"type":"array","items":{"type":"object","properties":{"entity":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"field":{"type":"string"},"body":{"type":"string"}},"required":["entity","field","body"]}},"resolutions":{"type":"object","additionalProperties":true,"description":"For each item, how each clashing field is settled: {item: {field: {take: \"ours\" (the site) | \"theirs\" (the suggestion)}}}; `*` stands for every item or every field not named"}},"required":["verdict"]}}}},"responses":{"201":{"description":"The review, the new status, and the commit when approved","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"409":{"description":"Clashes that need a decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/review-requests":{"post":{"operationId":"requestReview","tags":["Suggestions"],"summary":"Ask people to review (asking again asks again)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reviewers":{"type":"array","items":{"type":"string","description":"A handle"},"description":"Handles"}},"required":["reviewers"]}}}},"responses":{"201":{"description":"Who was asked","content":{"application/json":{"schema":{"type":"object","properties":{"requested":{"type":"array","items":{"type":"string"}}},"required":["requested"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/review-requests/{username}":{"delete":{"operationId":"removeReviewRequest","tags":["Suggestions"],"summary":"Stop asking someone to review","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}},{"name":"username","in":"path","required":true,"schema":{"type":"string","description":"A handle, without the @","pattern":"^[A-Za-z0-9][A-Za-z0-9-]{0,38}[A-Za-z0-9]$"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/items":{"put":{"operationId":"putSuggestionItem","tags":["Suggestions"],"summary":"Add or change one item in a draft suggestion (data null deletes it)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"type":{"type":"string"},"data":{"type":["object","null"]},"path":{"type":["string","null"]}},"required":["type","data"]}}}},"responses":{"200":{"description":"The item id","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},"required":["id"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/submit":{"post":{"operationId":"submitSuggestion","tags":["Suggestions"],"summary":"Send for review (runs the automatic checks)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"responses":{"200":{"description":"The suggestion with its checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/approve":{"post":{"operationId":"approveSuggestion","tags":["Suggestions"],"summary":"Approve and merge (keepers of its sets, stewards)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"resolutions":{"type":"object","additionalProperties":true,"description":"For each item, how each clashing field is settled: {item: {field: {take: \"ours\" (the site) | \"theirs\" (the suggestion)}}}; `*` stands for every item or every field not named"},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"The commit","content":{"application/json":{"schema":{"type":"object","properties":{"commit":{"oneOf":[{"type":"integer"},{"type":"null"}]}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"409":{"description":"Clashes that need a decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/send-back":{"post":{"operationId":"sendBackSuggestion","tags":["Suggestions"],"summary":"Send back with a note","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"}}}}}},"responses":{"200":{"description":"Sent back","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/review-live":{"post":{"operationId":"reviewLive","tags":["Suggestions"],"summary":"Review a live change after it went live: keep it (approve) or undo it (revert)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"enum":["approve","revert"]},"note":{"type":"string"}},"required":["verdict"]}}}},"responses":{"200":{"description":"Kept, or the suggestion that undoes it","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/withdraw":{"post":{"operationId":"withdrawSuggestion","tags":["Suggestions"],"summary":"Withdraw your suggestion","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"responses":{"200":{"description":"Withdrawn","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/reopen":{"post":{"operationId":"reopenSuggestion","tags":["Suggestions"],"summary":"Undo a withdrawal: your suggestion is open for review again (its checks run again)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"responses":{"200":{"description":"The suggestion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/{id}/revert":{"post":{"operationId":"revertSuggestion","tags":["Suggestions"],"summary":"Undo a merged suggestion (a new suggestion that reverses it)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The suggestion","minimum":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"The revert","content":{"application/json":{"schema":{"type":"object","properties":{"changeset":{"type":"integer"},"commit":{"oneOf":[{"type":"integer"},{"type":"null"}]}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/shaar":{"post":{"operationId":"suggestShaar","tags":["Suggestions"],"summary":"A sefer's shaar, the whole file, sent for review; a file the catalog cannot read is refused with each line that is wrong (`detail.problems`)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"text":{"type":"string","description":"The whole shaar file"},"before":{"type":"string","description":"The file as the person opened it; a change since answers 409"},"title":{"type":"string"},"note":{"type":"string"}},"required":["entityId","text"]}}}},"responses":{"201":{"description":"The suggestion sent for review (merged at once where its author may)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"409":{"description":"The shaar changed since it was opened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/words":{"post":{"operationId":"suggestWords","tags":["Suggestions"],"summary":"A page's words fixed segment by segment: one segment's new words, a segment added after it or taken out, a page's first words, or a machine's segment checked as right (`check`), sent for review","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"change":{"enum":["edit","add","remove","start","check"]},"version":{"type":"string"},"segment":{"type":"string"},"text":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Runs: { text, marks?, href? }, { note }, { marker }, { br: true }, { eol, split?, page?, box? }"},"before":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"The segment as the person saw it; a change since answers 409"},"kind":{"enum":["paragraph","heading","verse","item"]},"language":{"type":"string"},"title":{"type":"string"},"note":{"type":"string"}},"required":["entityId","change"]}}}},"responses":{"201":{"description":"The suggestion sent for review (merged at once where its author may)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"409":{"description":"The segment changed since it was opened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/combine":{"post":{"operationId":"combineSuggestions","tags":["Suggestions"],"summary":"Combine several of your own suggestions into one, as a pull request holds many commits","description":"Their changes are applied in the order they were made; changes to different words of one text are all kept, and where a later change rewrites an earlier one the later one stands. The suggestions combined are withdrawn.\n\nSigned in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"integer"},"description":"Their ids (2 to 100), all yours and not yet approved"},"title":{"type":"string","maxLength":200}},"required":["suggestions"]}}}},"responses":{"201":{"description":"The one suggestion, sent for review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestion"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/suggestions/contents-map":{"post":{"operationId":"mapContents","tags":["Suggestions"],"summary":"Map pages of a publication to the unit they hold (an existing unit, a new one, or words)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"publication":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"pages":{"type":"object","properties":{"from":{"type":"integer"},"to":{"type":"integer"},"scheme":{"enum":["printed","pdf"]}},"required":["from","to"]},"unit":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"newUnit":{"type":"object","properties":{"work":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"label":{"type":"object","additionalProperties":true},"date":{"type":"string"}}},"label":{"type":"object","additionalProperties":true}},"required":["publication","pages"]}}}},"responses":{"201":{"description":"The suggestion sent for review","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/machine":{"get":{"operationId":"machineSummary","tags":["Machine"],"summary":"What waits for the machines (OCR, transcription), what is left for them, and what they did this week","x-access":"public","responses":{"200":{"description":"By kind: waiting, running, done and failed this week, and the backlog not done yet: served scans; recordings served or heard at another site","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/machine/training":{"get":{"operationId":"trainingSummary","tags":["Machine"],"summary":"The next Rebbe Whisper's training data so far: every transcript paragraph of the Rebbe speaking that a person checked or fixed, waiting fixes too, as clips","description":"Hours and clips (gold: words and timing checked by a person; silver: words checked, timing by machine; review: how many are checked, fixed in part, or waiting for review), train and test hours, what was left out and why, and with since, the hours checked since then.","x-access":"public","parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"string"},"description":"A date: also count the hours checked since then"}],"responses":{"200":{"description":"The summary","content":{"application/json":{"schema":{"type":"object","properties":{"clips":{"type":"integer"},"hours":{"type":"number"},"gold":{"type":"integer"},"silver":{"type":"integer"},"review":{"type":"object","properties":{"checked":{"type":"integer"},"edited":{"type":"integer"},"pending":{"type":"integer"}},"required":["checked","edited","pending"]},"trainHours":{"type":"number"},"testHours":{"type":"number"},"recordings":{"type":"integer"},"newHours":{"oneOf":[{"type":"number"},{"type":"null"}]},"skipped":{"type":"object","additionalProperties":true},"goal":{"type":"object","additionalProperties":true,"description":"What the next model waits for: hours and farbrengens checked since the last one, against the target, and the farbrengens to check next (the most wanted first)"}},"required":["clips","hours","gold","silver","review","trainHours","testHours","recordings","newHours","skipped","goal"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/machine/to-check":{"get":{"operationId":"machineToCheck","tags":["Machine"],"summary":"What the machines wrote that no person has checked yet: farbrengens with unchecked transcript paragraphs, scans with pages read by OCR and not yet proofread, pages whose words a machine read with segments nobody checked, the newest first","x-access":"public","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"How many (at most 200)"}],"responses":{"200":{"description":"The lists, and how many in all","content":{"application/json":{"schema":{"type":"object","properties":{"transcripts":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"path":{"oneOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"object","additionalProperties":true},"date":{"oneOf":[{"type":"string"},{"type":"null"}]},"paragraphs":{"type":"integer"},"checked":{"type":"integer"},"made":{"type":"string","description":"When the machine last wrote a transcript of it"}},"required":["event","path","title","date","paragraphs","checked","made"]}},"scans":{"type":"array","items":{"type":"object","properties":{"scan":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"publication":{"oneOf":[{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},{"type":"null"}]},"title":{"type":"object","additionalProperties":true},"pages":{"type":"integer"},"checked":{"type":"integer"},"made":{"type":"string"}},"required":["scan","publication","title","pages","checked","made"]}},"texts":{"type":"array","items":{"type":"object","properties":{"entity":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"type":{"type":"string"},"path":{"oneOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"object","additionalProperties":true},"label":{"type":"object","additionalProperties":true},"segments":{"type":"integer","description":"Segments the machine labelled one by one (0 when only the version is labelled)"},"checked":{"type":"integer"},"made":{"type":"string"}},"required":["entity","type","path","title","label","segments","checked","made"]}},"totals":{"type":"object","properties":{"transcripts":{"type":"integer"},"paragraphs":{"type":"integer"},"scans":{"type":"integer"},"pages":{"type":"integer"},"texts":{"type":"integer"},"entries":{"type":"integer"}},"required":["transcripts","paragraphs","scans","pages","texts","entries"]}},"required":["transcripts","scans","texts","totals"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/machine/training/clips":{"get":{"operationId":"trainingClips","tags":["Machine"],"summary":"The training clips, one JSON object a line, as the training script reads them (audio, start, end, text, split, quality, review)","x-access":"public","parameters":[{"name":"carried","in":"query","required":false,"schema":{"enum":["1"]},"description":"With 1: fixed paragraphs cut by the word times the fix carried over too (marked timing: carried), for a training run that aligns them again"}],"responses":{"200":{"description":"JSON lines","content":{"application/x-ndjson":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/machine/requests":{"get":{"operationId":"machineRequests","tags":["Machine"],"summary":"Requests for the machines, the waiting ones in the order they are taken","x-access":"public","parameters":[{"name":"kind","in":"query","required":false,"schema":{"enum":["ocr","transcript"]}},{"name":"status","in":"query","required":false,"schema":{"enum":["waiting","running","done","failed"]}},{"name":"item","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"Requests for one item"},{"name":"items","in":"query","required":false,"schema":{"type":"string","description":"Ids, comma separated (up to 100)"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"How many (at most 200)"}],"responses":{"200":{"description":"The requests","content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","items":{"$ref":"#/components/schemas/MachineRequest"}}},"required":["requests"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"requestMachineWork","tags":["Machine"],"summary":"Ask the machine to read a scan (ocr) or transcribe a recording (transcript)","description":"Free CPU engines only; what they make is labelled as machine output until people check it. Asking for what already waits joins that request (200).\n\nSigned in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"enum":["ocr","transcript"]},"item":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}},"required":["kind","item"]}}}},"responses":{"201":{"description":"The request, its place in line, and whether the machine starts at once","content":{"application/json":{"schema":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/MachineRequest"},"created":{"type":"boolean"},"startsAtOnce":{"type":"boolean"}},"required":["request","created","startsAtOnce"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tree":{"get":{"operationId":"catalogTree","tags":["Organize"],"summary":"The catalog as a tree: the top sets (or one set or sefer), the sets and items under them, and how much each holds","x-access":"public","parameters":[{"name":"root","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"A set or a sefer (work); left out, the top sets"},{"name":"depth","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":4,"default":1},"description":"How many levels down"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"How many (at most 500)"}],"responses":{"200":{"description":"The tree","content":{"application/json":{"schema":{"type":"object","properties":{"root":{"oneOf":[{"$ref":"#/components/schemas/TreeNode"},{"type":"null"}]},"children":{"type":"array","items":{"$ref":"#/components/schemas/TreeNode"}},"more":{"type":"integer","description":"Children left out past the limit"}},"required":["root","children","more"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/organize/preview":{"post":{"operationId":"previewOrganize","tags":["Organize"],"summary":"What a plan of moves, renames, orderings, new sets and merges would change, item by item, saved nowhere","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizePlan"}}}},"responses":{"200":{"description":"The change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizePreview"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/organize":{"post":{"operationId":"organize","tags":["Organize"],"summary":"Organize the catalog: a plan becomes one suggestion, sent for review (apply: true approves it at once where you may approve it yourself)","description":"Operations: move, move-up, rename, reorder, create-set, delete-set, merge, split, addition, official. Every old path redirects once it is approved; a merged item's paths lead to the item it was merged into.\n\nSigned in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizePlan"}}}},"responses":{"201":{"description":"The suggestion, whether it was merged, and the change","content":{"application/json":{"schema":{"type":"object","properties":{"suggestion":{"$ref":"#/components/schemas/Suggestion"},"merged":{"type":"boolean"},"mayApprove":{"type":"boolean","description":"Whether you may approve it yourself"},"preview":{"$ref":"#/components/schemas/OrganizePreview"}},"required":["suggestion","merged","preview"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/entities/{id}/talk":{"get":{"operationId":"itemTalk","tags":["Talk"],"summary":"An item's talk page: the conversation about it","x-access":"public","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"responses":{"200":{"description":"Comments, oldest first, replies by parent","content":{"application/json":{"schema":{"type":"object","properties":{"talk":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}}},"required":["talk"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"commentOnItem","tags":["Talk"],"summary":"Comment on an item's talk page","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"parent":{"type":"integer","description":"The comment this answers"}},"required":["body"]}}}},"responses":{"201":{"description":"The comment id","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"}},"required":["id"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/comments/{id}/hide":{"post":{"operationId":"hideComment","tags":["Talk"],"summary":"Hide a comment (its author, or a steward)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The comment","minimum":1}}],"responses":{"200":{"description":"Hidden","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/comments/{id}":{"patch":{"operationId":"editComment","tags":["Talk"],"summary":"Change your own comment (on a talk page, a suggestion or an issue)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The comment","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000}},"required":["body"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/comments/{id}/resolve":{"post":{"operationId":"resolveComment","tags":["Suggestions"],"summary":"Resolve (or unresolve) a comment on a suggestion's field","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The comment","minimum":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"resolved":{"type":"boolean","description":"false to unresolve"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/reports":{"post":{"operationId":"report","tags":["Reports"],"summary":"Report a problem (no account needed: a captcha and an hourly limit instead)","description":"No account needed; signed in, a little more.","security":[{},{"token":[]},{"session":[]}],"x-access":"optional","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"reason":{"enum":["wrong-fact","missing-page","bad-scan","audio-problem","wrong-text","duplicate","rights","offensive","other"]},"note":{"type":"string","maxLength":10000},"title":{"type":"string","description":"A title of its own, as an issue","maxLength":200},"captcha":{"type":"string","description":"A Turnstile token, when not signed in"}},"required":["reason"]}}}},"responses":{"201":{"description":"The report id, and its number as an issue (#12)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"number":{"oneOf":[{"type":"integer"},{"type":"null"}]}},"required":["id","number"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"description":"Too many reports from one address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"listReports","tags":["Reports"],"summary":"A set's inbox of reports (stewards, and the set's keepers)","description":"Signed in: an API token (read scope is enough), or the site's session.","security":[{"token":["read"]},{"session":[]}],"x-access":"read","parameters":[{"name":"set","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"A set"},{"name":"status","in":"query","required":false,"schema":{"enum":["open","resolved","dismissed"]}}],"responses":{"200":{"description":"Reports, never who sent them","content":{"application/json":{"schema":{"type":"object","properties":{"reports":{"type":"array","items":{"type":"object","additionalProperties":true}},"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}}},"required":["reports","items"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/reports/{id}/close":{"post":{"operationId":"closeReport","tags":["Reports"],"summary":"Resolve or dismiss a report (keepers)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The report","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"enum":["resolved","dismissed"]},"changeset":{"type":"integer","description":"The suggestion that fixed it"},"note":{"type":"string"}},"required":["outcome"]}}}},"responses":{"200":{"description":"Closed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/takedowns":{"post":{"operationId":"requestTakedown","tags":["Reports"],"summary":"Ask for a file to stop being served (no account needed); stewards answer within two weeks","x-access":"public","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string","description":"The address of its page, an id, or the file address"},"name":{"type":"string"},"email":{"type":"string"},"relation":{"enum":["rights-holder","family","representative","other"]},"statement":{"type":"string","minLength":10,"maxLength":4000},"captcha":{"type":"string"}},"required":["target","name","email","relation","statement"]}}}},"responses":{"201":{"description":"The request id","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"answerWithinDays":{"type":"integer"}},"required":["id"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"description":"Too many requests from one address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/teshuros/{id}/family-request":{"post":{"operationId":"familyRequest","tags":["Reports"],"summary":"A family's request that a teshura not be shown (no account needed): its scans stop being served at once, and stewards review it","description":"No account needed; signed in, a little more.","security":[{},{"token":[]},{"session":[]}],"x-access":"optional","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"relation":{"type":"string"},"note":{"type":"string"},"contact":{"type":"string"},"captcha":{"type":"string"}}}}}},"responses":{"201":{"description":"The report id and how many files were paused","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"integer"},"paused":{"type":"integer"}},"required":["report","paused"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"description":"Too many requests from one address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/issues":{"get":{"operationId":"listIssues","tags":["Issues"],"summary":"Issues, newest first, with open and closed counts; private ones only for those who may read them","description":"No account needed; signed in, a little more.","security":[{},{"token":[]},{"session":[]}],"x-access":"optional","x-paged":true,"parameters":[{"name":"state","in":"query","required":false,"schema":{"enum":["open","closed","all"]},"description":"open (the default), closed or all"},{"name":"label","in":"query","required":false,"schema":{"type":"string"},"description":"Label names, comma separated"},{"name":"type","in":"query","required":false,"schema":{"enum":["wrong-fact","missing-page","bad-scan","audio-problem","wrong-text","duplicate","rights","offensive","other"]},"description":"The kind of report"},{"name":"set","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"Only about items in this set"},{"name":"entity","in":"query","required":false,"schema":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"description":"Only about this item"},{"name":"assignee","in":"query","required":false,"schema":{"type":"string"},"description":"A handle, or none"},{"name":"author","in":"query","required":false,"schema":{"type":"string"},"description":"A handle"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Words, or #number"},{"name":"before","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Deprecated: the same as a cursor, as a number"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30},"description":"How many (at most 100)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `next` of the page before"}],"responses":{"200":{"description":"A page of issues","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"people":{"type":"object","additionalProperties":true},"counts":{"type":"object","properties":{"open":{"type":"integer"},"closed":{"type":"integer"}},"required":["open","closed"]},"next":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["items","counts","next"]}}},"headers":{"Link":{"description":"rel=\"next\": the next page","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"openIssue","tags":["Issues"],"summary":"Open an issue (about an item, or the catalog at large)","description":"Reports of rights or of something offensive are private: stewards and the set's keepers read them.\n\nSigned in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"body":{"type":"string","maxLength":10000},"type":{"enum":["wrong-fact","missing-page","bad-scan","audio-problem","wrong-text","duplicate","rights","offensive","other"]},"entityId":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"labels":{"type":"array","items":{"type":"string"}},"private":{"type":"boolean","description":"Keep it for stewards and keepers"}},"required":["title"]}}}},"responses":{"201":{"description":"The issue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Issue"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/issues/templates":{"get":{"operationId":"issueTemplates","tags":["Issues"],"summary":"The kinds of issue and the words each starts with","x-access":"public","responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["templates"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/issues/{number}":{"get":{"operationId":"getIssue","tags":["Issues"],"summary":"An issue, its timeline, what the reader may do, and the suggestions that close it","description":"No account needed; signed in, a little more.","security":[{},{"token":[]},{"session":[]}],"x-access":"optional","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"integer","description":"The issue","minimum":1}}],"responses":{"200":{"description":"The issue","content":{"application/json":{"schema":{"type":"object","properties":{"issue":{"$ref":"#/components/schemas/Issue"},"rights":{"type":"object","additionalProperties":true},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true}},"people":{"type":"object","additionalProperties":true}},"required":["issue"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"editIssue","tags":["Issues"],"summary":"Change its title or words (its author, keepers, stewards)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"integer","description":"The issue","minimum":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"body":{"type":"string"}}}}}},"responses":{"200":{"description":"The issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/issues/{number}/state":{"post":{"operationId":"setIssueState","tags":["Issues"],"summary":"Close as completed or not planned, or reopen","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"integer","description":"The issue","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"enum":["open","completed","not_planned"]},"note":{"type":"string","maxLength":2000}},"required":["state"]}}}},"responses":{"200":{"description":"The issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/issues/{number}/labels":{"put":{"operationId":"setIssueLabels","tags":["Issues"],"summary":"Set its labels (keepers, stewards, trusted people)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"integer","description":"The issue","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"string"}}},"required":["labels"]}}}},"responses":{"200":{"description":"The issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/issues/{number}/assignees":{"put":{"operationId":"setIssueAssignees","tags":["Issues"],"summary":"Set who it is assigned to (yourself; others when you may triage)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"integer","description":"The issue","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignees":{"type":"array","items":{"type":"string","description":"A handle"}}},"required":["assignees"]}}}},"responses":{"200":{"description":"The issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/issues/{number}/visibility":{"post":{"operationId":"setIssueVisibility","tags":["Issues"],"summary":"Make it private or public (stewards and keepers)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"integer","description":"The issue","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"private":{"type":"boolean"}},"required":["private"]}}}},"responses":{"200":{"description":"The issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/issues/{number}/comments":{"post":{"operationId":"commentOnIssue","tags":["Issues"],"summary":"Comment on an issue, or answer a comment","description":"@handles are told (their inbox), and #12 links to that suggestion or issue.\n\nSigned in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"integer","description":"The issue","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"parent":{"type":"integer","description":"The comment this answers"}},"required":["body"]}}}},"responses":{"201":{"description":"The comment id","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"}},"required":["id"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/labels":{"get":{"operationId":"listLabels","tags":["Issues"],"summary":"Every label and how many open issues carry it","x-access":"public","responses":{"200":{"description":"Labels","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["labels"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createLabel","tags":["Issues"],"summary":"Make a label (stewards)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9][a-z0-9 -]{0,38}[a-z0-9]$"},"description":{"type":"string"},"color":{"type":"string","description":"Six hex digits","pattern":"^[0-9a-f]{6}$"}},"required":["name"]}}}},"responses":{"201":{"description":"The label","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/people":{"get":{"operationId":"searchPeople","tags":["People"],"summary":"People to @mention: handles that start with, or names that contain, what is typed; those in the conversation first","x-access":"public","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"What follows the @"},{"name":"ids","in":"query","required":false,"schema":{"type":"string"},"description":"Account ids, comma separated (at most 100): who each is, instead of a search"},{"name":"thread","in":"query","required":false,"schema":{"type":"string","pattern":"^(changeset|report):[0-9]+$"},"description":"changeset:<id> or report:<id>"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":8},"description":"How many (at most 20)"}],"responses":{"200":{"description":"People","content":{"application/json":{"schema":{"type":"object","properties":{"people":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["people"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/people/{username}":{"get":{"operationId":"getProfile","tags":["People"],"summary":"A person's public page: who they are, their counts and recent activity (an old handle finds them too, with `movedFrom`)","x-access":"public","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","description":"A handle, without the @","pattern":"^[A-Za-z0-9][A-Za-z0-9-]{0,38}[A-Za-z0-9]$"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30},"description":"How many (at most 100)"}],"responses":{"200":{"description":"The profile","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/threads":{"get":{"operationId":"searchThreads","tags":["People"],"summary":"Suggestions and issues to #mention, by number or words","description":"No account needed; signed in, a little more.","security":[{},{"token":[]},{"session":[]}],"x-access":"optional","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"What follows the #"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":8},"description":"How many (at most 20)"}],"responses":{"200":{"description":"Threads","content":{"application/json":{"schema":{"type":"object","properties":{"threads":{"type":"array","items":{"type":"object","properties":{"kind":{"enum":["changeset","report"]},"number":{"type":"integer"},"title":{"type":"string"},"state":{"type":"string"}}}}},"required":["threads"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/threads/{number}":{"get":{"operationId":"threadByNumber","tags":["People"],"summary":"Which of the two #12 is: a suggestion or an issue, and its id","description":"No account needed; signed in, a little more.","security":[{},{"token":[]},{"session":[]}],"x-access":"optional","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"integer","description":"The number after #","minimum":1}}],"responses":{"200":{"description":"What it is","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"enum":["suggestion","issue"]},"number":{"type":"integer"},"id":{"type":"integer"}},"required":["kind","number","id"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/inbox":{"get":{"operationId":"inbox","tags":["Inbox"],"summary":"Your inbox, newest first: mentions, review requests, assignments and what you follow","description":"Signed in: an API token (read scope is enough), or the site's session.","security":[{"token":["read"]},{"session":[]}],"x-access":"read","x-paged":true,"parameters":[{"name":"filter","in":"query","required":false,"schema":{"enum":["unread","all","mention","review_requested","assigned","author","comment","review","state","followed"]},"description":"unread, all, or one reason"},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Deprecated: lines older than this time; use cursor"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"How many (at most 100)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `next` of the page before"}],"responses":{"200":{"description":"Inbox lines and the unread count","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InboxLine"}},"unread":{"type":"integer"},"next":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["items","unread","next"]}}},"headers":{"Link":{"description":"rel=\"next\": the next page","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/inbox/count":{"get":{"operationId":"inboxCount","tags":["Inbox"],"summary":"How many inbox lines are unread","description":"Signed in: an API token (read scope is enough), or the site's session.","security":[{"token":["read"]},{"session":[]}],"x-access":"read","responses":{"200":{"description":"The count","content":{"application/json":{"schema":{"type":"object","properties":{"unread":{"type":"integer"}},"required":["unread"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/inbox/read":{"post":{"operationId":"markInboxRead","tags":["Inbox"],"summary":"Mark inbox lines read (or unread): by id, by conversation, or all","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"integer"}},"subject":{"type":"object","properties":{"kind":{"enum":["changeset","report","entity","project"]},"id":{"type":"string"}},"required":["kind","id"]},"all":{"type":"boolean"},"unread":{"type":"boolean","description":"true: mark them unread"}}}}}},"responses":{"200":{"description":"How many changed, and the unread count","content":{"application/json":{"schema":{"type":"object","properties":{"changed":{"type":"integer"},"unread":{"type":"integer"}},"required":["changed","unread"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects":{"get":{"operationId":"listProjects","tags":["Projects"],"summary":"Projects working through a gap, with their progress","x-access":"public","parameters":[{"name":"status","in":"query","required":false,"schema":{"enum":["open","merged","closed"]}}],"responses":{"200":{"description":"Projects","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["projects"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createProject","tags":["Projects"],"summary":"Open a project on a gap (farbrengens without recordings or texts, recordings to sync, pages to proofread)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"name":{"type":"string"},"goal":{"type":"string"},"set":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"missing":{"enum":["recordings","texts","sync","proofreading"]},"within":{"type":"string"},"scan":{"type":"string","description":"A permanent id: rh- and letters and digits (read forgivingly: RH-7K2M-9Q4D works)","pattern":"^[rR][hH]-[0-9A-Za-z-]+$","examples":["rh-7k2m9q4d"]},"level":{"enum":[1,2]}},"required":["slug","name"]}}}},"responses":{"201":{"description":"The project","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"}},"required":["id","slug"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{slug}":{"get":{"operationId":"getProject","tags":["Projects"],"summary":"A project, its progress and what is left to do","x-access":"public","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","description":"A project's short name","pattern":"^[a-z0-9-]+$"}}],"responses":{"200":{"description":"The project","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"object","additionalProperties":true},"next":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"todo":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["project","next","todo"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{slug}/next":{"post":{"operationId":"claimNext","tags":["Projects"],"summary":"Hand me the next item nobody holds (held for you for a few hours)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","description":"A project's short name","pattern":"^[a-z0-9-]+$"}}],"responses":{"200":{"description":"The item, or null","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]}},"required":["item"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{slug}/release":{"post":{"operationId":"releaseClaim","tags":["Projects"],"summary":"Let go of an item you held","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","description":"A project's short name","pattern":"^[a-z0-9-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"string"}},"required":["item"]}}}},"responses":{"200":{"description":"Released","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/projects/{slug}/close":{"post":{"operationId":"closeProject","tags":["Projects"],"summary":"Close a project (its keepers, stewards)","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","description":"A project's short name","pattern":"^[a-z0-9-]+$"}}],"responses":{"200":{"description":"Closed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/follows":{"get":{"operationId":"listFollows","tags":["Personal"],"summary":"What you follow, the items themselves, and what changed in them lately","description":"Signed in: an API token (read scope is enough), or the site's session.","security":[{"token":["read"]},{"session":[]}],"x-access":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"How many (at most 100)"}],"responses":{"200":{"description":"Follows and the feed","content":{"application/json":{"schema":{"type":"object","properties":{"follows":{"type":"array","items":{"type":"object","additionalProperties":true}},"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"feed":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["follows","items","feed"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"follow","tags":["Personal"],"summary":"Follow or unfollow an item, set, project, suggestion or issue","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"enum":["entity","set","project","changeset","report"]},"id":{"type":"string"},"on":{"type":"boolean","description":"false to unfollow"}},"required":["kind","id"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/places":{"get":{"operationId":"listPlaces","tags":["Personal"],"summary":"Where you stopped reading and listening lately (never cached)","description":"Signed in: an API token (read scope is enough), or the site's session.","security":[{"token":["read"]},{"session":[]}],"x-access":"read","parameters":[{"name":"kind","in":"query","required":false,"schema":{"enum":["read","listen"]}},{"name":"key","in":"query","required":false,"schema":{"type":"string"},"description":"One thing only"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":60,"default":20},"description":"How many (at most 60)"}],"responses":{"200":{"description":"Places","content":{"application/json":{"schema":{"type":"object","properties":{"places":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["places"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"put":{"operationId":"savePlace","tags":["Personal"],"summary":"Keep where you stopped in one thing","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"enum":["read","listen"]},"key":{"type":"string"},"title":{"type":"string"},"sub":{"type":"string"},"href":{"type":"string"},"place":{"type":"object","additionalProperties":true}},"required":["kind","key","title","href","place"]}}}},"responses":{"200":{"description":"The place kept","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"forgetPlace","tags":["Personal"],"summary":"Forget one place","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"kind","in":"query","required":true,"schema":{"enum":["read","listen"]}},{"name":"key","in":"query","required":true,"schema":{"type":"string"},"description":"The thing"}],"responses":{"200":{"description":"Forgotten","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"Your webhooks: addresses every merge is posted to","description":"Signed in: an API token (read scope is enough), or the site's session.","security":[{"token":["read"]},{"session":[]}],"x-access":"read","responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["webhooks"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createWebhook","tags":["Webhooks"],"summary":"Add a webhook (up to five); its signing secret is shown this once","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"https://…","format":"uri"}},"required":["url"]}}}},"responses":{"201":{"description":"The webhook and its secret","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","tags":["Webhooks"],"summary":"Remove a webhook","description":"Signed in: an API token with the write scope, or the site's session.","security":[{"token":["write"]},{"session":[]}],"x-access":"write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"The webhook","minimum":1}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tokens":{"get":{"operationId":"listTokens","tags":["Tokens"],"summary":"Your API tokens (their prefixes only), revoked ones marked","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","responses":{"200":{"description":"Tokens","content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/ApiToken"}}},"required":["tokens"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createToken","tags":["Tokens"],"summary":"Make an API token; the token itself is shown this once","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"What uses it","minLength":1,"maxLength":80},"scopes":{"type":"array","items":{"enum":["read","write"]},"description":"Default: read"},"expiresInDays":{"type":"integer","minimum":1,"maximum":3650}},"required":["name"]}}}},"responses":{"201":{"description":"The token, and what is kept of it","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiToken"},{"type":"object","properties":{"token":{"type":"string","description":"rhp_… - keep it secret"}},"required":["token"]}]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/tokens/{id}":{"delete":{"operationId":"revokeToken","tags":["Tokens"],"summary":"Revoke a token, or end a connected app; it stops working at once","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"tok-… for a token, oac-… for a connected app","pattern":"^(tok|oac)-[\\w-]+$"}}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"protectedResource","tags":["OAuth"],"summary":"The API's Protected Resource Metadata (RFC 9728): which authorization server gives its tokens","x-access":"public","responses":{"200":{"description":"Metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtectedResource"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/.well-known/oauth-protected-resource/mcp":{"get":{"operationId":"mcpProtectedResource","tags":["OAuth"],"summary":"The MCP server's Protected Resource Metadata (RFC 9728), named in its 401's WWW-Authenticate","x-access":"public","responses":{"200":{"description":"Metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtectedResource"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"operationId":"authorizationServer","tags":["OAuth"],"summary":"Authorization Server Metadata (RFC 8414): the endpoints, scopes read and write, PKCE S256, registration and Client ID Metadata Documents","x-access":"public","responses":{"200":{"description":"Metadata","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/oauth/register":{"post":{"operationId":"oauthRegister","tags":["OAuth"],"summary":"Register an app (RFC 7591): its name and redirect addresses; a secret only if it asks for one","x-access":"public","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_name":{"type":"string"},"client_uri":{"type":"string"},"redirect_uris":{"type":"array","items":{"type":"string"},"description":"https, http://localhost, or an app's own scheme"},"token_endpoint_auth_method":{"enum":["none","client_secret_post","client_secret_basic"]},"grant_types":{"type":"array","items":{"type":"string"}},"response_types":{"type":"array","items":{"type":"string"}}},"required":["redirect_uris"]}}}},"responses":{"201":{"description":"The app, with its client_id","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/oauth/authorize":{"get":{"operationId":"oauthAuthorize","tags":["OAuth"],"summary":"Start connecting (authorization code with PKCE): the person is sent to the site's consent page, then back to the app","x-access":"public","parameters":[{"name":"response_type","in":"query","required":true,"schema":{"enum":["code"]}},{"name":"client_id","in":"query","required":true,"schema":{"type":"string","description":"A registered client_id, or the https address of the app's Client ID Metadata Document"}},{"name":"redirect_uri","in":"query","required":false,"schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","description":"read, write or both, space separated (default both; the person may allow reading only)"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string","description":"base64url sha256 of the verifier"}},{"name":"code_challenge_method","in":"query","required":true,"schema":{"enum":["S256"]}},{"name":"resource","in":"query","required":false,"schema":{"type":"string","description":"RFC 8707: https://api.chassidushub.org/mcp (the MCP server) or https://api.chassidushub.org (the whole API)"}},{"name":"ui_locales","in":"query","required":false,"schema":{"type":"string","description":"he for the consent page in Hebrew (English otherwise)"}}],"responses":{"302":{"description":"To the consent page, or back to the app with an error"},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/oauth/token":{"post":{"operationId":"oauthToken","tags":["OAuth"],"summary":"Trade a code (with its PKCE verifier) or a refresh token for an access token (an hour) and a new refresh token","x-access":"public","requestBody":{"required":true,"description":"grant_type, client_id, and code, code_verifier, redirect_uri, resource; or refresh_token (and scope, resource)","content":{"application/x-www-form-urlencoded":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Tokens","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","description":"rho_…"},"token_type":{"const":"Bearer"},"expires_in":{"type":"integer"},"refresh_token":{"type":"string","description":"rhr_…"},"scope":{"type":"string"}},"required":["access_token","token_type","expires_in","refresh_token","scope"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"description":"invalid_client: the app is not known, or its secret is wrong"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/oauth/revoke":{"post":{"operationId":"oauthRevoke","tags":["OAuth"],"summary":"Revoke an access or refresh token (RFC 7009): the whole connection ends","x-access":"public","requestBody":{"required":true,"description":"token (and token_type_hint, client_id)","content":{"application/x-www-form-urlencoded":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Done, whether or not the token was known"},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/oauth/requests/{id}":{"get":{"operationId":"oauthRequest","tags":["OAuth"],"summary":"An app's request to connect, for the consent page: the app, where it sends the person back, the scopes","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^oar-[\\w-]+$"}}],"responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"oauthDecide","tags":["OAuth"],"summary":"The person's answer to an app's request to connect; answers where to send the browser","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^oar-[\\w-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approve":{"type":"boolean"},"scopes":{"type":"array","items":{"enum":["read","write"]},"description":"Allowed; never more than asked"}},"required":["approve"]}}}},"responses":{"200":{"description":"Where to go","content":{"application/json":{"schema":{"type":"object","properties":{"redirect":{"type":"string"}},"required":["redirect"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/mirrors":{"get":{"operationId":"mirrors","tags":["Mirrors"],"summary":"Everything a mirror needs: the git mirror, the release keys, every edition and its dumps","x-access":"public","responses":{"200":{"description":"Mirrors","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/app/{schema}/catalog/manifest.json":{"get":{"operationId":"appCatalogManifest","tags":["Apps"],"summary":"The Sichos Kodesh apps' catalog manifest: the served release's version, size, sha256 and address","description":"The same fields as Sichos-Kodesh's own catalog API (its `CatalogManifest`). The version is `2.<commit>.0`; a release missing a part the app needs (listed in `missing`) is numbered `0.<commit>.0`, so no app takes it.","x-access":"public","parameters":[{"name":"schema","in":"path","required":true,"schema":{"type":"string","description":"The catalog schema: v1 the farbrengens (the web app), v2 with the library, v3 with the works (the phone)","enum":["v1","v2","v3"]}}],"responses":{"200":{"description":"The manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppCatalogManifest"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/app/{schema}/catalog/changelog.json":{"get":{"operationId":"appCatalogChangelog","tags":["Apps"],"summary":"The apps' catalog changelog alone","x-access":"public","parameters":[{"name":"schema","in":"path","required":true,"schema":{"type":"string","description":"The catalog schema: v1 the farbrengens (the web app), v2 with the library, v3 with the works (the phone)","enum":["v1","v2","v3"]}}],"responses":{"200":{"description":"Changelog entries, newest first","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"version":{"type":"string"},"date":{"type":"string"},"en":{"type":"array","items":{"type":"string"}},"he":{"type":"array","items":{"type":"string"}}},"required":["version","date","en","he"]}}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/app/{schema}/catalog/latest/catalog.json":{"get":{"operationId":"appCatalogLatest","tags":["Apps"],"summary":"Redirects to the served release's catalog.json","x-access":"public","parameters":[{"name":"schema","in":"path","required":true,"schema":{"type":"string","description":"The catalog schema: v1 the farbrengens (the web app), v2 with the library, v3 with the works (the phone)","enum":["v1","v2","v3"]}}],"responses":{"302":{"description":"To /v1/app/{schema}/catalog/{version}/catalog.json"},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/app/{schema}/catalog/{version}/catalog.json":{"get":{"operationId":"appCatalogRelease","tags":["Apps"],"summary":"The apps' catalog: the farbrengens by year (v1), with the library (v2) and the works (v3)","description":"Byte for byte what the manifest's sha256 describes (also the ETag). Only the served version is found.","x-access":"public","parameters":[{"name":"schema","in":"path","required":true,"schema":{"type":"string","description":"The catalog schema: v1 the farbrengens (the web app), v2 with the library, v3 with the works (the phone)","enum":["v1","v2","v3"]}},{"name":"version","in":"path","required":true,"schema":{"type":"string","description":"The version the manifest names","pattern":"^\\d+\\.\\d+\\.\\d+$"}}],"responses":{"200":{"description":"Sichos-Kodesh's CatalogRelease, LibraryRelease or WorksRelease","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/app/v3/texts/{sha256}":{"get":{"operationId":"appSourceText","tags":["Apps"],"summary":"A text of a sefer, where the apps look for it (the same as /v1/texts/{sha256})","x-access":"public","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","description":"A file, named by its sha256","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"HTML, shown as a document (sandboxed)","content":{"text/html":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/app/item":{"get":{"operationId":"appItem","tags":["Apps"],"summary":"The item an app's fix or report link is about, by the app's own ids","description":"A farbrengen by `farbrengen` (its mafteiach number), a sefer by `work`, a page of it by `work` and `unit`; a page not found gives its sefer.","x-access":"public","parameters":[{"name":"farbrengen","in":"query","required":false,"schema":{"type":"string"}},{"name":"work","in":"query","required":false,"schema":{"type":"string"}},{"name":"unit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The item","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"}},"required":["id"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/app/v1/app/android/latest.json":{"get":{"operationId":"appAndroidLatest","tags":["Apps"],"summary":"The phone app's newest release: redirects to the reader's packs Worker","x-access":"public","responses":{"307":{"description":"To packs.chassidushub.org"},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/app/v1/app/android/download/{abi}":{"get":{"operationId":"appAndroidDownload","tags":["Apps"],"summary":"The phone app's APK: redirects to the reader's packs Worker","x-access":"public","parameters":[{"name":"abi","in":"path","required":true,"schema":{"type":"string","enum":["arm64-v8a","armeabi-v7a","universal"]}}],"responses":{"307":{"description":"To packs.chassidushub.org"},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/editions":{"get":{"operationId":"editions","tags":["Mirrors"],"summary":"Catalog editions (dated snapshots) and their dumps, each with its size, sha256 and address","x-access":"public","responses":{"200":{"description":"Editions","content":{"application/json":{"schema":{"type":"object","properties":{"editions":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["editions"]}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/editions/{tag}/manifest.json":{"get":{"operationId":"editionManifest","tags":["Mirrors"],"summary":"An edition's signed manifest (Ed25519), exactly as signed","x-access":"public","parameters":[{"name":"tag","in":"path","required":true,"schema":{"type":"string","examples":["2026.40"]}}],"responses":{"200":{"description":"The manifest","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/editions/{tag}/SHA256SUMS":{"get":{"operationId":"editionChecksums","tags":["Mirrors"],"summary":"An edition's checksums, for sha256sum -c","x-access":"public","parameters":[{"name":"tag","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Checksums","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/dumps/{tag}/{name}":{"get":{"operationId":"getDump","tags":["Mirrors"],"summary":"One of an edition's dumps (SQLite, JSON Lines, Parquet)","x-access":"public","parameters":[{"name":"tag","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The dump","content":{"application/octet-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/oai":{"get":{"operationId":"oai","tags":["Libraries"],"summary":"OAI-PMH 2.0 for libraries (oai_dc records), when switched on","x-access":"public","parameters":[{"name":"verb","in":"query","required":true,"schema":{"enum":["Identify","ListMetadataFormats","ListSets","ListIdentifiers","ListRecords","GetRecord"]}},{"name":"metadataPrefix","in":"query","required":false,"schema":{"type":"string"}},{"name":"identifier","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"until","in":"query","required":false,"schema":{"type":"string"}},{"name":"set","in":"query","required":false,"schema":{"type":"string"}},{"name":"resumptionToken","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OAI-PMH XML","content":{"text/xml":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"oaiPost","tags":["Libraries"],"summary":"OAI-PMH, the same arguments sent as a form","x-access":"public","requestBody":{"required":true,"description":"verb and the other arguments","content":{"application/x-www-form-urlencoded":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"OAI-PMH XML","content":{"text/xml":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mcp":{"post":{"operationId":"mcp","tags":["Agents"],"summary":"The Model Context Protocol server (Streamable HTTP, JSON answers, no sessions)","description":"Tools: search, get_item, list_children, get_text, suggest_fix, list_issues, open_issue. Send JSON-RPC 2.0. Reading needs no account. A writing tool without a token answers 401 with WWW-Authenticate naming the Protected Resource Metadata (so MCP clients such as claude.ai ask the person to connect with OAuth), and with a read-only token 403 insufficient_scope. See docs/developers/agents.md.\n\nNo account needed; signed in, a little more.","security":[{},{"token":[]},{"session":[]}],"x-access":"optional","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A JSON-RPC 2.0 message, or a batch"}}}},"responses":{"200":{"description":"The JSON-RPC answer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Only notifications were sent: nothing to answer"},"400":{"$ref":"#/components/responses/400"},"401":{"description":"A writing tool without a token: WWW-Authenticate says where to connect"},"403":{"description":"A writing tool with a read-only token: insufficient_scope"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"mcpStream","tags":["Agents"],"summary":"Not offered: this server opens no event stream","x-access":"public","responses":{"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"405":{"description":"POST only"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"mcpEnd","tags":["Agents"],"summary":"Not offered: there are no sessions to end","x-access":"public","responses":{"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"405":{"description":"POST only"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/me":{"get":{"operationId":"me","tags":["Sign-in"],"summary":"Who is signed in, with their passkeys, Google accounts, emails and notifications","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","responses":{"200":{"description":"The person, or null","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/passkey/register/options":{"post":{"operationId":"passkeyRegisterOptions","tags":["Sign-in"],"summary":"A new account: the options for making a passkey","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"username":{"type":"string","description":"A handle; else one is made from the name"}},"required":["name"]}}}},"responses":{"200":{"description":"WebAuthn options and a challenge id","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/passkey/register/verify":{"post":{"operationId":"passkeyRegisterVerify","tags":["Sign-in"],"summary":"A new account: the passkey made, checked; signs in","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"The person","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/passkey/add/options":{"post":{"operationId":"passkeyAddOptions","tags":["Sign-in"],"summary":"Another passkey for this account: its options","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","responses":{"200":{"description":"WebAuthn options","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/passkey/add/verify":{"post":{"operationId":"passkeyAddVerify","tags":["Sign-in"],"summary":"Another passkey for this account, checked and kept","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Added","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/username":{"get":{"operationId":"checkUsername","tags":["Sign-in"],"summary":"Whether a handle can be had, and a free one suggested from a name","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"name","in":"query","required":false,"schema":{"type":"string"},"description":"The handle wanted"},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"A name to suggest one from"}],"responses":{"200":{"description":"Whether it is free, why not, and a suggestion","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"setUsername","tags":["Sign-in"],"summary":"Choose a new handle; the old one keeps leading to you (never with a token)","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"]}}}},"responses":{"200":{"description":"The person","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/name":{"post":{"operationId":"rename","tags":["Sign-in"],"summary":"Change the name you go by","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}}},"responses":{"200":{"description":"The person","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/passkey/sign-in/options":{"post":{"operationId":"passkeySignInOptions","tags":["Sign-in"],"summary":"Signing in with a passkey: its options","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","responses":{"200":{"description":"WebAuthn options","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/passkey/sign-in/verify":{"post":{"operationId":"passkeySignInVerify","tags":["Sign-in"],"summary":"Signing in with a passkey: checked; signs in","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"The person","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/google/start":{"get":{"operationId":"googleStart","tags":["Sign-in"],"summary":"Signing in with Google: off to Google","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"return","in":"query","required":false,"schema":{"type":"string"},"description":"Where on the site to come back to"}],"responses":{"302":{"description":"To Google"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/google/callback":{"get":{"operationId":"googleCallback","tags":["Sign-in"],"summary":"Signing in with Google: back from Google","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Back to the site, signed in"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/email/start":{"post":{"operationId":"emailStart","tags":["Sign-in"],"summary":"Signing in by email: send a link","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"return":{"type":"string"},"lang":{"type":"string"}},"required":["email"]}}}},"responses":{"200":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"description":"Too many links for this address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/email/check":{"post":{"operationId":"emailCheck","tags":["Sign-in"],"summary":"Signing in by email: what a link is for, before using it","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}}}},"responses":{"200":{"description":"The address and whether it has an account","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/email/verify":{"post":{"operationId":"emailVerify","tags":["Sign-in"],"summary":"Signing in by email: use the link; signs in","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"name":{"type":"string"},"username":{"type":"string","description":"For a new account: a handle"}},"required":["token"]}}}},"responses":{"200":{"description":"The person","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/notifications":{"post":{"operationId":"setNotifications","tags":["Sign-in"],"summary":"Email about what you follow: off, a daily digest, or at once","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"enum":["off","daily","immediate"]},"email":{"type":"string"},"lang":{"type":"string"}},"required":["mode"]}}}},"responses":{"200":{"description":"The setting","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/email/unsubscribe":{"post":{"operationId":"unsubscribe","tags":["Sign-in"],"summary":"Stop email updates, from the link in any of them (no sign-in)","x-access":"public","parameters":[{"name":"token","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Stopped","content":{"application/json":{"schema":{"type":"object","properties":{"stopped":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/400"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/sign-out":{"post":{"operationId":"signOut","tags":["Sign-in"],"summary":"Sign out this browser","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","responses":{"200":{"description":"Signed out","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/admin/people":{"get":{"operationId":"listPeople","tags":["Stewards"],"summary":"Everyone with an account (stewards)","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"A name or id"}],"responses":{"200":{"description":"People","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/admin/people/{id}/role":{"post":{"operationId":"setRole","tags":["Stewards"],"summary":"Appoint or remove a steward or admin (admins)","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^u-[0-9a-z]+$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"steward":{"type":"boolean"},"admin":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/admin/people/{id}/suspend":{"post":{"operationId":"suspend","tags":["Stewards"],"summary":"Suspend or restore an account (its API tokens are revoked)","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^u-[0-9a-z]+$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"on":{"type":"boolean"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/admin/takedowns":{"get":{"operationId":"listTakedowns","tags":["Stewards"],"summary":"Takedown requests, with the files each points at","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"status","in":"query","required":false,"schema":{"enum":["open","resolved","dismissed"]}}],"responses":{"200":{"description":"Takedowns","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/admin/files/{sha256}/takedown":{"post":{"operationId":"takeDown","tags":["Stewards"],"summary":"Take a file down: kept privately, no longer served","description":"Only from the site's own pages, signed in; an API token cannot do this.","security":[{"session":[]}],"x-access":"site","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","description":"A file, named by its sha256","pattern":"^[0-9a-f]{64}$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"integer"}}}}}},"responses":{"200":{"description":"Taken down","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"default":{"description":"Any other error, in the same shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}