[{"data":1,"prerenderedAt":874},["ShallowReactive",2],{"/api/overview/migration":3,"/api/overview/migration-surround":865},{"id":4,"title":5,"body":6,"description":857,"extension":858,"links":859,"meta":860,"navigation":578,"path":861,"seo":862,"stem":863,"__hash__":864},"docs/api/1.overview/migration.md","Migration from Beta to v1",{"type":7,"value":8,"toc":841},"minimark",[9,18,31,36,39,44,52,81,85,99,114,121,125,128,239,243,247,252,257,274,285,289,298,303,318,321,324,336,341,367,378,381,386,391,452,458,461,472,485,510,522,526,534,537,751,755,837],[10,11,12,13,17],"p",{},"The Beta API has been superseded by ",[14,15,16],"strong",{},"the new API",". This guide covers everything you need to update.",[19,20,21],"warning",{},[10,22,23,24,30],{},"Both APIs are still available under ",[25,26,27],"a",{"href":27,"rel":28},"https://api.capacities.io",[29],"nofollow",". However, we recommend you to migrate to the new API as soon as possible. The Beta API will be deprecated on September 1st, 2026.",[32,33,35],"h2",{"id":34},"authentication","Authentication",[10,37,38],{},"This is the most significant change between the two versions.",[40,41,43],"h3",{"id":42},"beta-one-token-for-all-spaces","Beta: one token for all spaces",[10,45,46,47,51],{},"The beta API used a single user-level API token that granted access to all your spaces. Every request that needed a specific space required you to pass a ",[48,49,50],"code",{},"spaceId"," query parameter to identify which one to act on.",[53,54,59],"pre",{"className":55,"code":56,"language":57,"meta":58,"style":58},"language-http shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","GET /spaces          # discover your space IDs first\nGET /space-info?spaceId=\u003Cid>\nPOST /save-to-daily-note   # body: { spaceId: \"...\", mdText: \"...\" }\n","http","",[48,60,61,69,75],{"__ignoreMap":58},[62,63,66],"span",{"class":64,"line":65},"line",1,[62,67,68],{},"GET /spaces          # discover your space IDs first\n",[62,70,72],{"class":64,"line":71},2,[62,73,74],{},"GET /space-info?spaceId=\u003Cid>\n",[62,76,78],{"class":64,"line":77},3,[62,79,80],{},"POST /save-to-daily-note   # body: { spaceId: \"...\", mdText: \"...\" }\n",[40,82,84],{"id":83},"api-v1-one-token-per-space-or-oauth","API v1: one token per space (or OAuth)",[10,86,87,88,91,92,98],{},"API v1 tokens are ",[14,89,90],{},"space-scoped",". A personal API token or an OAuth access token grants access to exactly one space, so ",[14,93,94,95,97],{},"you never pass ",[48,96,50],{}," in a request",". If you need to work across multiple spaces, create one token per space.",[53,100,102],{"className":55,"code":101,"language":57,"meta":58,"style":58},"Authorization: Bearer cap-api-...      # API token\nAuthorization: Bearer eyJ...           # OAuth access token\n",[48,103,104,109],{"__ignoreMap":58},[62,105,106],{"class":64,"line":65},[62,107,108],{},"Authorization: Bearer cap-api-...      # API token\n",[62,110,111],{"class":64,"line":71},[62,112,113],{},"Authorization: Bearer eyJ...           # OAuth access token\n",[10,115,116,117,120],{},"See ",[25,118,35],{"href":119},"/api/overview/authentication"," for how to generate a personal token or set up OAuth.",[32,122,124],{"id":123},"route-mapping","Route mapping",[10,126,127],{},"All functionality from the beta API is available in v1. The table below shows the direct mapping.",[129,130,131,147],"table",{},[132,133,134],"thead",{},[135,136,137,141,144],"tr",{},[138,139,140],"th",{},"Beta",[138,142,143],{},"v1",[138,145,146],{},"Notes",[148,149,150,166,184,203,221],"tbody",{},[135,151,152,158,163],{},[153,154,155],"td",{},[48,156,157],{},"GET /spaces",[153,159,160],{},[48,161,162],{},"GET /space",[153,164,165],{},"Returns the single space the token is scoped to instead of all spaces.",[135,167,168,173,178],{},[153,169,170],{},[48,171,172],{},"GET /space-info?spaceId=",[153,174,175],{},[48,176,177],{},"GET /space/structures",[153,179,180,181,183],{},"No ",[48,182,50],{}," param; space comes from the token.",[135,185,186,191,196],{},[153,187,188],{},[48,189,190],{},"POST /lookup",[153,192,193],{},[48,194,195],{},"POST /objects/search",[153,197,116,198,202],{},[25,199,201],{"href":200},"#search","Search"," below.",[135,204,205,210,215],{},[153,206,207],{},[48,208,209],{},"POST /save-weblink",[153,211,212],{},[48,213,214],{},"POST /object/url",[153,216,116,217,202],{},[25,218,220],{"href":219},"#weblink","Weblink",[135,222,223,228,233],{},[153,224,225],{},[48,226,227],{},"POST /save-to-daily-note",[153,229,230],{},[48,231,232],{},"POST /blocks/daily-note/append",[153,234,116,235,202],{},[25,236,238],{"href":237},"#daily-note","Daily note",[32,240,242],{"id":241},"per-route-migration-details","Per-route migration details",[40,244,246],{"id":245},"spaces","Spaces",[10,248,249,251],{},[14,250,140],{}," returned an array of all spaces the user had access to.",[10,253,254,256],{},[14,255,143],{}," returns the single space the token is scoped to. There is no list endpoint; each token is already tied to one space.",[53,258,262],{"className":259,"code":260,"language":261,"meta":58,"style":58},"language-diff shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","- GET /spaces\n+ GET /space\n","diff",[48,263,264,269],{"__ignoreMap":58},[62,265,266],{"class":64,"line":65},[62,267,268],{},"- GET /spaces\n",[62,270,271],{"class":64,"line":71},[62,272,273],{},"+ GET /space\n",[10,275,276,277,280,281,284],{},"Response shape is similar; ",[48,278,279],{},"id"," and ",[48,282,283],{},"title"," are present in both.",[40,286,288],{"id":287},"space-structures","Space structures",[10,290,291,293,294,297],{},[14,292,140],{}," required a ",[48,295,296],{},"?spaceId="," query parameter.",[10,299,300,302],{},[14,301,143],{}," derives the space from the token.",[53,304,306],{"className":259,"code":305,"language":261,"meta":58,"style":58},"- GET /space-info?spaceId=ac7abb59-b1fd-4102-b549-78e5443610ac\n+ GET /space/structures\n",[48,307,308,313],{"__ignoreMap":58},[62,309,310],{"class":64,"line":65},[62,311,312],{},"- GET /space-info?spaceId=ac7abb59-b1fd-4102-b549-78e5443610ac\n",[62,314,315],{"class":64,"line":71},[62,316,317],{},"+ GET /space/structures\n",[10,319,320],{},"The response structure is equivalent: a list of structures with property definitions and collections.",[40,322,201],{"id":323},"search",[10,325,326,328,329,331,332,335],{},[14,327,140],{}," matched objects by title and returned minimal identifiers (",[48,330,279],{},", ",[48,333,334],{},"structureId",").",[10,337,338,340],{},[14,339,143],{}," uses a richer request and response:",[53,342,344],{"className":259,"code":343,"language":261,"meta":58,"style":58},"- POST /lookup\n- { \"spaceId\": \"...\", \"searchTerm\": \"my note\" }\n+ POST /objects/search\n+ { \"query\": \"my note\", \"structureIds\": [\"RootPage\"] }\n",[48,345,346,351,356,361],{"__ignoreMap":58},[62,347,348],{"class":64,"line":65},[62,349,350],{},"- POST /lookup\n",[62,352,353],{"class":64,"line":71},[62,354,355],{},"- { \"spaceId\": \"...\", \"searchTerm\": \"my note\" }\n",[62,357,358],{"class":64,"line":77},[62,359,360],{},"+ POST /objects/search\n",[62,362,364],{"class":64,"line":363},4,[62,365,366],{},"+ { \"query\": \"my note\", \"structureIds\": [\"RootPage\"] }\n",[10,368,369,370,373,374,377],{},"Response in v1 returns ",[48,371,372],{},"results: [{ id, structureId, title }]",". The ",[48,375,376],{},"structureIds"," filter is optional; omit it to search across all types.",[40,379,220],{"id":380},"weblink",[10,382,383,385],{},[14,384,140],{}," accepted a URL and a target space.",[10,387,388,390],{},[14,389,143],{}," accepts a URL with optional properties, notes (markdown), and target collections:",[53,392,394],{"className":259,"code":393,"language":261,"meta":58,"style":58},"- POST /save-weblink\n- { \"spaceId\": \"...\", \"url\": \"https://example.com\" }\n+ POST /object/url\n+ {\n+   \"url\": \"https://example.com\",\n+   \"properties\": {\n+     \"title\": { \"type\": \"title\", \"title\": { \"value\": \"My link\" } }\n+   },\n+   \"markdown\": \"Optional notes\"\n+ }\n",[48,395,396,401,406,411,416,422,428,434,440,446],{"__ignoreMap":58},[62,397,398],{"class":64,"line":65},[62,399,400],{},"- POST /save-weblink\n",[62,402,403],{"class":64,"line":71},[62,404,405],{},"- { \"spaceId\": \"...\", \"url\": \"https://example.com\" }\n",[62,407,408],{"class":64,"line":77},[62,409,410],{},"+ POST /object/url\n",[62,412,413],{"class":64,"line":363},[62,414,415],{},"+ {\n",[62,417,419],{"class":64,"line":418},5,[62,420,421],{},"+   \"url\": \"https://example.com\",\n",[62,423,425],{"class":64,"line":424},6,[62,426,427],{},"+   \"properties\": {\n",[62,429,431],{"class":64,"line":430},7,[62,432,433],{},"+     \"title\": { \"type\": \"title\", \"title\": { \"value\": \"My link\" } }\n",[62,435,437],{"class":64,"line":436},8,[62,438,439],{},"+   },\n",[62,441,443],{"class":64,"line":442},9,[62,444,445],{},"+   \"markdown\": \"Optional notes\"\n",[62,447,449],{"class":64,"line":448},10,[62,450,451],{},"+ }\n",[10,453,454,455,457],{},"The v1 endpoint returns the full created object including its ",[48,456,279],{},".",[40,459,238],{"id":460},"daily-note",[10,462,463,465,466,469,470,457],{},[14,464,140],{}," accepted a plain ",[48,467,468],{},"mdText"," string and a ",[48,471,50],{},[10,473,474,476,477,480,481,484],{},[14,475,143],{}," accepts either a ",[48,478,479],{},"markdown"," string or a structured ",[48,482,483],{},"blocks"," array (provide exactly one):",[53,486,488],{"className":259,"code":487,"language":261,"meta":58,"style":58},"- POST /save-to-daily-note\n- { \"spaceId\": \"...\", \"mdText\": \"# Hello\\nSome text\" }\n+ POST /blocks/daily-note/append\n+ { \"markdown\": \"# Hello\\nSome text\" }\n",[48,489,490,495,500,505],{"__ignoreMap":58},[62,491,492],{"class":64,"line":65},[62,493,494],{},"- POST /save-to-daily-note\n",[62,496,497],{"class":64,"line":71},[62,498,499],{},"- { \"spaceId\": \"...\", \"mdText\": \"# Hello\\nSome text\" }\n",[62,501,502],{"class":64,"line":77},[62,503,504],{},"+ POST /blocks/daily-note/append\n",[62,506,507],{"class":64,"line":363},[62,508,509],{},"+ { \"markdown\": \"# Hello\\nSome text\" }\n",[10,511,512,513,515,516,518,519,457],{},"Use ",[48,514,479],{}," for simple text. Use ",[48,517,483],{}," when you need precise control over block types and hierarchy. The endpoint processes asynchronously and returns ",[48,520,521],{},"204 No Content",[32,523,525],{"id":524},"typescript-sdk","TypeScript SDK",[10,527,528,529,533],{},"If you were calling the beta API directly via HTTP, the official SDK is now available. See ",[25,530,532],{"href":531},"/api/overview/sdks","SDKs"," for installation and full authentication setup, including OAuth.",[10,535,536],{},"The SDK method names mirror the v1 REST paths:",[53,538,542],{"className":539,"code":540,"language":541,"meta":58,"style":58},"language-typescript shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","import { CapacitiesClient } from '@capacities/api'\n\nconst capacities = new CapacitiesClient({ apiToken: 'cap-api-...' })\n\nconst space = await capacities.space.get()\nconst { results } = await capacities.objects.search({ query: 'my note' })\nawait capacities.blocks.dailyNote.append({ markdown: '## Today\\nSome text' })\n","typescript",[48,543,544,574,580,624,628,656,704],{"__ignoreMap":58},[62,545,546,550,554,558,561,564,567,571],{"class":64,"line":65},[62,547,549],{"class":548},"s7zQu","import",[62,551,553],{"class":552},"sMK4o"," {",[62,555,557],{"class":556},"sTEyZ"," CapacitiesClient",[62,559,560],{"class":552}," }",[62,562,563],{"class":548}," from",[62,565,566],{"class":552}," '",[62,568,570],{"class":569},"sfazB","@capacities/api",[62,572,573],{"class":552},"'\n",[62,575,576],{"class":64,"line":71},[62,577,579],{"emptyLinePlaceholder":578},true,"\n",[62,581,582,586,589,592,595,598,601,604,608,611,613,616,619,621],{"class":64,"line":77},[62,583,585],{"class":584},"spNyl","const",[62,587,588],{"class":556}," capacities ",[62,590,591],{"class":552},"=",[62,593,594],{"class":552}," new",[62,596,557],{"class":597},"s2Zo4",[62,599,600],{"class":556},"(",[62,602,603],{"class":552},"{",[62,605,607],{"class":606},"swJcz"," apiToken",[62,609,610],{"class":552},":",[62,612,566],{"class":552},[62,614,615],{"class":569},"cap-api-...",[62,617,618],{"class":552},"'",[62,620,560],{"class":552},[62,622,623],{"class":556},")\n",[62,625,626],{"class":64,"line":363},[62,627,579],{"emptyLinePlaceholder":578},[62,629,630,632,635,637,640,643,645,648,650,653],{"class":64,"line":418},[62,631,585],{"class":584},[62,633,634],{"class":556}," space ",[62,636,591],{"class":552},[62,638,639],{"class":548}," await",[62,641,642],{"class":556}," capacities",[62,644,457],{"class":552},[62,646,647],{"class":556},"space",[62,649,457],{"class":552},[62,651,652],{"class":597},"get",[62,654,655],{"class":556},"()\n",[62,657,658,660,662,665,668,671,673,675,677,680,682,684,686,688,691,693,695,698,700,702],{"class":64,"line":424},[62,659,585],{"class":584},[62,661,553],{"class":552},[62,663,664],{"class":556}," results ",[62,666,667],{"class":552},"}",[62,669,670],{"class":552}," =",[62,672,639],{"class":548},[62,674,642],{"class":556},[62,676,457],{"class":552},[62,678,679],{"class":556},"objects",[62,681,457],{"class":552},[62,683,323],{"class":597},[62,685,600],{"class":556},[62,687,603],{"class":552},[62,689,690],{"class":606}," query",[62,692,610],{"class":552},[62,694,566],{"class":552},[62,696,697],{"class":569},"my note",[62,699,618],{"class":552},[62,701,560],{"class":552},[62,703,623],{"class":556},[62,705,706,709,711,713,715,717,720,722,725,727,729,732,734,736,739,742,745,747,749],{"class":64,"line":430},[62,707,708],{"class":548},"await",[62,710,642],{"class":556},[62,712,457],{"class":552},[62,714,483],{"class":556},[62,716,457],{"class":552},[62,718,719],{"class":556},"dailyNote",[62,721,457],{"class":552},[62,723,724],{"class":597},"append",[62,726,600],{"class":556},[62,728,603],{"class":552},[62,730,731],{"class":606}," markdown",[62,733,610],{"class":552},[62,735,566],{"class":552},[62,737,738],{"class":569},"## Today",[62,740,741],{"class":556},"\\n",[62,743,744],{"class":569},"Some text",[62,746,618],{"class":552},[62,748,560],{"class":552},[62,750,623],{"class":556},[32,752,754],{"id":753},"checklist","Checklist",[756,757,760,778,787,804,813,822],"ul",{"className":758},[759],"contains-task-list",[761,762,765,769,770,773,774,777],"li",{"className":763},[764],"task-list-item",[766,767],"input",{"disabled":578,"type":768},"checkbox"," Generate a new ",[14,771,772],{},"per-space API token"," in Capacities settings (",[14,775,776],{},"Settings > Capacities API",")",[761,779,781,783,784,786],{"className":780},[764],[766,782],{"disabled":578,"type":768}," Remove all ",[48,785,50],{}," parameters from request bodies and query strings",[761,788,790,792,793,795,796,799,800,280,802],{"className":789},[764],[766,791],{"disabled":578,"type":768}," Replace ",[48,794,157],{}," + ",[48,797,798],{},"GET /space-info"," with ",[48,801,162],{},[48,803,177],{},[761,805,807,792,809,799,811],{"className":806},[764],[766,808],{"disabled":578,"type":768},[48,810,190],{},[48,812,195],{},[761,814,816,792,818,799,820],{"className":815},[764],[766,817],{"disabled":578,"type":768},[48,819,209],{},[48,821,214],{},[761,823,825,792,827,799,829,831,832,834,835,777],{"className":824},[764],[766,826],{"disabled":578,"type":768},[48,828,227],{},[48,830,232],{}," (rename ",[48,833,468],{}," → ",[48,836,479],{},[838,839,840],"style",{},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .s7zQu, html code.shiki .s7zQu{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#89DDFF;--shiki-default-font-style:italic;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html pre.shiki code .sTEyZ, html code.shiki .sTEyZ{--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8}html pre.shiki code .sfazB, html code.shiki .sfazB{--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D}html pre.shiki code .spNyl, html code.shiki .spNyl{--shiki-light:#9C3EDA;--shiki-default:#C792EA;--shiki-dark:#C792EA}html pre.shiki code .s2Zo4, html code.shiki .s2Zo4{--shiki-light:#6182B8;--shiki-default:#82AAFF;--shiki-dark:#82AAFF}html pre.shiki code .swJcz, html code.shiki .swJcz{--shiki-light:#E53935;--shiki-default:#F07178;--shiki-dark:#F07178}",{"title":58,"searchDepth":65,"depth":71,"links":842},[843,847,848,855,856],{"id":34,"depth":71,"text":35,"children":844},[845,846],{"id":42,"depth":77,"text":43},{"id":83,"depth":77,"text":84},{"id":123,"depth":71,"text":124},{"id":241,"depth":71,"text":242,"children":849},[850,851,852,853,854],{"id":245,"depth":77,"text":246},{"id":287,"depth":77,"text":288},{"id":323,"depth":77,"text":201},{"id":380,"depth":77,"text":220},{"id":460,"depth":77,"text":238},{"id":524,"depth":71,"text":525},{"id":753,"depth":71,"text":754},"How to migrate from the beta API to API v1.","md",null,{},"/api/overview/migration",{"title":5,"description":857},"api/1.overview/migration","H6sspGYzo8XAsiOeFnS6NAoF2tkvj4uqW0k8IYzX6HA",[866,870],{"title":867,"path":868,"stem":869,"children":-1},"Errors","/api/overview/errors","api/1.overview/errors",{"title":871,"path":872,"stem":873,"children":-1},"Rate Limiting","/api/overview/rate-limiting","api/1.overview/rate-limiting",1781012285112]