[{"data":1,"prerenderedAt":807},["ShallowReactive",2],{"docs-nav":3,"content-query-4o0U2i3LAm":265},[4,8,11,14,17,21,25,29,32,36,40,44,48,52,56,60,63,67,71,75,79,83,87,91,95,99,103,107,111,115,118,121,124,127,130,133,136,139,142,145,148,151,154,157,160,163,166,169,172,175,178,181,184,187,190,193,196,199,202,205,208,211,214,217,220,223,226,229,232,235,238,241,244,247,250,253,256,259,262],{"_path":5,"title":6,"order":7},"/docs/getting-started","Getting Started",1,{"_path":9,"title":10,"order":7},"/docs/views/grid","Grid View",{"_path":12,"title":13,"order":7},"/docs/api/server","Server API",{"_path":15,"title":16,"order":7},"/docs/self-hosting/all-in-one","All-in-One Setup",{"_path":18,"title":19,"order":20},"/docs/core-concepts","Core Concepts",10,{"_path":22,"title":23,"order":24},"/docs/crdt","What is a CRDT?",11,{"_path":26,"title":27,"order":28},"/docs/api/client-http","Client HTTP API",2,{"_path":30,"title":31,"order":28},"/docs/self-hosting/separate-containers","Separate Containers Setup",{"_path":33,"title":34,"order":35},"/docs/interface-overview","Interface Overview",20,{"_path":37,"title":38,"order":39},"/docs/global-search","Global Search",22,{"_path":41,"title":42,"order":43},"/docs/filters","Filters",24,{"_path":45,"title":46,"order":47},"/docs/sorting","Sorting",25,{"_path":49,"title":50,"order":51},"/docs/tagging-and-selection","Tagging & Selection",26,{"_path":53,"title":54,"order":55},"/docs/quick-view","Quick View",28,{"_path":57,"title":58,"order":59},"/docs/api/cli","CLI",3,{"_path":61,"title":62,"order":59},"/docs/self-hosting/remote-access-tailscale","Remote Access with Tailscale",{"_path":64,"title":65,"order":66},"/docs/block-actions","Block Actions",30,{"_path":68,"title":69,"order":70},"/docs/deleting-blocks","Deleting Blocks & Trash",32,{"_path":72,"title":73,"order":74},"/docs/self-hosting","Self-Hosting",4,{"_path":76,"title":77,"order":78},"/docs/managing-heaps","Managing Heaps",40,{"_path":80,"title":81,"order":82},"/docs/file-scanning","File Scanning & Importing",42,{"_path":84,"title":85,"order":86},"/docs/storage-management","Storage Management",44,{"_path":88,"title":89,"order":90},"/docs/daily-notes","Daily Notes & Calendar",46,{"_path":92,"title":93,"order":94},"/docs/api","API",5,{"_path":96,"title":97,"order":98},"/docs/views","Views",60,{"_path":100,"title":101,"order":102},"/docs/authentication","Authentication & User Management",70,{"_path":104,"title":105,"order":106},"/docs/licenses-privacy","Licenses & Privacy",72,{"_path":108,"title":109,"order":110},"/docs/faq","FAQ",80,{"_path":112,"title":113,"order":114},"/docs/changelog","Changelog",99,{"_path":116,"title":117},"/docs/changelog/v16.16.37","v16.16.37",{"_path":119,"title":120},"/docs/changelog/v16.16.38","v16.16.38",{"_path":122,"title":123},"/docs/changelog/v16.11.0","v16.11.0",{"_path":125,"title":126},"/docs/changelog/v16.16.29","v16.16.29",{"_path":128,"title":129},"/docs/changelog/v16.16.28","v16.16.28",{"_path":131,"title":132},"/docs/changelog/v16.16.1","v16.16.1",{"_path":134,"title":135},"/docs/changelog/v16.10.0","v16.10.0",{"_path":137,"title":138},"/docs/changelog/v16.16.8","v16.16.8",{"_path":140,"title":141},"/docs/changelog/v16.7.0","v16.7.0",{"_path":143,"title":144},"/docs/changelog/v16.16.14","v16.16.14",{"_path":146,"title":147},"/docs/changelog/v16.16.7","v16.16.7",{"_path":149,"title":150},"/docs/changelog/v16.16.36","v16.16.36",{"_path":152,"title":153},"/docs/changelog/v16.16.32","v16.16.32",{"_path":155,"title":156},"/docs/changelog/v16.16.41","v16.16.41",{"_path":158,"title":159},"/docs/changelog/v16.6.0","v16.6.0",{"_path":161,"title":162},"/docs/changelog/v16.16.4","v16.16.4",{"_path":164,"title":165},"/docs/changelog/v16.16.0","v16.16.0",{"_path":167,"title":168},"/docs/changelog/v16.16.40","v16.16.40",{"_path":170,"title":171},"/docs/changelog/v16.16.20","v16.16.20",{"_path":173,"title":174},"/docs/changelog/v16.16.16","v16.16.16",{"_path":176,"title":177},"/docs/changelog/v16.16.25","v16.16.25",{"_path":179,"title":180},"/docs/changelog/v16.16.17","v16.16.17",{"_path":182,"title":183},"/docs/changelog/v16.17.8","v16.17.8",{"_path":185,"title":186},"/docs/changelog/v16.16.33","v16.16.33",{"_path":188,"title":189},"/docs/changelog/v16.16.22","v16.16.22",{"_path":191,"title":192},"/docs/changelog/v16.16.23","v16.16.23",{"_path":194,"title":195},"/docs/changelog/v16.16.35","v16.16.35",{"_path":197,"title":198},"/docs/changelog/v16.16.24","v16.16.24",{"_path":200,"title":201},"/docs/changelog/v16.16.5","v16.16.5",{"_path":203,"title":204},"/docs/changelog/v16.16.11","v16.16.11",{"_path":206,"title":207},"/docs/changelog/v16.16.27","v16.16.27",{"_path":209,"title":210},"/docs/changelog/v16.16.19","v16.16.19",{"_path":212,"title":213},"/docs/changelog/v16.16.13","v16.16.13",{"_path":215,"title":216},"/docs/changelog/v16.16.3","v16.16.3",{"_path":218,"title":219},"/docs/changelog/v16.9.0","v16.9.0",{"_path":221,"title":222},"/docs/changelog/v16.16.43","v16.16.43",{"_path":224,"title":225},"/docs/changelog/v16.16.2","v16.16.2",{"_path":227,"title":228},"/docs/changelog/v16.16.18","v16.16.18",{"_path":230,"title":231},"/docs/changelog/v16.16.30","v16.16.30",{"_path":233,"title":234},"/docs/changelog/v16.16.21","v16.16.21",{"_path":236,"title":237},"/docs/changelog/v16.16.26","v16.16.26",{"_path":239,"title":240},"/docs/changelog/v16.16.6","v16.16.6",{"_path":242,"title":243},"/docs/changelog/v16.16.31","v16.16.31",{"_path":245,"title":246},"/docs/changelog/v16.16.39","v16.16.39",{"_path":248,"title":249},"/docs/changelog/v16.16.34","v16.16.34",{"_path":251,"title":252},"/docs/changelog/v16.16.12","v16.16.12",{"_path":254,"title":255},"/docs/changelog/v16.8.0","v16.8.0",{"_path":257,"title":258},"/docs/changelog/v16.16.10","v16.16.10",{"_path":260,"title":261},"/docs/changelog/v16.16.9","v16.16.9",{"_path":263,"title":264},"/docs/changelog/v16.16.15","v16.16.15",{"_path":12,"_dir":266,"_draft":267,"_partial":267,"_locale":268,"title":13,"description":269,"order":7,"body":270,"_type":801,"_id":802,"_source":803,"_file":804,"_stem":805,"_extension":806},"api",false,"","Public HTTP and realtime endpoints for integrating with a Heaper server.",{"type":271,"children":272,"toc":788},"root",[273,281,287,294,299,312,325,334,340,345,354,375,380,438,443,449,498,504,511,516,541,550,556,561,570,575,584,590,595,642,647,656,662,667,695,700,709,718,724,729,734,764,770,775],{"type":274,"tag":275,"props":276,"children":278},"element","h1",{"id":277},"server-api",[279],{"type":280,"value":13},"text",{"type":274,"tag":282,"props":283,"children":284},"p",{},[285],{"type":280,"value":286},"The server API is the remote integration surface for Heaper. Use it when you are talking to a self-hosted instance.",{"type":274,"tag":288,"props":289,"children":291},"h2",{"id":290},"base-url",[292],{"type":280,"value":293},"Base URL",{"type":274,"tag":282,"props":295,"children":296},{},[297],{"type":280,"value":298},"Most examples assume a server base URL like:",{"type":274,"tag":300,"props":301,"children":306},"pre",{"className":302,"code":304,"language":305,"meta":268},[303],"language-bash","https://your-heaper.example.com\n","bash",[307],{"type":274,"tag":308,"props":309,"children":310},"code",{"__ignoreMap":268},[311],{"type":280,"value":304},{"type":274,"tag":282,"props":313,"children":314},{},[315,317,323],{"type":280,"value":316},"Server routes live under ",{"type":274,"tag":308,"props":318,"children":320},{"className":319},[],[321],{"type":280,"value":322},"/api",{"type":280,"value":324},", for example:",{"type":274,"tag":300,"props":326,"children":329},{"className":327,"code":328,"language":305,"meta":268},[303],"curl https://your-heaper.example/api/health\n",[330],{"type":274,"tag":308,"props":331,"children":332},{"__ignoreMap":268},[333],{"type":280,"value":328},{"type":274,"tag":288,"props":335,"children":337},{"id":336},"authentication",[338],{"type":280,"value":339},"Authentication",{"type":274,"tag":282,"props":341,"children":342},{},[343],{"type":280,"value":344},"The server API uses bearer tokens:",{"type":274,"tag":300,"props":346,"children":349},{"className":347,"code":348,"language":305,"meta":268},[303],"Authorization: Bearer \u003Caccess-token>\n",[350],{"type":274,"tag":308,"props":351,"children":352},{"__ignoreMap":268},[353],{"type":280,"value":348},{"type":274,"tag":282,"props":355,"children":356},{},[357,359,365,367,373],{"type":280,"value":358},"The middleware accepts the token from the ",{"type":274,"tag":308,"props":360,"children":362},{"className":361},[],[363],{"type":280,"value":364},"Authorization",{"type":280,"value":366}," header and validates it as an EdDSA-signed JWT. For file-serving style integrations, the backend also accepts ",{"type":274,"tag":308,"props":368,"children":370},{"className":369},[],[371],{"type":280,"value":372},"token",{"type":280,"value":374}," in the query string, but header-based auth is the normal developer path.",{"type":274,"tag":282,"props":376,"children":377},{},[378],{"type":280,"value":379},"For current self-hosted and key-based flows, the main login pattern is:",{"type":274,"tag":381,"props":382,"children":383},"ol",{},[384,396,401,412,425],{"type":274,"tag":385,"props":386,"children":387},"li",{},[388,394],{"type":274,"tag":308,"props":389,"children":391},{"className":390},[],[392],{"type":280,"value":393},"POST /api/auth/create_session",{"type":280,"value":395}," with the user's public key.",{"type":274,"tag":385,"props":397,"children":398},{},[399],{"type":280,"value":400},"Sign the returned challenge client-side.",{"type":274,"tag":385,"props":402,"children":403},{},[404,410],{"type":274,"tag":308,"props":405,"children":407},{"className":406},[],[408],{"type":280,"value":409},"POST /api/auth/verify_session",{"type":280,"value":411}," with the signature.",{"type":274,"tag":385,"props":413,"children":414},{},[415,417,423],{"type":280,"value":416},"Use the returned ",{"type":274,"tag":308,"props":418,"children":420},{"className":419},[],[421],{"type":280,"value":422},"accessToken",{"type":280,"value":424}," for normal API requests.",{"type":274,"tag":385,"props":426,"children":427},{},[428,430,436],{"type":280,"value":429},"Refresh with ",{"type":274,"tag":308,"props":431,"children":433},{"className":432},[],[434],{"type":280,"value":435},"POST /api/auth/refresh_token",{"type":280,"value":437}," using a refresh token bearer header.",{"type":274,"tag":282,"props":439,"children":440},{},[441],{"type":280,"value":442},"The email/password login is only accessible to heaper.de cloud accounts, this removed the need for email servers in selfhosted environments which are basically hell to host and maintain.",{"type":274,"tag":288,"props":444,"children":446},{"id":445},"request-and-response-conventions",[447],{"type":280,"value":448},"Request and Response Conventions",{"type":274,"tag":450,"props":451,"children":452},"ul",{},[453,458,463,476,488,493],{"type":274,"tag":385,"props":454,"children":455},{},[456],{"type":280,"value":457},"JSON request bodies are used for most write and query-style endpoints.",{"type":274,"tag":385,"props":459,"children":460},{},[461],{"type":280,"value":462},"Successful responses are JSON unless the endpoint serves binary file content.",{"type":274,"tag":385,"props":464,"children":465},{},[466,468,474],{"type":280,"value":467},"Auth failures usually return ",{"type":274,"tag":308,"props":469,"children":471},{"className":470},[],[472],{"type":280,"value":473},"401 Unauthorized",{"type":280,"value":475},".",{"type":274,"tag":385,"props":477,"children":478},{},[479,481,487],{"type":280,"value":480},"Permission failures usually return ",{"type":274,"tag":308,"props":482,"children":484},{"className":483},[],[485],{"type":280,"value":486},"403 Forbidden",{"type":280,"value":475},{"type":274,"tag":385,"props":489,"children":490},{},[491],{"type":280,"value":492},"Routes under the new auth namespace are rate limited. These stricter for auth than for general data access.",{"type":274,"tag":385,"props":494,"children":495},{},[496],{"type":280,"value":497},"CORS is enabled by middleware and mirrors the request origin, for compatibility with all devices and browsers.",{"type":274,"tag":288,"props":499,"children":501},{"id":500},"main-workflows",[502],{"type":280,"value":503},"Main Workflows",{"type":274,"tag":505,"props":506,"children":508},"h3",{"id":507},"instance-discovery-and-health",[509],{"type":280,"value":510},"Instance Discovery and Health",{"type":274,"tag":282,"props":512,"children":513},{},[514],{"type":280,"value":515},"Use these first:",{"type":274,"tag":450,"props":517,"children":518},{},[519,530],{"type":274,"tag":385,"props":520,"children":521},{},[522,528],{"type":274,"tag":308,"props":523,"children":525},{"className":524},[],[526],{"type":280,"value":527},"GET /api/",{"type":280,"value":529}," returns instance metadata such as version, public key, public URL, and self-hosted status.",{"type":274,"tag":385,"props":531,"children":532},{},[533,539],{"type":274,"tag":308,"props":534,"children":536},{"className":535},[],[537],{"type":280,"value":538},"GET /api/health",{"type":280,"value":540}," returns server and database health.",{"type":274,"tag":300,"props":542,"children":545},{"className":543,"code":544,"language":305,"meta":268},[303],"curl https://your-heaper.example/api/\ncurl https://your-heaper.example/api/health\n",[546],{"type":274,"tag":308,"props":547,"children":548},{"__ignoreMap":268},[549],{"type":280,"value":544},{"type":274,"tag":505,"props":551,"children":553},{"id":552},"session-creation",[554],{"type":280,"value":555},"Session Creation",{"type":274,"tag":282,"props":557,"children":558},{},[559],{"type":280,"value":560},"Create a key-based auth challenge:",{"type":274,"tag":300,"props":562,"children":565},{"className":563,"code":564,"language":305,"meta":268},[303],"curl -X POST https://your-heaper.example/api/auth/create_session \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"public_key\":\"\u003Cbase58-public-key>\"}'\n",[566],{"type":274,"tag":308,"props":567,"children":568},{"__ignoreMap":268},[569],{"type":280,"value":564},{"type":274,"tag":282,"props":571,"children":572},{},[573],{"type":280,"value":574},"Verify the signed challenge:",{"type":274,"tag":300,"props":576,"children":579},{"className":577,"code":578,"language":305,"meta":268},[303],"curl -X POST https://your-heaper.example/api/auth/verify_session \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"public_key\":\"\u003Cbase58-public-key>\",\n    \"message\":\"\u003Cchallenge>\",\n    \"signature\":\"\u003Cbase58-signature>\"\n  }'\n",[580],{"type":274,"tag":308,"props":581,"children":582},{"__ignoreMap":268},[583],{"type":280,"value":578},{"type":274,"tag":505,"props":585,"children":587},{"id":586},"sync",[588],{"type":280,"value":589},"Sync",{"type":274,"tag":282,"props":591,"children":592},{},[593],{"type":280,"value":594},"Heaper exposes HTTP delta sync endpoints alongside WebSocket-based live sync.",{"type":274,"tag":450,"props":596,"children":597},{},[598,609,620,631],{"type":274,"tag":385,"props":599,"children":600},{},[601,607],{"type":274,"tag":308,"props":602,"children":604},{"className":603},[],[605],{"type":280,"value":606},"GET /api/sync/delta",{"type":280,"value":608}," asks what changed in a heap since a timestamp.",{"type":274,"tag":385,"props":610,"children":611},{},[612,618],{"type":274,"tag":308,"props":613,"children":615},{"className":614},[],[616],{"type":280,"value":617},"POST /api/sync/push",{"type":280,"value":619}," uploads YDoc updates.",{"type":274,"tag":385,"props":621,"children":622},{},[623,629],{"type":274,"tag":308,"props":624,"children":626},{"className":625},[],[627],{"type":280,"value":628},"POST /api/sync/pull",{"type":280,"value":630}," asks the server for missing updates or full state.",{"type":274,"tag":385,"props":632,"children":633},{},[634,640],{"type":274,"tag":308,"props":635,"children":637},{"className":636},[],[638],{"type":280,"value":639},"GET /ws",{"type":280,"value":641}," is the live sync WebSocket endpoint used by the app.",{"type":274,"tag":282,"props":643,"children":644},{},[645],{"type":280,"value":646},"Example delta request:",{"type":274,"tag":300,"props":648,"children":651},{"className":649,"code":650,"language":305,"meta":268},[303],"curl 'https://your-heaper.example/api/sync/delta?workspace_id=\u003Cworkspace-id>&since=0' \\\n  -H 'Authorization: Bearer \u003Caccess-token>'\n",[652],{"type":274,"tag":308,"props":653,"children":654},{"__ignoreMap":268},[655],{"type":280,"value":650},{"type":274,"tag":505,"props":657,"children":659},{"id":658},"workspaces-blocks-and-views",[660],{"type":280,"value":661},"Workspaces, Blocks, and Views",{"type":274,"tag":282,"props":663,"children":664},{},[665],{"type":280,"value":666},"The content model is block-based. The main routes let you:",{"type":274,"tag":450,"props":668,"children":669},{},[670,675,680,685,690],{"type":274,"tag":385,"props":671,"children":672},{},[673],{"type":280,"value":674},"list heaps",{"type":274,"tag":385,"props":676,"children":677},{},[678],{"type":280,"value":679},"fetch a block with relations and files",{"type":274,"tag":385,"props":681,"children":682},{},[683],{"type":280,"value":684},"search and query blocks within a heap",{"type":274,"tag":385,"props":686,"children":687},{},[688],{"type":280,"value":689},"create a block",{"type":274,"tag":385,"props":691,"children":692},{},[693],{"type":280,"value":694},"editing of blocks is handled via crdt's in the client to sync seamlessly with the server. (thin wrappers to let this happen just with requests are planned)",{"type":274,"tag":282,"props":696,"children":697},{},[698],{"type":280,"value":699},"Example:",{"type":274,"tag":300,"props":701,"children":704},{"className":702,"code":703,"language":305,"meta":268},[303],"curl -X POST https://your-heaper.example/api/heaps \\\n  -H 'Authorization: Bearer \u003Caccess-token>'\n",[705],{"type":274,"tag":308,"props":706,"children":707},{"__ignoreMap":268},[708],{"type":280,"value":703},{"type":274,"tag":300,"props":710,"children":713},{"className":711,"code":712,"language":305,"meta":268},[303],"curl -X POST https://your-heaper.example/api/block/\u003Cblock-id> \\\n  -H 'Authorization: Bearer \u003Caccess-token>'\n",[714],{"type":274,"tag":308,"props":715,"children":716},{"__ignoreMap":268},[717],{"type":280,"value":712},{"type":274,"tag":505,"props":719,"children":721},{"id":720},"files-and-uploads",[722],{"type":280,"value":723},"Files and Uploads",{"type":274,"tag":282,"props":725,"children":726},{},[727],{"type":280,"value":728},"The server API supports metadata queries, scan jobs, direct file assignment, resumable uploads, thumbnail upload/download, and authenticated raw file serving.",{"type":274,"tag":282,"props":730,"children":731},{},[732],{"type":280,"value":733},"Resumable upload flow:",{"type":274,"tag":381,"props":735,"children":736},{},[737,746,755],{"type":274,"tag":385,"props":738,"children":739},{},[740],{"type":274,"tag":308,"props":741,"children":743},{"className":742},[],[744],{"type":280,"value":745},"POST /api/upload/init/:heap_id/:block_id",{"type":274,"tag":385,"props":747,"children":748},{},[749],{"type":274,"tag":308,"props":750,"children":752},{"className":751},[],[753],{"type":280,"value":754},"PUT /api/upload/chunk/:heap_id/:block_id/:hash/:index",{"type":274,"tag":385,"props":756,"children":757},{},[758],{"type":274,"tag":308,"props":759,"children":761},{"className":760},[],[762],{"type":280,"value":763},"POST /api/upload/complete/:heap_id/:block_id/:hash",{"type":274,"tag":288,"props":765,"children":767},{"id":766},"reference",[768],{"type":280,"value":769},"Reference",{"type":274,"tag":282,"props":771,"children":772},{},[773],{"type":280,"value":774},"Use the reference page for the exact supported route inventory:",{"type":274,"tag":450,"props":776,"children":777},{},[778],{"type":274,"tag":385,"props":779,"children":780},{},[781],{"type":274,"tag":782,"props":783,"children":785},"a",{"href":784},"/docs/api/server-reference",[786],{"type":280,"value":787},"Server API Reference",{"title":268,"searchDepth":28,"depth":28,"links":789},[790,791,792,793,800],{"id":290,"depth":28,"text":293},{"id":336,"depth":28,"text":339},{"id":445,"depth":28,"text":448},{"id":500,"depth":28,"text":503,"children":794},[795,796,797,798,799],{"id":507,"depth":59,"text":510},{"id":552,"depth":59,"text":555},{"id":586,"depth":59,"text":589},{"id":658,"depth":59,"text":661},{"id":720,"depth":59,"text":723},{"id":766,"depth":28,"text":769},"markdown","content:docs:api:server.md","content","docs/api/server.md","docs/api/server","md",1777640558099]