{"openapi":"3.1.0","info":{"title":"Kanorio Agent API","version":"1.0.0","summary":"Create, edit, publish and connect domains for Kanorio websites.","description":"REST surface of the Kanorio capabilities registry. The same capabilities are exposed as MCP tools at https://app.kanorio.com/api/mcp (operationId equals the MCP tool name). All writes are drafts until `site.publish`. Errors use `{ error: { code, message, details? } }`; `CONFLICT` means re-read the page and retry with the new `updatedAt`. Stability: beta. Each operation carries x-kanorio-stability; deprecated operations are flagged with `deprecated: true`, x-kanorio-sunset and (when available) x-kanorio-replaced-by, and REST responses carry Deprecation and Sunset headers. Policy: https://kanorio.com/en/help/rest-api. Changelog: https://kanorio.com/developers/api/changelog.","contact":{"url":"https://kanorio.com/en/help/connect-ai-assistant"},"x-kanorio-stability":"beta","x-kanorio-stability-policy":"https://kanorio.com/en/help/rest-api","x-kanorio-changelog":"https://kanorio.com/developers/api/changelog"},"servers":[{"url":"https://app.kanorio.com/api/v1"}],"tags":[{"name":"sections"},{"name":"sites"},{"name":"jobs"},{"name":"site"},{"name":"globals"},{"name":"pages"},{"name":"domains"},{"name":"media"},{"name":"posts"},{"name":"blog_categories"},{"name":"blog_tags"},{"name":"collections"},{"name":"items"},{"name":"webhooks"},{"name":"forms"},{"name":"submissions"},{"name":"contacts"},{"name":"segments"},{"name":"deliverables"},{"name":"deliverable_units"},{"name":"entitlements"},{"name":"progress"},{"name":"products"},{"name":"product_categories"},{"name":"orders"},{"name":"campaigns"},{"name":"analytics"},{"name":"revisions"}],"paths":{"/sections":{"get":{"operationId":"sections_describe","summary":"sections.describe","description":"List the section (module) types that can be placed on a page, with an English name, description, category and, in full mode, the JSON Schema (draft 2020-12) each section object must satisfy. Call this before pages.replace_sections. Without `types` you get a compact summary of all types; pass `types` (or detail=full) to receive the schemas. Pass `websiteId` to learn which types are available on that website's plan (sets `available`); this requires the editor:enter scope on that website. Errors: FORBIDDEN (no access to websiteId), WEBSITE_NOT_FOUND.","tags":["sections"],"x-kanorio-stability":"beta","parameters":[{"name":"websiteId","in":"query","required":false,"description":"Optional. When set, `available` reflects that website's plan; needs editor:enter.","schema":{"description":"Optional. When set, `available` reflects that website's plan; needs editor:enter.","type":"string","minLength":1}},{"name":"types","in":"query","required":false,"description":"Return only these section types, with full JSON Schemas.","schema":{"description":"Return only these section types, with full JSON Schemas.","maxItems":60,"type":"array","items":{"type":"string"}},"style":"form","explode":false,"example":["hero","faq"]},{"name":"detail","in":"query","required":false,"description":"summary (default when `types` is omitted) or full (schemas included).","schema":{"description":"summary (default when `types` is omitted) or full (schemas included).","type":"string","enum":["summary","full"]},"example":"summary"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"sections":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"categories":{"type":"array","items":{"type":"string"}},"minimumPlan":{"anyOf":[{"type":"string"},{"type":"null"}]},"available":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["type","name","description","categories","minimumPlan","available"],"additionalProperties":false}},"conventions":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["sections","conventions"],"additionalProperties":false},"example":{"sections":[{"type":"hero","name":"Hero","description":"Full-width opening section with headline, subtitle, image and buttons.","categories":["intro"],"minimumPlan":null,"available":true},{"type":"faq","name":"FAQ","description":"Question and answer list.","categories":["content"],"minimumPlan":null,"available":true}],"conventions":{"brandFirst":"Set brand colors and buttons before filling pages."}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"sections.describe","x-kanorio-mcp-tool":"sections_describe","x-kanorio-required-scope":null,"x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites":{"get":{"operationId":"sites_list","summary":"sites.list","description":"List the websites the token owner is a member of, restricted to the websites the token was granted for. Returns ids you need for every other site-scoped call. Errors: none beyond FORBIDDEN when the token lacks console:view.","tags":["sites"],"x-kanorio-stability":"beta","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The token owner's role on this website (OWNER/ADMIN/MEMBER/VIEWER)."},"plan":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Content language of the site (e.g. zh-Hant, en-US)."},"status":{"type":"string"},"isPublished":{"type":"boolean"},"subdomain":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Assigned on first publish; null until then."},"suggestedSubdomain":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Suggested slug to use when publishing for the first time."},"publicUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"https URL on kanorio.com when published."},"primaryCustomDomain":{"anyOf":[{"type":"object","properties":{"hostname":{"type":"string"},"status":{"type":"string"}},"required":["hostname","status"],"additionalProperties":false},{"type":"null"}]},"lastPublishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasUnpublishedChanges":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","role","plan","locale","status","isPublished","subdomain","suggestedSubdomain","publicUrl","primaryCustomDomain","lastPublishedAt","hasUnpublishedChanges","createdAt","updatedAt"],"additionalProperties":false}}},"required":["sites"],"additionalProperties":false},"example":{"sites":[{"id":"ws_example123","name":"Sunny Bakery","role":"OWNER","plan":"PRO","locale":"zh-Hant","status":"ACTIVE","isPublished":true,"subdomain":"sunny-bakery","suggestedSubdomain":"sunny-bakery","publicUrl":"https://sunny-bakery.kanorio.com","primaryCustomDomain":{"hostname":"www.sunnybakery.example","status":"ACTIVE"},"lastPublishedAt":"2026-10-01T02:30:00.000Z","hasUnpublishedChanges":true,"createdAt":"2026-08-12T03:20:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"sites.list","x-kanorio-mcp-tool":"sites_list","x-kanorio-required-scope":"console:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"sites_create","summary":"sites.create","description":"Create a new website owned by the token owner. Requires a token granted for all websites (not restricted to specific websiteIds). mode=blank: creates the skeleton immediately (empty home page, hidden legal pages, a default header and footer in globalSections, owner membership) and returns websiteId. Then follow sections.describe -> conventions.brandFirst: set the theme (site.update_settings), define buttons (globals.update_site_settings), create pages, fill them with pages.replace_sections, rebuild the header navigation (globals.replace_header) and publish. mode=brief: queues the AI site builder with a brand brief and returns jobId; poll jobs.get every 5-10 seconds until status is SUCCEEDED (websiteId is set) or FAILED. This consumes the owner's AI credits and daily site-creation quota. Errors: TOKEN_WEBSITE_SCOPED, VALIDATION, DAILY_LIMIT_REACHED (brief).","tags":["sites"],"x-kanorio-stability":"beta","parameters":[],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["blank","brief"]},"websiteId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Set immediately for blank; for brief it appears on jobs.get once the job succeeds."},"jobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Job status for brief mode."}},"required":["mode","websiteId","jobId","status"],"additionalProperties":false},"example":{"mode":"blank","websiteId":"ws_example123","jobId":null,"status":null}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"sites.create","x-kanorio-mcp-tool":"sites_create","x-kanorio-required-scope":"console:view","x-kanorio-read-only":false,"x-kanorio-requires-unscoped-token":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}":{"get":{"operationId":"sites_get","summary":"sites.get","description":"Get one website's summary: plan, publish state, subdomain, primary custom domain and whether there are unpublished changes. Errors: FORBIDDEN, WEBSITE_NOT_FOUND.","tags":["sites"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The token owner's role on this website (OWNER/ADMIN/MEMBER/VIEWER)."},"plan":{"type":"string"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Content language of the site (e.g. zh-Hant, en-US)."},"status":{"type":"string"},"isPublished":{"type":"boolean"},"subdomain":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Assigned on first publish; null until then."},"suggestedSubdomain":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Suggested slug to use when publishing for the first time."},"publicUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"https URL on kanorio.com when published."},"primaryCustomDomain":{"anyOf":[{"type":"object","properties":{"hostname":{"type":"string"},"status":{"type":"string"}},"required":["hostname","status"],"additionalProperties":false},{"type":"null"}]},"lastPublishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasUnpublishedChanges":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","role","plan","locale","status","isPublished","subdomain","suggestedSubdomain","publicUrl","primaryCustomDomain","lastPublishedAt","hasUnpublishedChanges","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"ws_example123","name":"Sunny Bakery","role":"OWNER","plan":"PRO","locale":"zh-Hant","status":"ACTIVE","isPublished":true,"subdomain":"sunny-bakery","suggestedSubdomain":"sunny-bakery","publicUrl":"https://sunny-bakery.kanorio.com","primaryCustomDomain":{"hostname":"www.sunnybakery.example","status":"ACTIVE"},"lastPublishedAt":"2026-10-01T02:30:00.000Z","hasUnpublishedChanges":true,"createdAt":"2026-08-12T03:20:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"sites.get","x-kanorio-mcp-tool":"sites_get","x-kanorio-required-scope":"console:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/structure":{"get":{"operationId":"sites_structure","summary":"sites.structure","description":"Return the visual sitemap tree of a website: top-level pages with nested subpages (up to 3 levels), real page status (published / changed / draft / hidden), the ordered list of section types on each page, and summary counts for Kanorio-managed Store and Blog pages. Errors: FORBIDDEN, WEBSITE_NOT_FOUND.","tags":["sites"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"websiteId":{"type":"string"},"totalGeneralPages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"maxDepth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rootPages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"pageType":{"type":"string"},"isHomePage":{"type":"boolean"},"isVisible":{"type":"boolean"},"isDirectory":{"type":"boolean"},"status":{"type":"string","enum":["published","changed","draft","hidden"]},"path":{"type":"array","items":{"type":"string"}},"parentSlug":{"anyOf":[{"type":"string"},{"type":"null"}]},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sections":{"type":"array","items":{"type":"string"},"description":"Ordered list of content section types on this page (excluding global header and footer)."},"hasGlobalChrome":{"type":"boolean"},"descendantCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"children":{"type":"array","items":{"description":"Recursive: same shape as the enclosing __schema0 node."}}},"required":["id","slug","title","pageType","isHomePage","isVisible","isDirectory","status","path","parentSlug","depth","sections","hasGlobalChrome","descendantCount","children"],"additionalProperties":false}},"systemGroups":{"type":"object","properties":{"shop":{"type":"object","properties":{"basePath":{"type":"string"},"productCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"productCategoryCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["basePath","productCount","productCategoryCount"],"additionalProperties":false},"blog":{"type":"object","properties":{"basePath":{"type":"string"},"publishedPostCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"blogCategoryCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"blogTagCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["basePath","publishedPostCount","blogCategoryCount","blogTagCount"],"additionalProperties":false}},"required":["shop","blog"],"additionalProperties":false}},"required":["websiteId","totalGeneralPages","maxDepth","rootPages","systemGroups"],"additionalProperties":false},"example":{"websiteId":"ws_example123","totalGeneralPages":2,"maxDepth":1,"rootPages":[{"id":"pg_example456","slug":"/","title":"Home","pageType":"generic","isHomePage":true,"isVisible":true,"isDirectory":false,"status":"published","path":[],"parentSlug":null,"depth":0,"sections":["page-main-visual","faq"],"hasGlobalChrome":true,"descendantCount":0,"children":[]},{"id":"pg_example789","slug":"/about","title":"About Us","pageType":"generic","isHomePage":false,"isVisible":true,"isDirectory":false,"status":"published","path":["about"],"parentSlug":null,"depth":1,"sections":["image-text-split"],"hasGlobalChrome":true,"descendantCount":0,"children":[]}],"systemGroups":{"shop":{"basePath":"/shop","productCount":12,"productCategoryCount":3},"blog":{"basePath":"/blog","publishedPostCount":27,"blogCategoryCount":5,"blogTagCount":14}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"sites.structure","x-kanorio-mcp-tool":"sites_structure","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/jobs/{id}":{"get":{"operationId":"jobs_get","summary":"jobs.get","description":"Get the status of a site-generation job (from sites.create mode=brief) or a page-generation job. Poll until status is SUCCEEDED or FAILED; respect pollAfterSeconds. Errors: JOB_NOT_FOUND, FORBIDDEN.","tags":["jobs"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"kind":{"type":"string","enum":["site","page"]},"status":{"type":"string","description":"PENDING, RUNNING, SUCCEEDED, FAILED or CANCELLED."},"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"websiteId":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"failedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"pollAfterSeconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Suggested wait before polling again; null when terminal."}},"required":["jobId","kind","status","stage","websiteId","errorCode","errorMessage","createdAt","startedAt","completedAt","failedAt","pollAfterSeconds"],"additionalProperties":false},"example":{"jobId":"job_example01","kind":"site","status":"RUNNING","stage":"generating_pages","websiteId":"ws_example123","errorCode":null,"errorMessage":null,"createdAt":"2026-10-01T02:30:00.000Z","startedAt":"2026-10-01T02:30:00.000Z","completedAt":null,"failedAt":null,"pollAfterSeconds":10}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"jobs.get","x-kanorio-mcp-tool":"jobs_get","x-kanorio-required-scope":"console:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/search":{"get":{"operationId":"site_search","summary":"site.search","description":"Search the live site the way visitors do: published pages, blog posts, blog categories and tags, products and product categories. Use it to check whether the site already covers a topic before writing, or to find the page to edit. Every term in q must appear in the title or body (AND); full-width characters, case and term order do not matter. Drafts, hidden pages and pages excluded from site search are not included; an unpublished site returns no results. Errors: FORBIDDEN, VALIDATION (details.reason: QUERY_REQUIRED, QUERY_TOO_SHORT or QUERY_TOO_LONG), SEARCH_BUSY.","tags":["site"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"q","in":"query","required":true,"description":"Search terms separated by spaces (up to 4 are used). One term needs 2 CJK or Thai characters, or 3 letters or digits.","schema":{"type":"string","maxLength":400,"description":"Search terms separated by spaces (up to 4 are used). One term needs 2 CJK or Thai characters, or 3 letters or digits."},"example":"sourdough"},{"name":"kind","in":"query","required":false,"description":"Only these kinds. REST accepts kind=PAGE,PRODUCT. Omit for all kinds.","schema":{"description":"Only these kinds. REST accepts kind=PAGE,PRODUCT. Omit for all kinds.","minItems":1,"type":"array","items":{"type":"string","enum":["PAGE","COLLECTION_ITEM","PRODUCT","CATEGORY"]}},"style":"form","explode":false,"example":["PAGE","COLLECTION_ITEM"]},{"name":"limit","in":"query","required":false,"description":"Results to return (1-20, default 20).","schema":{"description":"Results to return (1-20, default 20).","type":"integer","minimum":1,"maximum":20},"example":5}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"The normalized query actually searched."},"tokens":{"type":"array","items":{"type":"string"},"description":"Terms that all had to match."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Matches before limit."},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["PAGE","COLLECTION_ITEM","PRODUCT","CATEGORY"]},"collectionKey":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Set for COLLECTION_ITEM: blog (posts), blog_categories or blog_tags."},"refId":{"type":"string","description":"Id of the source: page id, collection item id, product id or product category id."},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Source slug; null for pages (use url)."},"title":{"type":"string"},"url":{"type":"string","description":"Path on the live site, e.g. /about or /blog/hello."},"excerpt":{"type":"string"},"snippet":{"type":"string","description":"Body text around the first matching term."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"soldOut":{"type":"boolean","description":"Products with nothing left to buy; always sorted last."},"score":{"type":"number","description":"Relevance used for ordering; compare only within one response."},"product":{"anyOf":[{"type":"object","properties":{"amount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"currency":{"type":"string"},"showPlus":{"type":"boolean"},"compareAtAmount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"isPromo":{"type":"boolean"},"promoBadge":{"anyOf":[{"type":"string"},{"type":"null"}]},"rating":{"anyOf":[{"type":"number"},{"type":"null"}]},"reviewCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"totalSalesCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["amount","currency","showPlus","compareAtAmount","rating","reviewCount","totalSalesCount"],"additionalProperties":false},{"type":"null"}]},"blog":{"anyOf":[{"type":"object","properties":{"categoryName":{"anyOf":[{"type":"string"},{"type":"null"}]},"authors":{"type":"array","items":{"type":"string"}},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"readingTimeMin":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["categoryName","authors","publishedAt","readingTimeMin"],"additionalProperties":false},{"type":"null"}]}},"required":["kind","collectionKey","refId","slug","title","url","excerpt","snippet","imageUrl","soldOut","score"],"additionalProperties":false}}},"required":["q","tokens","total","items"],"additionalProperties":false},"example":{"q":"sourdough","tokens":["sourdough"],"total":2,"items":[{"kind":"PAGE","collectionKey":null,"refId":"pg_example789","slug":null,"title":"About Us","url":"/about","excerpt":"Naturally leavened sourdough baked fresh every morning.","snippet":"Every loaf starts with a sourdough starter we have fed daily since 2019.","imageUrl":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","soldOut":false,"score":0.412},{"kind":"COLLECTION_ITEM","collectionKey":"blog","refId":"post_example01","slug":"starter-guide","title":"How we keep our starter alive","url":"/blog/starter-guide","excerpt":"A week in the life of our 7-year-old starter.","snippet":"…the sourdough starter goes into the fridge on Sunday nights…","imageUrl":null,"soldOut":false,"score":0.087}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"site.search","x-kanorio-mcp-tool":"site_search","x-kanorio-required-scope":"console:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/settings":{"get":{"operationId":"site_get_settings","summary":"site.get_settings","description":"Read the website's visual theme (brand colors, fonts, corner radius, density, color scheme), content language and website currency. Errors: FORBIDDEN, WEBSITE_NOT_FOUND.","tags":["site"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"theme":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Resolved theme: typography { bodyEnFontId, bodyZhHantFontId, ... }, brandColor { light, dark } (hex), brandForeground?, sectionDensity (standard|compact), cornerRadius (sharp|normal|soft), colorScheme (system|light|dark), textSizeSettings?."},"locale":{"type":"string","description":"Content language (BCP 47)."},"currency":{"type":"string","description":"Website currency (ISO 4217, read-only here): product prices, checkout and every amount on the site use it. The owner changes it in website settings."}},"required":["theme","locale","currency"],"additionalProperties":false},"example":{"theme":{"brandColor":{"light":"#D9822B","dark":"#F0A55A"},"brandForeground":null,"typography":{"bodyZhHantFontId":"noto-sans-tc"},"cornerRadius":"soft","sectionDensity":"standard","colorScheme":"system"},"locale":"zh-Hant","currency":"TWD"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"site.get_settings","x-kanorio-mcp-tool":"site_get_settings","x-kanorio-required-scope":"site:manage_settings","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"patch":{"operationId":"site_update_settings","summary":"site.update_settings","description":"Update the website's visual theme and basic settings; only the fields you send change. brandColor { light, dark } are hex colors used for buttons, links and accents in light/dark mode; brandForeground overrides the text color on brand-colored surfaces (null resets). typography picks body font ids per script (bodyEnFontId, bodyZhHantFontId, bodyZhHansFontId, bodyJaFontId, bodyKoFontId). cornerRadius: sharp | normal | soft; sectionDensity: standard | compact; colorScheme: system | light | dark. locale changes the content language (fonts, HTML lang, legal pages). The website currency can't be changed here: it re-labels every price and is limited by the connected payment providers, so the owner changes it in website settings. Do this before filling pages so the brand colors apply everywhere. Theme changes are draft until site.publish. Errors: FORBIDDEN, WEBSITE_NOT_FOUND, VALIDATION (details lists the failing field), WRITE_FROZEN.","tags":["site"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"typography":{"type":"object","properties":{"bodyEnFontId":{"type":"string"},"bodyZhHantFontId":{"type":"string"},"bodyZhHansFontId":{"type":"string"},"bodyJaFontId":{"type":"string"},"bodyKoFontId":{"type":"string"}}},"brandColor":{"type":"object","properties":{"light":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dark":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"required":["light","dark"]},"brandForeground":{"anyOf":[{"type":"object","properties":{"light":{"anyOf":[{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},{"type":"null"}]},"dark":{"anyOf":[{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},{"type":"null"}]}}},{"type":"null"}]},"sectionDensity":{"type":"string","enum":["standard","compact"]},"cornerRadius":{"type":"string","enum":["sharp","normal","soft"]},"colorScheme":{"type":"string","enum":["system","light","dark"]},"textSizeSettings":{"anyOf":[{"type":"object","properties":{"h1":{"type":"integer","minimum":1,"maximum":9},"h2":{"type":"integer","minimum":1,"maximum":9},"h3":{"type":"integer","minimum":1,"maximum":9},"body":{"type":"integer","minimum":1,"maximum":9}}},{"type":"null"}]},"locale":{"type":"string","enum":["ar","bn","bg","my","zh-CN","zh-HK","zh-Hant","cs","da","nl-BE","nl-NL","en-AU","en-CA","en-GB","en-US","tl","fi","fr-CA","fr-FR","de","el","gu","he","hi","hu","id","it","ja","kn","km","ko","lo","ms","ml","mr","ne","nb","nn","fa","pl","pt-BR","pt-PT","pa","ro","ru","si","es-419","es-ES","sw","sv","ta","te","th","tr","uk","ur","vi"]}},"description":"Fields to change; omitted fields keep their current value."}},"required":["settings"]},"example":{"settings":{"brandColor":{"light":"#D9822B","dark":"#F0A55A"},"cornerRadius":"soft"}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"theme":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Resolved theme: typography { bodyEnFontId, bodyZhHantFontId, ... }, brandColor { light, dark } (hex), brandForeground?, sectionDensity (standard|compact), cornerRadius (sharp|normal|soft), colorScheme (system|light|dark), textSizeSettings?."},"locale":{"type":"string","description":"Content language (BCP 47)."},"currency":{"type":"string","description":"Website currency (ISO 4217, read-only here): product prices, checkout and every amount on the site use it. The owner changes it in website settings."}},"required":["theme","locale","currency"],"additionalProperties":false},"example":{"theme":{"brandColor":{"light":"#D9822B","dark":"#F0A55A"},"brandForeground":null,"typography":{"bodyZhHantFontId":"noto-sans-tc"},"cornerRadius":"soft","sectionDensity":"standard","colorScheme":"system"},"locale":"zh-Hant","currency":"TWD"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"site.update_settings","x-kanorio-mcp-tool":"site_update_settings","x-kanorio-required-scope":"site:manage_settings","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/globals":{"get":{"operationId":"globals_get","summary":"globals.get","description":"Read the site-level draft shared by all pages: the primary header and footer (from globalSections), siteSettings (customButtons referenced by sections via ctaIds, socialLinks) and the revision marker contentUpdatedAt. Call it before globals.replace_header / globals.replace_footer / globals.update_site_settings and pass contentUpdatedAt back as ifUnmodifiedSince. Images of the site's media library appear as asset:<assetId>; assets holds them (with display URLs). Errors: FORBIDDEN, WEBSITE_NOT_FOUND.","tags":["globals"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"header":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Primary header section, or null when the site has none yet."},"footer":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"sharedSections":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"description":"Other shared content sections; pages embed them with a global-section-ref item."},"siteSettings":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files referenced as asset:<assetId>, by assetId."},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Revision marker of the site-level draft (Website.contentUpdatedAt). Pass it back as ifUnmodifiedSince."}},"required":["header","footer","sharedSections","siteSettings","assets","contentUpdatedAt"],"additionalProperties":false},"example":{"header":{"id":"sec_header01","type":"header","navItems":[{"id":"nav_home","text":"Home","linkType":"internal","pageSlug":"/"},{"id":"nav_about","text":"About Us","linkType":"internal","pageSlug":"/about"}],"ctaIds":["btn_order"]},"footer":{"id":"sec_footer01","type":"footer","copyright":"© 2026 Sunny Bakery"},"sharedSections":[{"id":"sec_header01","type":"header"},{"id":"sec_footer01","type":"footer"}],"siteSettings":{"customButtons":[{"id":"btn_order","text":"Order online","url":"/shop","style":"brand"}],"socialLinks":[{"platform":"instagram","url":"https://www.instagram.com/sunnybakery.example"}]},"assets":{},"contentUpdatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"globals.get","x-kanorio-mcp-tool":"globals_get","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/globals/headers":{"get":{"operationId":"globals_list_headers","summary":"globals.list_headers","description":"List all headers in globalSections: the primary header plus any secondary headers created for specific pages (ADR-0001). Most websites only need the primary header. Errors: FORBIDDEN, WEBSITE_NOT_FOUND.","tags":["globals"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"headers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass this id to pages.update globalHeaderId to assign the header to a page."},"key":{"type":"string"},"isPrimary":{"type":"boolean"},"header":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","key","isPrimary","header"],"additionalProperties":false}},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files referenced as asset:<assetId>, by assetId."},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Revision marker of the site-level draft (Website.contentUpdatedAt). Pass it back as ifUnmodifiedSince."}},"required":["headers","assets","contentUpdatedAt"],"additionalProperties":false},"example":{"headers":[{"id":"sec_header01","key":"primary","isPrimary":true,"header":{"id":"sec_header01","type":"header","navItems":[{"id":"nav_home","text":"Home","linkType":"internal","pageSlug":"/"},{"id":"nav_about","text":"About Us","linkType":"internal","pageSlug":"/about"}],"ctaIds":["btn_order"]}}],"assets":{},"contentUpdatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"globals.list_headers","x-kanorio-mcp-tool":"globals_list_headers","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"globals_create_header","summary":"globals.create_header","description":"Create a secondary header in globalSections with a human-readable key. Only use this when specific pages need a different navigation bar (for example a sub-brand or campaign microsite); most websites only need the primary header. After creating the header, assign its returned id to a page with pages.update({ globalHeaderId }). Saved as draft only; call site.publish to go live. Errors: FORBIDDEN, WEBSITE_NOT_FOUND, VALIDATION, KEY_TAKEN, CONFLICT, WRITE_FROZEN, ASSET_NOT_FOUND (details.assetIds: not in this site's media library), ASSET_NOT_ALLOWED (product files cannot be shown on pages).","tags":["globals"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ifUnmodifiedSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"contentUpdatedAt from globals.get. Required: the write is rejected with CONFLICT when the site-level draft changed since (details.contentUpdatedAt holds the current value)."},"key":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$","description":"Unique header key (a-z, 0-9, hyphen, underscore; 1-40 chars). 'primary' refers to the main site header."},"header":{"type":"object","properties":{"type":{"type":"string","const":"header"},"id":{"type":"string","minLength":1,"description":"Stable id; pages reference it via globalHeaderId."},"key":{"description":"Human-readable key for this header (e.g. 'primary', 'campaign', 'docs').","type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"cta":{"type":"object","properties":{"id":{"type":"string"},"icon":{"enum":["briefcase","star","award","crown","flame","zap","target","rocket","flag","gem","diamond","scroll","fingerprint","smile","laugh","clock","phone","mail","bell","settings","check-circle","info","help-circle","headset","megaphone","newspaper","hourglass","stamp","milestone","quote","table","list-ordered","list-checks","arrow-right","message-circle","external-link","download","play","pause","bookmark","search","filter","thumbs-up","share-2","eye","phone-call","send","lock","rotate-ccw","clipboard-check","alarm-clock","utensils","utensils-crossed","chef-hat","coffee","pizza","soup","ice-cream-cone","sandwich","beef","fish","salad","cookie","cake","cake-slice","dessert","cup-soda","wine","beer","martini","milk","wheat","egg","croissant","popcorn","candy","apple","cherry","banana","citrus","grape","carrot","drumstick","cooking-pot","shrimp","donut","bean","vegan","store","shopping-bag","shopping-cart","shopping-basket","package","package-check","boxes","truck","motorbike","warehouse","tag","tags","ticket-percent","barcode","qr-code","scan-qr-code","credit-card","smartphone-nfc","wallet","banknote","coins","dollar-sign","percent","badge-percent","receipt","shirt","heart","heart-pulse","stethoscope","hospital","syringe","pill","pill-bottle","bandage","cross","thermometer","briefcase-medical","scissors","sparkles","scan-face","hand","bath","droplet","droplets","flower","flower-2","sun","moon","book-open","book-text","book-copy","book-marked","book-check","graduation-cap","school","library","monitor-play","backpack","pencil","pen-tool","file-text","scroll-text","notebook-pen","languages","calculator","presentation","lightbulb","brain","puzzle","laptop","monitor","smartphone","tablet","code","code-2","terminal","server","database","cloud","cpu","globe","network","circuit-board","brain-circuit","bot","blocks","palette","brush","paint-bucket","pen-line","image","image-plus","camera","video","film","clapperboard","music","music-2","music-4","mic","mic-2","headphones","speaker","radio","podcast","piano","plane","map-pin","map-pinned","navigation","route","compass","mountain","tree-pine","trees","tent","umbrella","anchor","ship","car","bike","bus","train","luggage","hotel","bed-double","concierge-bell","wifi","parking-square","air-vent","washing-machine","cigarette-off","accessibility","dumbbell","biceps-flexed","footprints","timer","watch","medal","trophy","swords","badge-check","activity","building","building-2","factory","house","house-plus","map-pin-house","door-open","door-closed","key","key-round","fence","sofa","ruler","hard-hat","hammer","wrench","paint-roller","brush-cleaning","cat","dog","bird","rabbit","squirrel","paw-print","bone","leaf","sprout","clover","tractor","cloud-sun","cloud-rain","snowflake","leafy-green","tree-deciduous","wind","waves","recycle","landmark","vault","scale","gavel","shield","shield-check","badge-dollar-sign","hand-coins","trending-up","trending-down","bar-chart","bar-chart-2","bar-chart-3","pie-chart","line-chart","chart-no-axes-combined","users","users-round","user-circle","user-plus","hand-heart","hand-helping","heart-handshake","handshake","baby","church","party-popper","sparkle","gift","ticket","calendar","calendar-days","calendar-check","calendar-clock"],"type":"string"},"text":{"type":"string","maxLength":250},"url":{"description":"Optional link: absolute http(s)/tel:/mailto: URL, site-relative path (/about) or anchor (#id).","type":"string"},"style":{"type":"string","enum":["brand","default","ghost"]}}},"ctaId":{"description":"Legacy single button id from siteSettings.customButtons. Prefer ctaIds; when both are set ctaIds wins.","type":"string"},"ctaIds":{"description":"Up to 2 ids of buttons defined in siteSettings.customButtons, shown at the right of the header (and at the bottom of the side-left sidebar / mobile menu).","maxItems":3,"type":"array","items":{"type":"string"}},"ctaStyleById":{"description":"Per-button style override keyed by customButton id: brand (filled brand color), default (neutral), or ghost (text with arrow).","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","enum":["brand","default","ghost"]}},"layout":{"description":"Desktop header layout: top-spread (default), top-left (nav next to logo), top-center (centered nav), or side-left (fixed left sidebar).","type":"string","enum":["top-spread","top-left","top-center","side-left"]},"surface":{"description":"Header background tone: default (light bar with blur), muted, tint, brand or contrast; text colors adapt automatically. auto behaves like default.","type":"string","enum":["auto","default","muted","tint","brand","contrast"]},"showBrandLogo":{"description":"Show the brand logo (default true). When false and showSiteName is false, nothing is rendered in the brand slot.","type":"boolean"},"showSiteName":{"description":"Show the website name next to (or instead of) the logo (default false; the name is still shown when no logo exists).","type":"boolean"},"logoSize":{"description":"Logo size in the header (default md).","type":"string","enum":["sm","md","lg"]},"showSocialLinks":{"description":"Show siteSettings.socialLinks in the header, either for every device (boolean) or per device. Defaults: desktop only for the side-left layout, tablet and mobile menu on.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"desktop":{"type":"boolean"},"tablet":{"type":"boolean"},"mobile":{"type":"boolean"}}}]},"hiddenSocialLinkUrls":{"description":"Urls from siteSettings.socialLinks to hide in this section (blacklist; omitted or empty shows all).","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048}},"hiddenSocialLinkUrlsByDevice":{"description":"Per-device blacklist of social link urls; a device without its own list falls back to hiddenSocialLinkUrls.","type":"object","properties":{"desktop":{"description":"Urls from siteSettings.socialLinks to hide in this section (blacklist; omitted or empty shows all).","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048}},"tablet":{"description":"Urls from siteSettings.socialLinks to hide in this section (blacklist; omitted or empty shows all).","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048}},"mobile":{"description":"Urls from siteSettings.socialLinks to hide in this section (blacklist; omitted or empty shows all).","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048}}}},"variant":{"description":"Deprecated and ignored: the header background is controlled by surface. Accepted for backward compatibility.","type":"string","enum":["solid","transparent","glass"]},"shrinkOnScroll":{"description":"Compact the header after scrolling (default true).","type":"boolean"},"showProgressBar":{"type":"boolean"},"showAccentLine":{"description":"Show a thin brand-gradient line at the bottom edge (default false).","type":"boolean"},"isVisible":{"type":"boolean"},"navItems":{"description":"Navigation links. The header never lists pages automatically; add one internal item per visible page.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","minLength":1,"maxLength":250},"linkType":{"type":"string","enum":["internal","external","group"]},"pageSlug":{"type":"string"},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"},"externalUrl":{"description":"Optional link: absolute http(s)/tel:/mailto: URL, site-relative path (/about) or anchor (#id).","type":"string"},"openInNewTab":{"type":"boolean"},"children":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","minLength":1,"maxLength":250},"linkType":{"type":"string","enum":["internal","external"]},"pageSlug":{"type":"string"},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"},"externalUrl":{"description":"Optional link: absolute http(s)/tel:/mailto: URL, site-relative path (/about) or anchor (#id).","type":"string"},"openInNewTab":{"type":"boolean"},"link":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"}},"required":["kind","pageId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-post"},"postId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","postId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-tag"},"tagId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","tagId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-author"},"authorId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","authorId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"product-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"external"},"url":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","url"]}]}},"required":["id","text","linkType"]}},"link":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"}},"required":["kind","pageId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-post"},"postId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","postId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-tag"},"tagId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","tagId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-author"},"authorId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","authorId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"product-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"external"},"url":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","url"]}]}},"required":["id","text","linkType"]}},"utilities":{"description":"Header utility buttons (site features shown at the right of the header, after the CTA buttons), in display order; each id at most once. enabled shows or hides it; an omitted id keeps its default (search: off, cart: on; newly created sites default both to on). A utility only renders when the site has that feature: search needs a published site with searchable content; cart needs the shopping cart turned on in store settings and at least one active product. On phones only the first 2 visible utilities stay next to the menu button; the rest move to the top of the mobile menu.","maxItems":2,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["search","cart"],"description":"search: site search button; cart: shopping cart button."},"enabled":{"type":"boolean"}},"required":["id","enabled"]}},"isGlobal":{"type":"boolean"},"logoOverride":{"description":"Header-specific logo (e.g. a wide wordmark). Omit to use the website's brand logo.","allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["image","icon"]},"url":{"description":"Required when type is image.","type":"string","format":"uri"},"icon":{"description":"Required when type is icon; one of the curated logo icon names.","type":"string","enum":["briefcase","star","award","crown","flame","zap","target","rocket","flag","gem","diamond","scroll","fingerprint","smile","laugh","clock","phone","mail","bell","settings","check-circle","info","help-circle","headset","megaphone","newspaper","hourglass","stamp","milestone","utensils","utensils-crossed","chef-hat","coffee","pizza","soup","ice-cream-cone","sandwich","beef","fish","salad","cookie","cake","cake-slice","dessert","cup-soda","wine","beer","martini","milk","wheat","egg","croissant","popcorn","candy","apple","cherry","banana","citrus","grape","carrot","drumstick","cooking-pot","shrimp","donut","bean","vegan","store","shopping-bag","shopping-cart","shopping-basket","package","package-check","boxes","truck","motorbike","warehouse","tag","tags","ticket-percent","barcode","qr-code","scan-qr-code","credit-card","smartphone-nfc","wallet","banknote","coins","dollar-sign","percent","badge-percent","receipt","shirt","heart","heart-pulse","stethoscope","hospital","syringe","pill","pill-bottle","bandage","cross","thermometer","briefcase-medical","scissors","sparkles","scan-face","hand","bath","droplet","droplets","flower","flower-2","sun","moon","book-open","book-text","book-copy","book-marked","book-check","graduation-cap","school","library","monitor-play","backpack","pencil","pen-tool","file-text","scroll-text","notebook-pen","languages","calculator","presentation","lightbulb","brain","puzzle","laptop","monitor","smartphone","tablet","code","code-2","terminal","server","database","cloud","cpu","globe","network","circuit-board","brain-circuit","bot","blocks","palette","brush","paint-bucket","pen-line","image","image-plus","camera","video","film","clapperboard","music","music-2","music-4","mic","mic-2","headphones","speaker","radio","podcast","piano","plane","map-pin","map-pinned","navigation","route","compass","mountain","tree-pine","trees","tent","umbrella","anchor","ship","car","bike","bus","train","luggage","hotel","bed-double","concierge-bell","wifi","parking-square","air-vent","washing-machine","cigarette-off","accessibility","dumbbell","biceps-flexed","footprints","timer","watch","medal","trophy","swords","badge-check","activity","building","building-2","factory","house","house-plus","map-pin-house","door-open","door-closed","key","key-round","fence","sofa","ruler","hard-hat","hammer","wrench","paint-roller","brush-cleaning","cat","dog","bird","rabbit","squirrel","paw-print","bone","leaf","sprout","clover","tractor","cloud-sun","cloud-rain","snowflake","leafy-green","tree-deciduous","wind","waves","recycle","landmark","vault","scale","gavel","shield","shield-check","badge-dollar-sign","hand-coins","trending-up","trending-down","bar-chart","bar-chart-2","bar-chart-3","pie-chart","line-chart","chart-no-axes-combined","users","users-round","user-circle","user-plus","hand-heart","hand-helping","heart-handshake","handshake","baby","church","party-popper","sparkle","gift","ticket","calendar","calendar-days","calendar-check","calendar-clock"]}},"required":["type"]},{"type":"object","properties":{"dark":{"type":"object","properties":{"type":{"type":"string","enum":["image","icon"]},"url":{"description":"Required when type is image.","type":"string","format":"uri"},"icon":{"description":"Required when type is icon; one of the curated logo icon names.","type":"string","enum":["briefcase","star","award","crown","flame","zap","target","rocket","flag","gem","diamond","scroll","fingerprint","smile","laugh","clock","phone","mail","bell","settings","check-circle","info","help-circle","headset","megaphone","newspaper","hourglass","stamp","milestone","utensils","utensils-crossed","chef-hat","coffee","pizza","soup","ice-cream-cone","sandwich","beef","fish","salad","cookie","cake","cake-slice","dessert","cup-soda","wine","beer","martini","milk","wheat","egg","croissant","popcorn","candy","apple","cherry","banana","citrus","grape","carrot","drumstick","cooking-pot","shrimp","donut","bean","vegan","store","shopping-bag","shopping-cart","shopping-basket","package","package-check","boxes","truck","motorbike","warehouse","tag","tags","ticket-percent","barcode","qr-code","scan-qr-code","credit-card","smartphone-nfc","wallet","banknote","coins","dollar-sign","percent","badge-percent","receipt","shirt","heart","heart-pulse","stethoscope","hospital","syringe","pill","pill-bottle","bandage","cross","thermometer","briefcase-medical","scissors","sparkles","scan-face","hand","bath","droplet","droplets","flower","flower-2","sun","moon","book-open","book-text","book-copy","book-marked","book-check","graduation-cap","school","library","monitor-play","backpack","pencil","pen-tool","file-text","scroll-text","notebook-pen","languages","calculator","presentation","lightbulb","brain","puzzle","laptop","monitor","smartphone","tablet","code","code-2","terminal","server","database","cloud","cpu","globe","network","circuit-board","brain-circuit","bot","blocks","palette","brush","paint-bucket","pen-line","image","image-plus","camera","video","film","clapperboard","music","music-2","music-4","mic","mic-2","headphones","speaker","radio","podcast","piano","plane","map-pin","map-pinned","navigation","route","compass","mountain","tree-pine","trees","tent","umbrella","anchor","ship","car","bike","bus","train","luggage","hotel","bed-double","concierge-bell","wifi","parking-square","air-vent","washing-machine","cigarette-off","accessibility","dumbbell","biceps-flexed","footprints","timer","watch","medal","trophy","swords","badge-check","activity","building","building-2","factory","house","house-plus","map-pin-house","door-open","door-closed","key","key-round","fence","sofa","ruler","hard-hat","hammer","wrench","paint-roller","brush-cleaning","cat","dog","bird","rabbit","squirrel","paw-print","bone","leaf","sprout","clover","tractor","cloud-sun","cloud-rain","snowflake","leafy-green","tree-deciduous","wind","waves","recycle","landmark","vault","scale","gavel","shield","shield-check","badge-dollar-sign","hand-coins","trending-up","trending-down","bar-chart","bar-chart-2","bar-chart-3","pie-chart","line-chart","chart-no-axes-combined","users","users-round","user-circle","user-plus","hand-heart","hand-helping","heart-handshake","handshake","baby","church","party-popper","sparkle","gift","ticket","calendar","calendar-days","calendar-check","calendar-clock"]}},"required":["type"]}}}]}},"required":["type","id"],"description":"Complete header object. navItems is the navigation: one { id, text, linkType: \"internal\", pageSlug } per visible page (the header never lists pages automatically); use ctaIds (up to 2) to show buttons from siteSettings.customButtons. layout picks the desktop arrangement (top-spread, top-left, top-center, side-left), surface the background tone; showBrandLogo / showSiteName / logoSize control the brand slot and showSocialLinks (boolean or per device) plus hiddenSocialLinkUrls choose which social links appear; utilities orders and toggles the feature buttons (search, cart) after the CTA buttons. The logo comes from the website's brand settings unless logoOverride is set."}},"required":["ifUnmodifiedSince","key","header"]},"example":{"ifUnmodifiedSince":"2026-10-06T08:00:00.000Z","key":"campaign","header":{"id":"hdr_campaign_01","type":"header","navItems":[{"id":"nav_home","text":"Home","linkType":"internal","pageSlug":"/"},{"id":"nav_about","text":"About Us","linkType":"internal","pageSlug":"/about"}],"ctaIds":["btn_order"],"key":"campaign"}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"isPrimary":{"type":"boolean","const":false},"header":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files referenced as asset:<assetId>, by assetId."},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Revision marker of the site-level draft (Website.contentUpdatedAt). Pass it back as ifUnmodifiedSince."}},"required":["key","isPrimary","header","assets","contentUpdatedAt"],"additionalProperties":false},"example":{"key":"campaign","isPrimary":false,"header":{"id":"hdr_campaign_01","type":"header","navItems":[{"id":"nav_home","text":"Home","linkType":"internal","pageSlug":"/"},{"id":"nav_about","text":"About Us","linkType":"internal","pageSlug":"/about"}],"ctaIds":["btn_order"],"key":"campaign"},"assets":{},"contentUpdatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"globals.create_header","x-kanorio-mcp-tool":"globals_create_header","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/globals/headers/{key}":{"delete":{"operationId":"globals_delete_header","summary":"globals.delete_header","description":"Delete a secondary header by key and automatically reassign any pages using it back to the primary header. The primary header cannot be deleted. Saved as draft only; call site.publish to go live. Errors: FORBIDDEN, WEBSITE_NOT_FOUND, HEADER_NOT_FOUND, PRIMARY_HEADER_PROTECTED, CONFLICT, WRITE_FROZEN.","tags":["globals"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Unique header key (a-z, 0-9, hyphen, underscore; 1-40 chars). 'primary' refers to the main site header.","schema":{"type":"string"}},{"name":"ifUnmodifiedSince","in":"query","required":true,"description":"contentUpdatedAt from globals.get. Required: the write is rejected with CONFLICT when the site-level draft changed since (details.contentUpdatedAt holds the current value).","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"contentUpdatedAt from globals.get. Required: the write is rejected with CONFLICT when the site-level draft changed since (details.contentUpdatedAt holds the current value)."},"example":"2026-10-06T08:00:00.000Z"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deletedKey":{"type":"string"},"reassignedPages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Revision marker of the site-level draft (Website.contentUpdatedAt). Pass it back as ifUnmodifiedSince."}},"required":["deletedKey","reassignedPages","contentUpdatedAt"],"additionalProperties":false},"example":{"deletedKey":"campaign","reassignedPages":1,"contentUpdatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"globals.delete_header","x-kanorio-mcp-tool":"globals_delete_header","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/globals/site-settings":{"patch":{"operationId":"globals_update_site_settings","summary":"globals.update_site_settings","description":"Partially update siteSettings (only the keys you send are replaced; optimistic concurrency). customButtons is the single list of CTA buttons for the whole site: define them here (text, url, optional icon and style), then reference their ids from sections, the header and the footer via ctaIds (up to 2 per place). Buttons without an id get one; read it back from the response. Replaces the whole list when sent. socialLinks: [{ platform, url }] rendered in the footer and social sections. Contact fields (address/phone/email/hours) are business facts and are not editable here. Saved as draft only; call site.publish to go live. Errors: FORBIDDEN, WEBSITE_NOT_FOUND, VALIDATION, CONFLICT, WRITE_FROZEN, ASSET_NOT_FOUND (details.assetIds: not in this site's media library), ASSET_NOT_ALLOWED (product files cannot be shown on pages).","tags":["globals"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ifUnmodifiedSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"contentUpdatedAt from globals.get. Required: the write is rejected with CONFLICT when the site-level draft changed since (details.contentUpdatedAt holds the current value)."},"siteSettings":{"type":"object","properties":{"socialLinks":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["website","facebook","instagram","line_oa","threads","tiktok","douyin","youtube","twitter","whatsapp","linkedin","xhs","pinterest","behance","bluesky","discord","messenger","dribbble","github","mastodon","medium","reddit","snapchat","substack","patreon","ko_fi","buymeacoffee","linktree","tumblr","quora","nextdoor","soundcloud","bandcamp","tidal","notion","figma","canva","signal","slack","zoom","bilibili","weibo","wechat","zhihu","douban","strava","letterboxd","goodreads","yelp","foursquare","tripadvisor","stackoverflow","shopify","skype","viber","wordpress","deezer","mixcloud","dailymotion","gitlab","bitbucket","trello","dropbox","codepen","artstation","audible","gojek","bukalapak","zalo","kakaotalk","naver","aliexpress","amazon","ebay","etsy","paypal","stripe","alipay","jkopay","line_pay","taiwan_pay","pxpay","ipass_money","grab","meituan","dianping","plurk","dcard","bahamut","shopee","rakuten","rakuten_tickets","taobao","pinkoi","carousell","momo","pchome","yahoo_shopping","yahoo_mall","ruten","coupang","books_com_tw","etmall","friday","spotify","vocus","telegram","twitch","vimeo","surveycake","apple_podcast","apple_music","firstory","kkbox","soundon","uber","uber_eats","foodpanda","keeta","deliveroo","nidin","ichef","dudoo","hahow","pressplay","udemy","google_maps","google_forms","google_reviews","typeform","openrice","inline","funnow","accupass","kktix","eztable","104_jobs","1111_jobs","518_jobs","yes123","yourator","meet_jobs","cake","calendly","booking_com","agoda","airbnb","asiayo","kkday","klook","house591","youbike","irent","hktvmall","payme","octopus","alipay_hk","jobsdb","lihkg","price_com_hk","cityline","joox","ctgoodjobs","discuss_com_hk","hse28","spacious","urbtix","jd_com","yesstyle","ztore","moov","flickr","meetup","kickstarter","product_hunt","lastfm","scribd","pocket","steam","vk","xing","orcid","researchgate"]},"url":{"type":"string","minLength":1,"format":"uri"}},"required":["platform","url"]}},"customButtons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"iconType":{"type":"string","enum":["icon","platform"]},"icon":{"enum":["briefcase","star","award","crown","flame","zap","target","rocket","flag","gem","diamond","scroll","fingerprint","smile","laugh","clock","phone","mail","bell","settings","check-circle","info","help-circle","headset","megaphone","newspaper","hourglass","stamp","milestone","quote","table","list-ordered","list-checks","arrow-right","message-circle","external-link","download","play","pause","bookmark","search","filter","thumbs-up","share-2","eye","phone-call","send","lock","rotate-ccw","clipboard-check","alarm-clock","utensils","utensils-crossed","chef-hat","coffee","pizza","soup","ice-cream-cone","sandwich","beef","fish","salad","cookie","cake","cake-slice","dessert","cup-soda","wine","beer","martini","milk","wheat","egg","croissant","popcorn","candy","apple","cherry","banana","citrus","grape","carrot","drumstick","cooking-pot","shrimp","donut","bean","vegan","store","shopping-bag","shopping-cart","shopping-basket","package","package-check","boxes","truck","motorbike","warehouse","tag","tags","ticket-percent","barcode","qr-code","scan-qr-code","credit-card","smartphone-nfc","wallet","banknote","coins","dollar-sign","percent","badge-percent","receipt","shirt","heart","heart-pulse","stethoscope","hospital","syringe","pill","pill-bottle","bandage","cross","thermometer","briefcase-medical","scissors","sparkles","scan-face","hand","bath","droplet","droplets","flower","flower-2","sun","moon","book-open","book-text","book-copy","book-marked","book-check","graduation-cap","school","library","monitor-play","backpack","pencil","pen-tool","file-text","scroll-text","notebook-pen","languages","calculator","presentation","lightbulb","brain","puzzle","laptop","monitor","smartphone","tablet","code","code-2","terminal","server","database","cloud","cpu","globe","network","circuit-board","brain-circuit","bot","blocks","palette","brush","paint-bucket","pen-line","image","image-plus","camera","video","film","clapperboard","music","music-2","music-4","mic","mic-2","headphones","speaker","radio","podcast","piano","plane","map-pin","map-pinned","navigation","route","compass","mountain","tree-pine","trees","tent","umbrella","anchor","ship","car","bike","bus","train","luggage","hotel","bed-double","concierge-bell","wifi","parking-square","air-vent","washing-machine","cigarette-off","accessibility","dumbbell","biceps-flexed","footprints","timer","watch","medal","trophy","swords","badge-check","activity","building","building-2","factory","house","house-plus","map-pin-house","door-open","door-closed","key","key-round","fence","sofa","ruler","hard-hat","hammer","wrench","paint-roller","brush-cleaning","cat","dog","bird","rabbit","squirrel","paw-print","bone","leaf","sprout","clover","tractor","cloud-sun","cloud-rain","snowflake","leafy-green","tree-deciduous","wind","waves","recycle","landmark","vault","scale","gavel","shield","shield-check","badge-dollar-sign","hand-coins","trending-up","trending-down","bar-chart","bar-chart-2","bar-chart-3","pie-chart","line-chart","chart-no-axes-combined","users","users-round","user-circle","user-plus","hand-heart","hand-helping","heart-handshake","handshake","baby","church","party-popper","sparkle","gift","ticket","calendar","calendar-days","calendar-check","calendar-clock"],"type":"string"},"platform":{"type":"string","enum":["website","facebook","instagram","line_oa","threads","tiktok","douyin","youtube","twitter","whatsapp","linkedin","xhs","pinterest","behance","bluesky","discord","messenger","dribbble","github","mastodon","medium","reddit","snapchat","substack","patreon","ko_fi","buymeacoffee","linktree","tumblr","quora","nextdoor","soundcloud","bandcamp","tidal","notion","figma","canva","signal","slack","zoom","bilibili","weibo","wechat","zhihu","douban","strava","letterboxd","goodreads","yelp","foursquare","tripadvisor","stackoverflow","shopify","skype","viber","wordpress","deezer","mixcloud","dailymotion","gitlab","bitbucket","trello","dropbox","codepen","artstation","audible","gojek","bukalapak","zalo","kakaotalk","naver","aliexpress","amazon","ebay","etsy","paypal","stripe","alipay","jkopay","line_pay","taiwan_pay","pxpay","ipass_money","grab","meituan","dianping","plurk","dcard","bahamut","shopee","rakuten","rakuten_tickets","taobao","pinkoi","carousell","momo","pchome","yahoo_shopping","yahoo_mall","ruten","coupang","books_com_tw","etmall","friday","spotify","vocus","telegram","twitch","vimeo","surveycake","apple_podcast","apple_music","firstory","kkbox","soundon","uber","uber_eats","foodpanda","keeta","deliveroo","nidin","ichef","dudoo","hahow","pressplay","udemy","google_maps","google_forms","google_reviews","typeform","openrice","inline","funnow","accupass","kktix","eztable","104_jobs","1111_jobs","518_jobs","yes123","yourator","meet_jobs","cake","calendly","booking_com","agoda","airbnb","asiayo","kkday","klook","house591","youbike","irent","hktvmall","payme","octopus","alipay_hk","jobsdb","lihkg","price_com_hk","cityline","joox","ctgoodjobs","discuss_com_hk","hse28","spacious","urbtix","jd_com","yesstyle","ztore","moov","flickr","meetup","kickstarter","product_hunt","lastfm","scribd","pocket","steam","vk","xing","orcid","researchgate"]},"text":{"type":"string","maxLength":250},"url":{"description":"Optional link: absolute http(s)/tel:/mailto: URL, site-relative path (/about) or anchor (#id).","type":"string"},"link":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"}},"required":["kind","pageId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-post"},"postId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","postId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-tag"},"tagId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","tagId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-author"},"authorId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","authorId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"product-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"external"},"url":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","url"]}]},"openInNewTab":{"type":"boolean"},"style":{"type":"string","enum":["brand","default","ghost"]},"iconPosition":{"type":"string","enum":["left","right"]}}}},"socialIconColor":{"type":"object","properties":{"light":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dark":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}}},"showBreadcrumbs":{"type":"boolean"}},"description":"Keys to replace: customButtons (max 2 are shown per section; the list itself can be longer), socialLinks, socialIconColor, showBreadcrumbs (boolean, defaults to true; controls site-wide breadcrumb navigation and BreadcrumbList JSON-LD)."}},"required":["ifUnmodifiedSince","siteSettings"]},"example":{"ifUnmodifiedSince":"2026-10-06T08:00:00.000Z","siteSettings":{"customButtons":[{"id":"btn_order","text":"Order online","url":"/shop","style":"brand"}]}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"siteSettings":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"siteSettings as stored; customButtons[].id are the ids to use in ctaIds."},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files referenced as asset:<assetId>, by assetId."},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Revision marker of the site-level draft (Website.contentUpdatedAt). Pass it back as ifUnmodifiedSince."}},"required":["siteSettings","assets","contentUpdatedAt"],"additionalProperties":false},"example":{"siteSettings":{"customButtons":[{"id":"btn_order","text":"Order online","url":"/shop","style":"brand"}],"socialLinks":[{"platform":"instagram","url":"https://www.instagram.com/sunnybakery.example"}]},"assets":{},"contentUpdatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"globals.update_site_settings","x-kanorio-mcp-tool":"globals_update_site_settings","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/globals/header":{"put":{"operationId":"globals_replace_header","summary":"globals.replace_header","description":"Replace the primary header or a secondary header identified by key (whole object, optimistic concurrency). The header's id stays the one pages already reference; when the site has no header yet, the given id is used and attached to every page. Typical use after creating pages: rebuild navItems so each visible page has an internal link. Saved as draft only; call site.publish to go live. Reference a logoOverride image as asset:<assetId>. Errors: FORBIDDEN, WEBSITE_NOT_FOUND, HEADER_NOT_FOUND, VALIDATION (details lists the failing field), CONFLICT, WRITE_FROZEN, ASSET_NOT_FOUND (details.assetIds: not in this site's media library), ASSET_NOT_ALLOWED (product files cannot be shown on pages).","tags":["globals"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ifUnmodifiedSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"contentUpdatedAt from globals.get. Required: the write is rejected with CONFLICT when the site-level draft changed since (details.contentUpdatedAt holds the current value)."},"key":{"description":"Header key to replace (default 'primary'; pass a secondary header key from globals.list_headers to replace that header).","type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"header":{"type":"object","properties":{"type":{"type":"string","const":"header"},"id":{"type":"string","minLength":1,"description":"Stable id; pages reference it via globalHeaderId."},"key":{"description":"Human-readable key for this header (e.g. 'primary', 'campaign', 'docs').","type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"cta":{"type":"object","properties":{"id":{"type":"string"},"icon":{"enum":["briefcase","star","award","crown","flame","zap","target","rocket","flag","gem","diamond","scroll","fingerprint","smile","laugh","clock","phone","mail","bell","settings","check-circle","info","help-circle","headset","megaphone","newspaper","hourglass","stamp","milestone","quote","table","list-ordered","list-checks","arrow-right","message-circle","external-link","download","play","pause","bookmark","search","filter","thumbs-up","share-2","eye","phone-call","send","lock","rotate-ccw","clipboard-check","alarm-clock","utensils","utensils-crossed","chef-hat","coffee","pizza","soup","ice-cream-cone","sandwich","beef","fish","salad","cookie","cake","cake-slice","dessert","cup-soda","wine","beer","martini","milk","wheat","egg","croissant","popcorn","candy","apple","cherry","banana","citrus","grape","carrot","drumstick","cooking-pot","shrimp","donut","bean","vegan","store","shopping-bag","shopping-cart","shopping-basket","package","package-check","boxes","truck","motorbike","warehouse","tag","tags","ticket-percent","barcode","qr-code","scan-qr-code","credit-card","smartphone-nfc","wallet","banknote","coins","dollar-sign","percent","badge-percent","receipt","shirt","heart","heart-pulse","stethoscope","hospital","syringe","pill","pill-bottle","bandage","cross","thermometer","briefcase-medical","scissors","sparkles","scan-face","hand","bath","droplet","droplets","flower","flower-2","sun","moon","book-open","book-text","book-copy","book-marked","book-check","graduation-cap","school","library","monitor-play","backpack","pencil","pen-tool","file-text","scroll-text","notebook-pen","languages","calculator","presentation","lightbulb","brain","puzzle","laptop","monitor","smartphone","tablet","code","code-2","terminal","server","database","cloud","cpu","globe","network","circuit-board","brain-circuit","bot","blocks","palette","brush","paint-bucket","pen-line","image","image-plus","camera","video","film","clapperboard","music","music-2","music-4","mic","mic-2","headphones","speaker","radio","podcast","piano","plane","map-pin","map-pinned","navigation","route","compass","mountain","tree-pine","trees","tent","umbrella","anchor","ship","car","bike","bus","train","luggage","hotel","bed-double","concierge-bell","wifi","parking-square","air-vent","washing-machine","cigarette-off","accessibility","dumbbell","biceps-flexed","footprints","timer","watch","medal","trophy","swords","badge-check","activity","building","building-2","factory","house","house-plus","map-pin-house","door-open","door-closed","key","key-round","fence","sofa","ruler","hard-hat","hammer","wrench","paint-roller","brush-cleaning","cat","dog","bird","rabbit","squirrel","paw-print","bone","leaf","sprout","clover","tractor","cloud-sun","cloud-rain","snowflake","leafy-green","tree-deciduous","wind","waves","recycle","landmark","vault","scale","gavel","shield","shield-check","badge-dollar-sign","hand-coins","trending-up","trending-down","bar-chart","bar-chart-2","bar-chart-3","pie-chart","line-chart","chart-no-axes-combined","users","users-round","user-circle","user-plus","hand-heart","hand-helping","heart-handshake","handshake","baby","church","party-popper","sparkle","gift","ticket","calendar","calendar-days","calendar-check","calendar-clock"],"type":"string"},"text":{"type":"string","maxLength":250},"url":{"description":"Optional link: absolute http(s)/tel:/mailto: URL, site-relative path (/about) or anchor (#id).","type":"string"},"style":{"type":"string","enum":["brand","default","ghost"]}}},"ctaId":{"description":"Legacy single button id from siteSettings.customButtons. Prefer ctaIds; when both are set ctaIds wins.","type":"string"},"ctaIds":{"description":"Up to 2 ids of buttons defined in siteSettings.customButtons, shown at the right of the header (and at the bottom of the side-left sidebar / mobile menu).","maxItems":3,"type":"array","items":{"type":"string"}},"ctaStyleById":{"description":"Per-button style override keyed by customButton id: brand (filled brand color), default (neutral), or ghost (text with arrow).","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","enum":["brand","default","ghost"]}},"layout":{"description":"Desktop header layout: top-spread (default), top-left (nav next to logo), top-center (centered nav), or side-left (fixed left sidebar).","type":"string","enum":["top-spread","top-left","top-center","side-left"]},"surface":{"description":"Header background tone: default (light bar with blur), muted, tint, brand or contrast; text colors adapt automatically. auto behaves like default.","type":"string","enum":["auto","default","muted","tint","brand","contrast"]},"showBrandLogo":{"description":"Show the brand logo (default true). When false and showSiteName is false, nothing is rendered in the brand slot.","type":"boolean"},"showSiteName":{"description":"Show the website name next to (or instead of) the logo (default false; the name is still shown when no logo exists).","type":"boolean"},"logoSize":{"description":"Logo size in the header (default md).","type":"string","enum":["sm","md","lg"]},"showSocialLinks":{"description":"Show siteSettings.socialLinks in the header, either for every device (boolean) or per device. Defaults: desktop only for the side-left layout, tablet and mobile menu on.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"desktop":{"type":"boolean"},"tablet":{"type":"boolean"},"mobile":{"type":"boolean"}}}]},"hiddenSocialLinkUrls":{"description":"Urls from siteSettings.socialLinks to hide in this section (blacklist; omitted or empty shows all).","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048}},"hiddenSocialLinkUrlsByDevice":{"description":"Per-device blacklist of social link urls; a device without its own list falls back to hiddenSocialLinkUrls.","type":"object","properties":{"desktop":{"description":"Urls from siteSettings.socialLinks to hide in this section (blacklist; omitted or empty shows all).","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048}},"tablet":{"description":"Urls from siteSettings.socialLinks to hide in this section (blacklist; omitted or empty shows all).","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048}},"mobile":{"description":"Urls from siteSettings.socialLinks to hide in this section (blacklist; omitted or empty shows all).","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048}}}},"variant":{"description":"Deprecated and ignored: the header background is controlled by surface. Accepted for backward compatibility.","type":"string","enum":["solid","transparent","glass"]},"shrinkOnScroll":{"description":"Compact the header after scrolling (default true).","type":"boolean"},"showProgressBar":{"type":"boolean"},"showAccentLine":{"description":"Show a thin brand-gradient line at the bottom edge (default false).","type":"boolean"},"isVisible":{"type":"boolean"},"navItems":{"description":"Navigation links. The header never lists pages automatically; add one internal item per visible page.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","minLength":1,"maxLength":250},"linkType":{"type":"string","enum":["internal","external","group"]},"pageSlug":{"type":"string"},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"},"externalUrl":{"description":"Optional link: absolute http(s)/tel:/mailto: URL, site-relative path (/about) or anchor (#id).","type":"string"},"openInNewTab":{"type":"boolean"},"children":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","minLength":1,"maxLength":250},"linkType":{"type":"string","enum":["internal","external"]},"pageSlug":{"type":"string"},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"},"externalUrl":{"description":"Optional link: absolute http(s)/tel:/mailto: URL, site-relative path (/about) or anchor (#id).","type":"string"},"openInNewTab":{"type":"boolean"},"link":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"}},"required":["kind","pageId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-post"},"postId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","postId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-tag"},"tagId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","tagId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-author"},"authorId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","authorId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"product-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"external"},"url":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","url"]}]}},"required":["id","text","linkType"]}},"link":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"}},"required":["kind","pageId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-post"},"postId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","postId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-tag"},"tagId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","tagId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-author"},"authorId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","authorId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"product-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"external"},"url":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","url"]}]}},"required":["id","text","linkType"]}},"utilities":{"description":"Header utility buttons (site features shown at the right of the header, after the CTA buttons), in display order; each id at most once. enabled shows or hides it; an omitted id keeps its default (search: off, cart: on; newly created sites default both to on). A utility only renders when the site has that feature: search needs a published site with searchable content; cart needs the shopping cart turned on in store settings and at least one active product. On phones only the first 2 visible utilities stay next to the menu button; the rest move to the top of the mobile menu.","maxItems":2,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["search","cart"],"description":"search: site search button; cart: shopping cart button."},"enabled":{"type":"boolean"}},"required":["id","enabled"]}},"isGlobal":{"type":"boolean"},"logoOverride":{"description":"Header-specific logo (e.g. a wide wordmark). Omit to use the website's brand logo.","allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["image","icon"]},"url":{"description":"Required when type is image.","type":"string","format":"uri"},"icon":{"description":"Required when type is icon; one of the curated logo icon names.","type":"string","enum":["briefcase","star","award","crown","flame","zap","target","rocket","flag","gem","diamond","scroll","fingerprint","smile","laugh","clock","phone","mail","bell","settings","check-circle","info","help-circle","headset","megaphone","newspaper","hourglass","stamp","milestone","utensils","utensils-crossed","chef-hat","coffee","pizza","soup","ice-cream-cone","sandwich","beef","fish","salad","cookie","cake","cake-slice","dessert","cup-soda","wine","beer","martini","milk","wheat","egg","croissant","popcorn","candy","apple","cherry","banana","citrus","grape","carrot","drumstick","cooking-pot","shrimp","donut","bean","vegan","store","shopping-bag","shopping-cart","shopping-basket","package","package-check","boxes","truck","motorbike","warehouse","tag","tags","ticket-percent","barcode","qr-code","scan-qr-code","credit-card","smartphone-nfc","wallet","banknote","coins","dollar-sign","percent","badge-percent","receipt","shirt","heart","heart-pulse","stethoscope","hospital","syringe","pill","pill-bottle","bandage","cross","thermometer","briefcase-medical","scissors","sparkles","scan-face","hand","bath","droplet","droplets","flower","flower-2","sun","moon","book-open","book-text","book-copy","book-marked","book-check","graduation-cap","school","library","monitor-play","backpack","pencil","pen-tool","file-text","scroll-text","notebook-pen","languages","calculator","presentation","lightbulb","brain","puzzle","laptop","monitor","smartphone","tablet","code","code-2","terminal","server","database","cloud","cpu","globe","network","circuit-board","brain-circuit","bot","blocks","palette","brush","paint-bucket","pen-line","image","image-plus","camera","video","film","clapperboard","music","music-2","music-4","mic","mic-2","headphones","speaker","radio","podcast","piano","plane","map-pin","map-pinned","navigation","route","compass","mountain","tree-pine","trees","tent","umbrella","anchor","ship","car","bike","bus","train","luggage","hotel","bed-double","concierge-bell","wifi","parking-square","air-vent","washing-machine","cigarette-off","accessibility","dumbbell","biceps-flexed","footprints","timer","watch","medal","trophy","swords","badge-check","activity","building","building-2","factory","house","house-plus","map-pin-house","door-open","door-closed","key","key-round","fence","sofa","ruler","hard-hat","hammer","wrench","paint-roller","brush-cleaning","cat","dog","bird","rabbit","squirrel","paw-print","bone","leaf","sprout","clover","tractor","cloud-sun","cloud-rain","snowflake","leafy-green","tree-deciduous","wind","waves","recycle","landmark","vault","scale","gavel","shield","shield-check","badge-dollar-sign","hand-coins","trending-up","trending-down","bar-chart","bar-chart-2","bar-chart-3","pie-chart","line-chart","chart-no-axes-combined","users","users-round","user-circle","user-plus","hand-heart","hand-helping","heart-handshake","handshake","baby","church","party-popper","sparkle","gift","ticket","calendar","calendar-days","calendar-check","calendar-clock"]}},"required":["type"]},{"type":"object","properties":{"dark":{"type":"object","properties":{"type":{"type":"string","enum":["image","icon"]},"url":{"description":"Required when type is image.","type":"string","format":"uri"},"icon":{"description":"Required when type is icon; one of the curated logo icon names.","type":"string","enum":["briefcase","star","award","crown","flame","zap","target","rocket","flag","gem","diamond","scroll","fingerprint","smile","laugh","clock","phone","mail","bell","settings","check-circle","info","help-circle","headset","megaphone","newspaper","hourglass","stamp","milestone","utensils","utensils-crossed","chef-hat","coffee","pizza","soup","ice-cream-cone","sandwich","beef","fish","salad","cookie","cake","cake-slice","dessert","cup-soda","wine","beer","martini","milk","wheat","egg","croissant","popcorn","candy","apple","cherry","banana","citrus","grape","carrot","drumstick","cooking-pot","shrimp","donut","bean","vegan","store","shopping-bag","shopping-cart","shopping-basket","package","package-check","boxes","truck","motorbike","warehouse","tag","tags","ticket-percent","barcode","qr-code","scan-qr-code","credit-card","smartphone-nfc","wallet","banknote","coins","dollar-sign","percent","badge-percent","receipt","shirt","heart","heart-pulse","stethoscope","hospital","syringe","pill","pill-bottle","bandage","cross","thermometer","briefcase-medical","scissors","sparkles","scan-face","hand","bath","droplet","droplets","flower","flower-2","sun","moon","book-open","book-text","book-copy","book-marked","book-check","graduation-cap","school","library","monitor-play","backpack","pencil","pen-tool","file-text","scroll-text","notebook-pen","languages","calculator","presentation","lightbulb","brain","puzzle","laptop","monitor","smartphone","tablet","code","code-2","terminal","server","database","cloud","cpu","globe","network","circuit-board","brain-circuit","bot","blocks","palette","brush","paint-bucket","pen-line","image","image-plus","camera","video","film","clapperboard","music","music-2","music-4","mic","mic-2","headphones","speaker","radio","podcast","piano","plane","map-pin","map-pinned","navigation","route","compass","mountain","tree-pine","trees","tent","umbrella","anchor","ship","car","bike","bus","train","luggage","hotel","bed-double","concierge-bell","wifi","parking-square","air-vent","washing-machine","cigarette-off","accessibility","dumbbell","biceps-flexed","footprints","timer","watch","medal","trophy","swords","badge-check","activity","building","building-2","factory","house","house-plus","map-pin-house","door-open","door-closed","key","key-round","fence","sofa","ruler","hard-hat","hammer","wrench","paint-roller","brush-cleaning","cat","dog","bird","rabbit","squirrel","paw-print","bone","leaf","sprout","clover","tractor","cloud-sun","cloud-rain","snowflake","leafy-green","tree-deciduous","wind","waves","recycle","landmark","vault","scale","gavel","shield","shield-check","badge-dollar-sign","hand-coins","trending-up","trending-down","bar-chart","bar-chart-2","bar-chart-3","pie-chart","line-chart","chart-no-axes-combined","users","users-round","user-circle","user-plus","hand-heart","hand-helping","heart-handshake","handshake","baby","church","party-popper","sparkle","gift","ticket","calendar","calendar-days","calendar-check","calendar-clock"]}},"required":["type"]}}}]}},"required":["type","id"],"description":"Complete header object. navItems is the navigation: one { id, text, linkType: \"internal\", pageSlug } per visible page (the header never lists pages automatically); use ctaIds (up to 2) to show buttons from siteSettings.customButtons. layout picks the desktop arrangement (top-spread, top-left, top-center, side-left), surface the background tone; showBrandLogo / showSiteName / logoSize control the brand slot and showSocialLinks (boolean or per device) plus hiddenSocialLinkUrls choose which social links appear; utilities orders and toggles the feature buttons (search, cart) after the CTA buttons. The logo comes from the website's brand settings unless logoOverride is set."}},"required":["ifUnmodifiedSince","header"]},"example":{"ifUnmodifiedSince":"2026-10-06T08:00:00.000Z","header":{"id":"sec_header01","type":"header","navItems":[{"id":"nav_home","text":"Home","linkType":"internal","pageSlug":"/"},{"id":"nav_about","text":"About Us","linkType":"internal","pageSlug":"/about"}],"ctaIds":["btn_order"]}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"header":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Header as stored (id may differ from the one sent when the site already had one)."},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files referenced as asset:<assetId>, by assetId."},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Revision marker of the site-level draft (Website.contentUpdatedAt). Pass it back as ifUnmodifiedSince."}},"required":["header","assets","contentUpdatedAt"],"additionalProperties":false},"example":{"header":{"id":"sec_header01","type":"header","navItems":[{"id":"nav_home","text":"Home","linkType":"internal","pageSlug":"/"},{"id":"nav_about","text":"About Us","linkType":"internal","pageSlug":"/about"}],"ctaIds":["btn_order"]},"assets":{},"contentUpdatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"globals.replace_header","x-kanorio-mcp-tool":"globals_replace_header","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/globals/footer":{"put":{"operationId":"globals_replace_footer","summary":"globals.replace_footer","description":"Replace the primary footer (whole object, optimistic concurrency). The footer's id stays the one pages already reference; when the site has no footer yet, the given id is used and attached to every page. Saved as draft only; call site.publish to go live. Errors: FORBIDDEN, WEBSITE_NOT_FOUND, VALIDATION, CONFLICT, WRITE_FROZEN, ASSET_NOT_FOUND (details.assetIds: not in this site's media library), ASSET_NOT_ALLOWED (product files cannot be shown on pages).","tags":["globals"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ifUnmodifiedSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"contentUpdatedAt from globals.get. Required: the write is rejected with CONFLICT when the site-level draft changed since (details.contentUpdatedAt holds the current value)."},"footer":{"type":"object","properties":{"type":{"type":"string","const":"footer"},"isVisible":{"type":"boolean"},"layout":{"description":"Footer layout preset.","type":"string","enum":["columns","centered","minimal"]},"surface":{"description":"Footer background tone: muted (default), default, tint, brand or contrast; text and icon colors adapt automatically.","type":"string","enum":["auto","default","muted","tint","brand","contrast"]},"logoSize":{"description":"Logo size in the footer (default md).","type":"string","enum":["sm","md","lg"]},"logoFramed":{"description":"Wrap the logo in a white rounded frame (default false: logo rendered as is).","type":"boolean"},"showBrandLogo":{"type":"boolean"},"showSocialLinks":{"type":"boolean"},"hiddenSocialLinkUrls":{"description":"Urls from siteSettings.socialLinks to hide in this section (blacklist; omitted or empty shows all).","maxItems":50,"type":"array","items":{"type":"string","maxLength":2048}},"ctaIds":{"description":"Up to 2 ids of buttons defined in siteSettings.customButtons, shown under the brand description.","maxItems":3,"type":"array","items":{"type":"string"}},"ctaStyleById":{"description":"Per-button style override keyed by customButton id: brand (filled brand color), default (neutral), or ghost (text with arrow).","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","enum":["brand","default","ghost"]}},"showAccentLine":{"description":"Show a thin brand-gradient line at the top edge (default false).","type":"boolean"},"copyright":{"type":"string","maxLength":250},"description":{"description":"Body text (optional). Up to 3000 visible characters.","type":"string"},"descriptionCollapsible":{"description":"Clamp long text: null shows everything, a number clamps to that many lines, \"scroll\" keeps a fixed height with scrolling.","anyOf":[{"anyOf":[{"type":"number","enum":[3,5,10,15]},{"type":"string","const":"scroll"}]},{"type":"null"}]},"showSiteName":{"type":"boolean"},"navItems":{"description":"Footer links. An item with linkType group becomes its own column titled with the item text; its children are the links of that column.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","minLength":1,"maxLength":250},"linkType":{"type":"string","enum":["internal","external","group"]},"pageSlug":{"type":"string"},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"},"externalUrl":{"description":"Optional link: absolute http(s)/tel:/mailto: URL, site-relative path (/about) or anchor (#id).","type":"string"},"openInNewTab":{"type":"boolean"},"children":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","minLength":1,"maxLength":250},"linkType":{"type":"string","enum":["internal","external"]},"pageSlug":{"type":"string"},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"},"externalUrl":{"description":"Optional link: absolute http(s)/tel:/mailto: URL, site-relative path (/about) or anchor (#id).","type":"string"},"openInNewTab":{"type":"boolean"},"link":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"}},"required":["kind","pageId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-post"},"postId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","postId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-tag"},"tagId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","tagId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-author"},"authorId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","authorId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"product-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"external"},"url":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","url"]}]}},"required":["id","text","linkType"]}},"link":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."},"anchorId":{"type":"string","pattern":"^[a-z0-9-]*$"}},"required":["kind","pageId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-post"},"postId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","postId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-tag"},"tagId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","tagId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"blog-author"},"authorId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","authorId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"product-category"},"categoryId":{"type":"string","minLength":1},"href":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","categoryId","href"]},{"type":"object","properties":{"kind":{"type":"string","const":"external"},"url":{"type":"string","minLength":1,"description":"Required link: absolute http(s)/tel:/mailto: URL, site-relative path or anchor."}},"required":["kind","url"]}]}},"required":["id","text","linkType"]}},"enabledTerms":{"description":"Legal links to render at the bottom; each refers to one of the hidden legal pages created with the site.","type":"array","items":{"type":"string","enum":["cookie-settings","cookie-policy","privacy-policy","terms-of-service","purchase-terms","return-policy","disclaimer"]}},"id":{"type":"string","minLength":1,"description":"Stable id; pages reference it via globalFooterId."},"isGlobal":{"type":"boolean"},"showAddress":{"type":"boolean"},"showPhone":{"type":"boolean"},"showEmail":{"type":"boolean"},"showBusinessHours":{"type":"boolean"},"navItemsTitle":{"type":"string","maxLength":250},"contactInfoTitle":{"type":"string","maxLength":250}},"required":["type","id"],"description":"Complete footer object: copyright, optional description, navItems (a group item renders as its own column), showBrandLogo / showSiteName / showSocialLinks / hiddenSocialLinkUrls, layout and surface, optional ctaIds (up to 2), and enabledTerms to link the legal pages."}},"required":["ifUnmodifiedSince","footer"]},"example":{"ifUnmodifiedSince":"2026-10-06T08:00:00.000Z","footer":{"id":"sec_footer01","type":"footer","copyright":"© 2026 Sunny Bakery"}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"footer":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files referenced as asset:<assetId>, by assetId."},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Revision marker of the site-level draft (Website.contentUpdatedAt). Pass it back as ifUnmodifiedSince."}},"required":["footer","assets","contentUpdatedAt"],"additionalProperties":false},"example":{"footer":{"id":"sec_footer01","type":"footer","copyright":"© 2026 Sunny Bakery"},"assets":{},"contentUpdatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"globals.replace_footer","x-kanorio-mcp-tool":"globals_replace_footer","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/pages":{"get":{"operationId":"pages_list","summary":"pages.list","description":"List the pages of a website (home page first), with slug, visibility, SEO fields and the revision marker updatedAt. Sections are not included; use pages.get. Errors: FORBIDDEN.","tags":["pages"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","description":"URL path, \"/\" for the home page."},"path":{"type":"array","items":{"type":"string"},"description":"Path segments (e.g. [\"services\", \"haircut\"] for \"/services/haircut\"; [] for \"/\")."},"parentSlug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Immediate parent page slug (e.g. \"/services\" for \"/services/haircut\"; null for \"/\" and top-level pages)."},"isDirectory":{"type":"boolean","description":"True when this is a hidden folder page that exists to group subpage URLs."},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hierarchy depth: 0 for home page, 1 for top-level pages, up to 3."},"ancestors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"}},"required":["id","slug","title"],"additionalProperties":false},"description":"Visible ancestor pages from root to immediate parent (hidden intermediate folder pages are omitted)."},"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"description":"Visible breadcrumb trail shown on the page and in BreadcrumbList JSON-LD (up to 4 items; empty when the page has no visible ancestors)."},"breadcrumbSource":{"type":"string","enum":["url","custom"],"description":"Whether breadcrumbs follow the URL hierarchy (\"url\") or a custom breadcrumbParentSlug override (\"custom\")."},"breadcrumbParentSlug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional parent page slug override for breadcrumbs and structured data only."},"title":{"type":"string"},"pageType":{"type":"string"},"isHomePage":{"type":"boolean"},"isVisible":{"type":"boolean","description":"Hidden pages are not published or linked from navigation."},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"globalHeaderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"globalFooterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string","description":"Revision marker. Pass it back as ifUnmodifiedSince when replacing sections."},"seo":{"type":"object","properties":{"seoTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoKeywords":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ogTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Share image display URL (changes with versions; do not store it)."},"ogImageAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId of the share image when it is in the media library."},"canonicalUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsIndex":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsFollow":{"anyOf":[{"type":"string"},{"type":"null"}]},"excludeFromSiteSearch":{"type":"boolean","description":"When true, this page is excluded from visitor site search (independent of robotsIndex)."}},"required":["seoTitle","seoDescription","seoKeywords","ogTitle","ogDescription","ogImage","ogImageAssetId","canonicalUrl","robotsIndex","robotsFollow","excludeFromSiteSearch"],"additionalProperties":false}},"required":["id","slug","path","parentSlug","isDirectory","depth","ancestors","breadcrumbs","breadcrumbSource","breadcrumbParentSlug","title","pageType","isHomePage","isVisible","order","globalHeaderId","globalFooterId","updatedAt","seo"],"additionalProperties":false}}},"required":["pages"],"additionalProperties":false},"example":{"pages":[{"id":"pg_example456","slug":"/","path":[],"parentSlug":null,"isDirectory":false,"depth":0,"ancestors":[],"breadcrumbs":[],"breadcrumbSource":"url","breadcrumbParentSlug":null,"title":"Home","pageType":"generic","isHomePage":true,"isVisible":true,"order":0,"globalHeaderId":"sec_header01","globalFooterId":"sec_footer01","updatedAt":"2026-10-06T08:00:00.000Z","seo":{"seoTitle":"Sunny Bakery","seoDescription":"Artisan sourdough bakery in Taipei.","seoKeywords":["sourdough","artisan bakery"],"ogTitle":null,"ogDescription":null,"ogImage":null,"ogImageAssetId":null,"canonicalUrl":null,"robotsIndex":null,"robotsFollow":null,"excludeFromSiteSearch":false}},{"id":"pg_example789","slug":"/about","path":["about"],"parentSlug":null,"isDirectory":false,"depth":1,"ancestors":[],"breadcrumbs":[],"breadcrumbSource":"url","breadcrumbParentSlug":null,"title":"About Us","pageType":"generic","isHomePage":false,"isVisible":true,"order":1,"globalHeaderId":"sec_header01","globalFooterId":"sec_footer01","updatedAt":"2026-10-06T08:00:00.000Z","seo":{"seoTitle":"About Us | Sunny Bakery","seoDescription":"Naturally leavened sourdough baked fresh every morning.","seoKeywords":["sourdough","artisan bakery"],"ogTitle":null,"ogDescription":null,"ogImage":null,"ogImageAssetId":null,"canonicalUrl":null,"robotsIndex":null,"robotsFollow":null,"excludeFromSiteSearch":false}}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"pages.list","x-kanorio-mcp-tool":"pages_list","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"pages_create","summary":"pages.create","description":"Create an empty page (up to 3 levels deep). Pass parentSlug (e.g. \"/services\") plus the last segment in slug (e.g. \"/haircut\") rather than concatenating multi-segment paths yourself; if the parent page does not exist yet, a hidden folder page is created automatically. Omit slug to have one generated from the title. The home page (\"/\") already exists and cannot be created; link-in-bio pages have a dedicated flow. The new page uses the home page's header and footer unless you pass globalHeaderId/globalFooterId. It is not added to the navigation automatically: after creating pages, call globals.replace_header with a navItem per visible page. Fill the page afterwards with pages.replace_sections. Errors: FORBIDDEN, VALIDATION, SLUG_TAKEN, RESERVED_SLUG, RESERVED_SEGMENT, SEGMENT_TOO_LONG, DEPTH_EXCEEDED, PARENT_NOT_ALLOWED, BREADCRUMB_PARENT_INVALID, HOME_NOT_CREATABLE, LINK_IN_BIO_DEDICATED_ENTRY.","tags":["pages"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120,"description":"Page title; also used for navigation labels."},"slug":{"description":"Last URL segment starting with \"/\" (e.g. \"/haircut\" when parentSlug is \"/services\"), or full path (e.g. \"/about\"). Generated from title when omitted.","type":"string","minLength":1,"maxLength":160},"parentSlug":{"description":"Optional parent page slug (e.g. \"/services\"). Pass parentSlug + last segment instead of concatenating \"/a/b\" yourself.","anyOf":[{"type":"string","minLength":1,"maxLength":160},{"type":"null"}]},"breadcrumbParentSlug":{"description":"Optional parent page slug override for breadcrumbs and BreadcrumbList JSON-LD only (use only when the typical user trail differs from the URL path; does not change the URL).","anyOf":[{"type":"string","minLength":1,"maxLength":160},{"type":"null"}]},"pageType":{"description":"Defaults to generic.","type":"string","enum":["generic","article","product","shop-index","blog-index","blog-category-archive","blog-tag-archive","blog-author-archive","product-category-archive","legal-cookie-policy","legal-privacy-policy","legal-terms-of-service","legal-purchase-terms","legal-return-policy","legal-disclaimer","link-in-bio"]},"isVisible":{"description":"Defaults to true. Hidden pages are not published.","type":"boolean"},"globalHeaderId":{"description":"Header from globalSections. Defaults to the home page's header; pass null for a page without a header.","anyOf":[{"type":"string"},{"type":"null"}]},"globalFooterId":{"description":"Footer from globalSections. Defaults to the home page's footer; pass null for a page without a footer.","anyOf":[{"type":"string"},{"type":"null"}]},"seoTitle":{"type":"string","maxLength":70},"seoDescription":{"type":"string","maxLength":200}},"required":["title"]},"example":{"title":"About Us","slug":"/about","isVisible":true}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","description":"URL path, \"/\" for the home page."},"path":{"type":"array","items":{"type":"string"},"description":"Path segments (e.g. [\"services\", \"haircut\"] for \"/services/haircut\"; [] for \"/\")."},"parentSlug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Immediate parent page slug (e.g. \"/services\" for \"/services/haircut\"; null for \"/\" and top-level pages)."},"isDirectory":{"type":"boolean","description":"True when this is a hidden folder page that exists to group subpage URLs."},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hierarchy depth: 0 for home page, 1 for top-level pages, up to 3."},"ancestors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"}},"required":["id","slug","title"],"additionalProperties":false},"description":"Visible ancestor pages from root to immediate parent (hidden intermediate folder pages are omitted)."},"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"description":"Visible breadcrumb trail shown on the page and in BreadcrumbList JSON-LD (up to 4 items; empty when the page has no visible ancestors)."},"breadcrumbSource":{"type":"string","enum":["url","custom"],"description":"Whether breadcrumbs follow the URL hierarchy (\"url\") or a custom breadcrumbParentSlug override (\"custom\")."},"breadcrumbParentSlug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional parent page slug override for breadcrumbs and structured data only."},"title":{"type":"string"},"pageType":{"type":"string"},"isHomePage":{"type":"boolean"},"isVisible":{"type":"boolean","description":"Hidden pages are not published or linked from navigation."},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"globalHeaderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"globalFooterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string","description":"Revision marker. Pass it back as ifUnmodifiedSince when replacing sections."},"seo":{"type":"object","properties":{"seoTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoKeywords":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ogTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Share image display URL (changes with versions; do not store it)."},"ogImageAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId of the share image when it is in the media library."},"canonicalUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsIndex":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsFollow":{"anyOf":[{"type":"string"},{"type":"null"}]},"excludeFromSiteSearch":{"type":"boolean","description":"When true, this page is excluded from visitor site search (independent of robotsIndex)."}},"required":["seoTitle","seoDescription","seoKeywords","ogTitle","ogDescription","ogImage","ogImageAssetId","canonicalUrl","robotsIndex","robotsFollow","excludeFromSiteSearch"],"additionalProperties":false},"warnings":{"description":"Non-fatal warnings from this write (e.g. REDIRECT_SHADOWS_PAGE when a manual redirect intercepts this URL).","type":"array","items":{"type":"string"}}},"required":["id","slug","path","parentSlug","isDirectory","depth","ancestors","breadcrumbs","breadcrumbSource","breadcrumbParentSlug","title","pageType","isHomePage","isVisible","order","globalHeaderId","globalFooterId","updatedAt","seo"],"additionalProperties":false},"example":{"id":"pg_example789","slug":"/about","path":["about"],"parentSlug":null,"isDirectory":false,"depth":1,"ancestors":[],"breadcrumbs":[],"breadcrumbSource":"url","breadcrumbParentSlug":null,"title":"About Us","pageType":"generic","isHomePage":false,"isVisible":true,"order":1,"globalHeaderId":"sec_header01","globalFooterId":"sec_footer01","updatedAt":"2026-10-06T08:00:00.000Z","seo":{"seoTitle":"About Us | Sunny Bakery","seoDescription":"Naturally leavened sourdough baked fresh every morning.","seoKeywords":["sourdough","artisan bakery"],"ogTitle":null,"ogDescription":null,"ogImage":null,"ogImageAssetId":null,"canonicalUrl":null,"robotsIndex":null,"robotsFollow":null,"excludeFromSiteSearch":false}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"pages.create","x-kanorio-mcp-tool":"pages_create","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/pages/order":{"put":{"operationId":"pages_reorder","summary":"pages.reorder","description":"Set the order of all non-home pages (the home page is always first). Order drives the page list in the console; navigation links come from the header's navItems, which you manage with globals.replace_header. pageIds must list every non-home page exactly once; legal pages created with the site count too (get them from pages.list). Errors: FORBIDDEN, FOREIGN_PAGE (an id is not a page of this site), HOME_NOT_SORTABLE (home page included), INCOMPLETE_ORDER (some pages missing or duplicated).","tags":["pages"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pageIds":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"string","minLength":1,"description":"Page id. Get it from pages.list."},"description":"All non-home page ids in the desired order."}},"required":["pageIds"]},"example":{"pageIds":["pg_example789"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","description":"URL path, \"/\" for the home page."},"path":{"type":"array","items":{"type":"string"},"description":"Path segments (e.g. [\"services\", \"haircut\"] for \"/services/haircut\"; [] for \"/\")."},"parentSlug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Immediate parent page slug (e.g. \"/services\" for \"/services/haircut\"; null for \"/\" and top-level pages)."},"isDirectory":{"type":"boolean","description":"True when this is a hidden folder page that exists to group subpage URLs."},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hierarchy depth: 0 for home page, 1 for top-level pages, up to 3."},"ancestors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"}},"required":["id","slug","title"],"additionalProperties":false},"description":"Visible ancestor pages from root to immediate parent (hidden intermediate folder pages are omitted)."},"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"description":"Visible breadcrumb trail shown on the page and in BreadcrumbList JSON-LD (up to 4 items; empty when the page has no visible ancestors)."},"breadcrumbSource":{"type":"string","enum":["url","custom"],"description":"Whether breadcrumbs follow the URL hierarchy (\"url\") or a custom breadcrumbParentSlug override (\"custom\")."},"breadcrumbParentSlug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional parent page slug override for breadcrumbs and structured data only."},"title":{"type":"string"},"pageType":{"type":"string"},"isHomePage":{"type":"boolean"},"isVisible":{"type":"boolean","description":"Hidden pages are not published or linked from navigation."},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"globalHeaderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"globalFooterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string","description":"Revision marker. Pass it back as ifUnmodifiedSince when replacing sections."},"seo":{"type":"object","properties":{"seoTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoKeywords":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ogTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Share image display URL (changes with versions; do not store it)."},"ogImageAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId of the share image when it is in the media library."},"canonicalUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsIndex":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsFollow":{"anyOf":[{"type":"string"},{"type":"null"}]},"excludeFromSiteSearch":{"type":"boolean","description":"When true, this page is excluded from visitor site search (independent of robotsIndex)."}},"required":["seoTitle","seoDescription","seoKeywords","ogTitle","ogDescription","ogImage","ogImageAssetId","canonicalUrl","robotsIndex","robotsFollow","excludeFromSiteSearch"],"additionalProperties":false}},"required":["id","slug","path","parentSlug","isDirectory","depth","ancestors","breadcrumbs","breadcrumbSource","breadcrumbParentSlug","title","pageType","isHomePage","isVisible","order","globalHeaderId","globalFooterId","updatedAt","seo"],"additionalProperties":false}}},"required":["pages"],"additionalProperties":false},"example":{"pages":[{"id":"pg_example456","slug":"/","path":[],"parentSlug":null,"isDirectory":false,"depth":0,"ancestors":[],"breadcrumbs":[],"breadcrumbSource":"url","breadcrumbParentSlug":null,"title":"Home","pageType":"generic","isHomePage":true,"isVisible":true,"order":0,"globalHeaderId":"sec_header01","globalFooterId":"sec_footer01","updatedAt":"2026-10-06T08:00:00.000Z","seo":{"seoTitle":"Sunny Bakery","seoDescription":"Artisan sourdough bakery in Taipei.","seoKeywords":["sourdough","artisan bakery"],"ogTitle":null,"ogDescription":null,"ogImage":null,"ogImageAssetId":null,"canonicalUrl":null,"robotsIndex":null,"robotsFollow":null,"excludeFromSiteSearch":false}},{"id":"pg_example789","slug":"/about","path":["about"],"parentSlug":null,"isDirectory":false,"depth":1,"ancestors":[],"breadcrumbs":[],"breadcrumbSource":"url","breadcrumbParentSlug":null,"title":"About Us","pageType":"generic","isHomePage":false,"isVisible":true,"order":1,"globalHeaderId":"sec_header01","globalFooterId":"sec_footer01","updatedAt":"2026-10-06T08:00:00.000Z","seo":{"seoTitle":"About Us | Sunny Bakery","seoDescription":"Naturally leavened sourdough baked fresh every morning.","seoKeywords":["sourdough","artisan bakery"],"ogTitle":null,"ogDescription":null,"ogImage":null,"ogImageAssetId":null,"canonicalUrl":null,"robotsIndex":null,"robotsFollow":null,"excludeFromSiteSearch":false}}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"pages.reorder","x-kanorio-mcp-tool":"pages_reorder","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/pages/{pageId}":{"get":{"operationId":"pages_get","summary":"pages.get","description":"Get one page including its current draft sections, hierarchy metadata (path, parentSlug, isDirectory, depth, ancestors, breadcrumbs, breadcrumbSource) and updatedAt. Always read the page right before pages.replace_sections and pass updatedAt back as ifUnmodifiedSince. Images and files of the site's media library appear as asset:<assetId> in sections; assets holds them (with display URLs). Errors: FORBIDDEN, PAGE_NOT_FOUND.","tags":["pages"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"pageId","in":"path","required":true,"description":"Page id. Get it from pages.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","description":"URL path, \"/\" for the home page."},"path":{"type":"array","items":{"type":"string"},"description":"Path segments (e.g. [\"services\", \"haircut\"] for \"/services/haircut\"; [] for \"/\")."},"parentSlug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Immediate parent page slug (e.g. \"/services\" for \"/services/haircut\"; null for \"/\" and top-level pages)."},"isDirectory":{"type":"boolean","description":"True when this is a hidden folder page that exists to group subpage URLs."},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hierarchy depth: 0 for home page, 1 for top-level pages, up to 3."},"ancestors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"}},"required":["id","slug","title"],"additionalProperties":false},"description":"Visible ancestor pages from root to immediate parent (hidden intermediate folder pages are omitted)."},"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"description":"Visible breadcrumb trail shown on the page and in BreadcrumbList JSON-LD (up to 4 items; empty when the page has no visible ancestors)."},"breadcrumbSource":{"type":"string","enum":["url","custom"],"description":"Whether breadcrumbs follow the URL hierarchy (\"url\") or a custom breadcrumbParentSlug override (\"custom\")."},"breadcrumbParentSlug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional parent page slug override for breadcrumbs and structured data only."},"title":{"type":"string"},"pageType":{"type":"string"},"isHomePage":{"type":"boolean"},"isVisible":{"type":"boolean","description":"Hidden pages are not published or linked from navigation."},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"globalHeaderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"globalFooterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string","description":"Revision marker. Pass it back as ifUnmodifiedSince when replacing sections."},"seo":{"type":"object","properties":{"seoTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoKeywords":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ogTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Share image display URL (changes with versions; do not store it)."},"ogImageAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId of the share image when it is in the media library."},"canonicalUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsIndex":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsFollow":{"anyOf":[{"type":"string"},{"type":"null"}]},"excludeFromSiteSearch":{"type":"boolean","description":"When true, this page is excluded from visitor site search (independent of robotsIndex)."}},"required":["seoTitle","seoDescription","seoKeywords","ogTitle","ogDescription","ogImage","ogImageAssetId","canonicalUrl","robotsIndex","robotsFollow","excludeFromSiteSearch"],"additionalProperties":false},"sections":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Current draft sections (what the editor shows), not the published copy. Media-library files appear as asset:<assetId>."},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files the sections use, by assetId."}},"required":["id","slug","path","parentSlug","isDirectory","depth","ancestors","breadcrumbs","breadcrumbSource","breadcrumbParentSlug","title","pageType","isHomePage","isVisible","order","globalHeaderId","globalFooterId","updatedAt","seo","sections","assets"],"additionalProperties":false},"example":{"id":"pg_example456","slug":"/","path":[],"parentSlug":null,"isDirectory":false,"depth":0,"ancestors":[],"breadcrumbs":[],"breadcrumbSource":"url","breadcrumbParentSlug":null,"title":"Home","pageType":"generic","isHomePage":true,"isVisible":true,"order":0,"globalHeaderId":"sec_header01","globalFooterId":"sec_footer01","updatedAt":"2026-10-06T08:00:00.000Z","seo":{"seoTitle":"Sunny Bakery","seoDescription":"Artisan sourdough bakery in Taipei.","seoKeywords":["sourdough","artisan bakery"],"ogTitle":null,"ogDescription":null,"ogImage":null,"ogImageAssetId":null,"canonicalUrl":null,"robotsIndex":null,"robotsFollow":null,"excludeFromSiteSearch":false},"sections":[{"id":"sec_hero01","type":"hero","title":"Freshly baked sourdough every morning","subtitle":"Natural starter, local grain. Doors open at 7 a.m.","image":"asset:asset_example01","ctaIds":["btn_order"]},{"id":"sec_faq01","type":"faq","title":"Frequently Asked Questions","items":[{"question":"Can I pre-order loaves?","answer":"Yes, place pre-orders by 5 p.m. the day before."}]}],"assets":{"asset_example01":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"sunny-bakery-hero.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":true,"createdAt":"2026-10-01T02:30:00.000Z"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"pages.get","x-kanorio-mcp-tool":"pages_get","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"patch":{"operationId":"pages_update","summary":"pages.update","description":"Update a page's properties: title, slug, parentSlug, createRedirect, breadcrumbParentSlug, visibility, header/footer reference, SEO fields (seoTitle, seoDescription, seoKeywords, og*, canonicalUrl, robots*) and excludeFromSiteSearch. Only the fields you send change; sections are untouched (use pages.replace_sections). Nullable fields (parentSlug, breadcrumbParentSlug, globalHeaderId, globalFooterId, ogImageAssetId) can be cleared by passing null; all other fields can only be replaced, not cleared. Slug, parentSlug and visibility changes take effect on the published site immediately; renaming automatically updates descendant subpages and creates 301 redirects for previously published pages unless createRedirect is false. Errors: FORBIDDEN, PAGE_NOT_FOUND, PARENT_NOT_FOUND, PARENT_NOT_ALLOWED, DEPTH_EXCEEDED, SEGMENT_TOO_LONG, RESERVED_SLUG, RESERVED_SEGMENT, BREADCRUMB_PARENT_INVALID, REDIRECT_CONFLICT, REDIRECT_LIMIT, VALIDATION, SLUG_TAKEN, HOME_SLUG_IMMUTABLE, HOME_NOT_HIDEABLE, PRODUCT_PAGES_PLAN_REQUIRED, ASSET_NOT_FOUND, ASSET_NOT_ALLOWED.","tags":["pages"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"pageId","in":"path","required":true,"description":"Page id. Get it from pages.list.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"Page title; also the default navigation label.","type":"string","minLength":1,"maxLength":120},"slug":{"description":"New URL path (or last segment when parentSlug is provided), e.g. \"/about\". Renaming a page also renames all its descendant subpages and creates 301 redirects for previously published pages. The home page slug cannot change.","type":"string","minLength":1,"maxLength":160},"parentSlug":{"description":"Move this page (and its subpages) under a new parent page slug (e.g. \"/services\"), or pass null to move it to the top level. Pass parentSlug + last segment rather than concatenating \"/a/b\" yourself.","anyOf":[{"type":"string","minLength":1,"maxLength":160},{"type":"null"}]},"createRedirect":{"description":"Whether to create 301 permanent redirects for previously published pages when renaming or moving (defaults to true).","type":"boolean"},"breadcrumbParentSlug":{"description":"Override the parent page shown in breadcrumbs and BreadcrumbList JSON-LD (pass null to reset to URL hierarchy). Use only when the page's logical category differs from its URL; does not change the URL or create redirects. Renaming or deleting the target page updates or clears this override automatically.","anyOf":[{"type":"string","minLength":1,"maxLength":160},{"type":"null"}]},"isVisible":{"description":"Hidden pages are not published. The home page cannot be hidden.","type":"boolean"},"globalHeaderId":{"description":"Header from globalSections to show on this page; null removes it.","anyOf":[{"type":"string"},{"type":"null"}]},"globalFooterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoTitle":{"type":"string","minLength":1,"maxLength":70},"seoDescription":{"type":"string","minLength":1,"maxLength":200},"seoKeywords":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":30}},"ogTitle":{"type":"string","minLength":1,"maxLength":70},"ogDescription":{"type":"string","minLength":1,"maxLength":200},"ogImageAssetId":{"description":"Share image: assetId of an image in the media library (media.list, media.upload). null removes it; without a share image a title card is generated automatically.","anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]},"canonicalUrl":{"type":"string","format":"uri"},"robotsIndex":{"type":"string","enum":["index","noindex"]},"robotsFollow":{"type":"string","enum":["follow","nofollow"]},"excludeFromSiteSearch":{"description":"Exclude this page from visitor site search (/api/v1/search and the /search page); does not affect search engine indexing (robotsIndex).","type":"boolean"}}},"example":{"seoTitle":"About Us | Sunny Bakery","seoDescription":"Naturally leavened sourdough baked fresh every morning.","ogImageAssetId":"asset_example01"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","description":"URL path, \"/\" for the home page."},"path":{"type":"array","items":{"type":"string"},"description":"Path segments (e.g. [\"services\", \"haircut\"] for \"/services/haircut\"; [] for \"/\")."},"parentSlug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Immediate parent page slug (e.g. \"/services\" for \"/services/haircut\"; null for \"/\" and top-level pages)."},"isDirectory":{"type":"boolean","description":"True when this is a hidden folder page that exists to group subpage URLs."},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hierarchy depth: 0 for home page, 1 for top-level pages, up to 3."},"ancestors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"}},"required":["id","slug","title"],"additionalProperties":false},"description":"Visible ancestor pages from root to immediate parent (hidden intermediate folder pages are omitted)."},"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"description":"Visible breadcrumb trail shown on the page and in BreadcrumbList JSON-LD (up to 4 items; empty when the page has no visible ancestors)."},"breadcrumbSource":{"type":"string","enum":["url","custom"],"description":"Whether breadcrumbs follow the URL hierarchy (\"url\") or a custom breadcrumbParentSlug override (\"custom\")."},"breadcrumbParentSlug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional parent page slug override for breadcrumbs and structured data only."},"title":{"type":"string"},"pageType":{"type":"string"},"isHomePage":{"type":"boolean"},"isVisible":{"type":"boolean","description":"Hidden pages are not published or linked from navigation."},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"globalHeaderId":{"anyOf":[{"type":"string"},{"type":"null"}]},"globalFooterId":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string","description":"Revision marker. Pass it back as ifUnmodifiedSince when replacing sections."},"seo":{"type":"object","properties":{"seoTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoKeywords":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ogTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Share image display URL (changes with versions; do not store it)."},"ogImageAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId of the share image when it is in the media library."},"canonicalUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsIndex":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsFollow":{"anyOf":[{"type":"string"},{"type":"null"}]},"excludeFromSiteSearch":{"type":"boolean","description":"When true, this page is excluded from visitor site search (independent of robotsIndex)."}},"required":["seoTitle","seoDescription","seoKeywords","ogTitle","ogDescription","ogImage","ogImageAssetId","canonicalUrl","robotsIndex","robotsFollow","excludeFromSiteSearch"],"additionalProperties":false},"warnings":{"description":"Non-fatal warnings from this write (e.g. REDIRECT_SHADOWS_PAGE when a manual redirect intercepts this URL).","type":"array","items":{"type":"string"}}},"required":["id","slug","path","parentSlug","isDirectory","depth","ancestors","breadcrumbs","breadcrumbSource","breadcrumbParentSlug","title","pageType","isHomePage","isVisible","order","globalHeaderId","globalFooterId","updatedAt","seo"],"additionalProperties":false},"example":{"id":"pg_example789","slug":"/about","path":["about"],"parentSlug":null,"isDirectory":false,"depth":1,"ancestors":[],"breadcrumbs":[],"breadcrumbSource":"url","breadcrumbParentSlug":null,"title":"About Us","pageType":"generic","isHomePage":false,"isVisible":true,"order":1,"globalHeaderId":"sec_header01","globalFooterId":"sec_footer01","updatedAt":"2026-10-06T08:00:00.000Z","seo":{"seoTitle":"About Us | Sunny Bakery","seoDescription":"Naturally leavened sourdough baked fresh every morning.","seoKeywords":["sourdough","artisan bakery"],"ogTitle":null,"ogDescription":null,"ogImage":null,"ogImageAssetId":null,"canonicalUrl":null,"robotsIndex":null,"robotsFollow":null,"excludeFromSiteSearch":false}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"pages.update","x-kanorio-mcp-tool":"pages_update","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"},"delete":{"operationId":"pages_delete","summary":"pages.delete","description":"Delete a page and its draft content. The home page cannot be deleted. When the page has subpages, you must pass mode: \"subtree\" (delete the page and all its subpages) or \"lift-children\" (move subpages up one level with 301 redirects before deleting the parent); omitting mode returns HAS_CHILDREN with details.children. Errors: FORBIDDEN, PAGE_NOT_FOUND, HOME_NOT_DELETABLE, HAS_CHILDREN, SLUG_TAKEN, REDIRECT_CONFLICT, REDIRECT_LIMIT.","tags":["pages"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"pageId","in":"path","required":true,"description":"Page id. Get it from pages.list.","schema":{"type":"string"}},{"name":"mode","in":"query","required":false,"description":"Required when deleting a parent page that has subpages: \"subtree\" deletes all descendants; \"lift-children\" moves subpages up one level first.","schema":{"description":"Required when deleting a parent page that has subpages: \"subtree\" deletes all descendants; \"lift-children\" moves subpages up one level first.","type":"string","enum":["subtree","lift-children"]}},{"name":"createRedirect","in":"query","required":false,"description":"With mode \"lift-children\": whether to create 301 redirects from the old subpage URLs for previously published subpages (defaults to true). Ignored otherwise.","schema":{"description":"With mode \"lift-children\": whether to create 301 redirects from the old subpage URLs for previously published subpages (defaults to true). Ignored otherwise.","type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true},"deletedCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"liftedCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","deleted"],"additionalProperties":false},"example":{"id":"pg_example789","deleted":true,"deletedCount":1}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"pages.delete","x-kanorio-mcp-tool":"pages_delete","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/pages/{pageId}/sections":{"put":{"operationId":"pages_replace_sections","summary":"pages.replace_sections","description":"Replace the whole draft section list of a page (optimistic concurrency). Get the shapes from sections.describe; read the page with pages.get and pass its updatedAt as ifUnmodifiedSince. If someone else (another agent or a person in the editor) changed the page since, the call fails with CONFLICT and details.updatedAt holds the current revision: re-read the page, merge, retry. Changes are saved as draft only; call site.publish to go live. Reference images and files as asset:<assetId> (from media.list, media.upload, media.import_stock, media.upload_link_status); values you read with pages.get can be sent back unchanged. Errors: FORBIDDEN, PAGE_NOT_FOUND, VALIDATION (details lists the failing section index and field), CONFLICT, ASSET_NOT_FOUND (details.assetIds: not in this site's media library), ASSET_NOT_ALLOWED (product files cannot be shown on pages).","tags":["pages"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"pageId","in":"path","required":true,"description":"Page id. Get it from pages.list.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ifUnmodifiedSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"The page's updatedAt from pages.get/pages.list. Required: the write is rejected with CONFLICT when it no longer matches."},"sections":{"maxItems":100,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Complete ordered list of section objects, each with `type` and a unique `id`."}},"required":["ifUnmodifiedSince","sections"]},"example":{"ifUnmodifiedSince":"2026-10-06T08:00:00.000Z","sections":[{"id":"sec_hero01","type":"hero","title":"Freshly baked sourdough every morning","subtitle":"Natural starter, local grain. Doors open at 7 a.m.","image":"asset:asset_example01","ctaIds":["btn_order"]},{"id":"sec_faq01","type":"faq","title":"Frequently Asked Questions","items":[{"question":"Can I pre-order loaves?","answer":"Yes, place pre-orders by 5 p.m. the day before."}]}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"sections":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Sections as stored after sanitization (media as asset:<assetId>)."},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files the sections use, by assetId."},"updatedAt":{"type":"string","description":"New revision marker; use it for the next replace."}},"required":["id","sections","assets","updatedAt"],"additionalProperties":false},"example":{"id":"pg_example456","sections":[{"id":"sec_hero01","type":"hero","title":"Freshly baked sourdough every morning","subtitle":"Natural starter, local grain. Doors open at 7 a.m.","image":"asset:asset_example01","ctaIds":["btn_order"]},{"id":"sec_faq01","type":"faq","title":"Frequently Asked Questions","items":[{"question":"Can I pre-order loaves?","answer":"Yes, place pre-orders by 5 p.m. the day before."}]}],"assets":{"asset_example01":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"sunny-bakery-hero.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":true,"createdAt":"2026-10-01T02:30:00.000Z"}},"updatedAt":"2026-10-06T08:01:30.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"pages.replace_sections","x-kanorio-mcp-tool":"pages_replace_sections","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/publish":{"post":{"operationId":"site_publish","summary":"site.publish","description":"Publish the current draft (all visible pages) so it is live. On first publish you must choose a subdomain (lowercase letters, digits, hyphens; it becomes https://<subdomain>.kanorio.com). Afterwards omit subdomain to keep the current one. Do not use this to change custom domains; use domains.bind. Publishing is rate-limited per token (30/hour). Errors: FORBIDDEN, SUBDOMAIN_MISSING (first publish without subdomain), SUBDOMAIN_TAKEN, RESERVED_SUBDOMAIN, INVALID_SUBDOMAIN, SUBDOMAIN_CHANGE_FORBIDDEN, PLAN_CANNOT_PUBLISH, FREE_VISIBLE_MODULE_LIMIT, FREE_VISIBLE_PAGE_LIMIT, CONTENT_VALIDATION_FAILED (details.issues lists pages/fields to fix), MODERATION_LOCKED, EMPTY_CONTENT, HOSTNAME_CONFLICT.","tags":["site"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subdomain":{"description":"Required on first publish. Defaults to the site's current subdomain, else its suggestedSubdomain.","type":"string","minLength":1,"maxLength":63}}},"example":{"subdomain":"sunny-bakery"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"publishedAt":{"type":"string"},"publicUrl":{"type":"string","description":"Live URL on kanorio.com."},"subdomain":{"type":"string"},"customDomainStatus":{"anyOf":[{"type":"string","enum":["ACTIVE","PENDING"]},{"type":"null"}]},"expectedVersion":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque content version; the edge may take up to ~30s to serve it."},"warning":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","description":"CONNECTION, DNS_DELAY, SYNC_DELAY, GENERIC_DELAY or GENERIC_SYNC."},"messages":{"type":"array","items":{"type":"string"}}},"required":["code","messages"],"additionalProperties":false},{"type":"null"}],"description":"Set when publishing succeeded but Cloudflare sync reported a delay; nothing to retry."}},"required":["publishedAt","publicUrl","subdomain","customDomainStatus","expectedVersion","warning"],"additionalProperties":false},"example":{"publishedAt":"2026-10-06T08:00:00.000Z","publicUrl":"https://sunny-bakery.kanorio.com","subdomain":"sunny-bakery","customDomainStatus":"ACTIVE","expectedVersion":"v_example01","warning":null}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"site.publish","x-kanorio-mcp-tool":"site_publish","x-kanorio-required-scope":"site:lifecycle","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agentPublish (30/hour per token)"}},"/sites/{id}/unpublish":{"post":{"operationId":"site_unpublish","summary":"site.unpublish","description":"Take the website offline (content and settings are kept; publish again to restore). Only the website owner may do this. Errors: OWNER_REQUIRED, WEBSITE_NOT_FOUND, FORBIDDEN.","tags":["site"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"unpublished":{"type":"boolean","const":true}},"required":["unpublished"],"additionalProperties":false},"example":{"unpublished":true}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"site.unpublish","x-kanorio-mcp-tool":"site_unpublish","x-kanorio-required-scope":"site:lifecycle","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agentPublish (30/hour per token)"}},"/sites/{id}/domains":{"get":{"operationId":"domains_list","summary":"domains.list","description":"List the custom domains bound to a website (primary first) with their verification status. Errors: FORBIDDEN, NOT_FOUND.","tags":["domains"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"object","properties":{"hostname":{"type":"string"},"kind":{"type":"string","description":"CUSTOM_PRIMARY (canonical) or CUSTOM_ALIAS (301 to primary)."},"isPrimary":{"type":"boolean"},"status":{"type":"string","description":"PENDING until DNS and TLS are verified, then ACTIVE."}},"required":["hostname","kind","isPrimary","status"],"additionalProperties":{}}}},"required":["domains"],"additionalProperties":false},"example":{"domains":[{"hostname":"www.sunnybakery.example","kind":"CUSTOM","isPrimary":true,"status":"ACTIVE"}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"domains.list","x-kanorio-mcp-tool":"domains_list","x-kanorio-required-scope":"site:manage_settings","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"put":{"operationId":"domains_bind","summary":"domains.bind","description":"Set the complete list of custom domains for a website: the first hostname becomes the primary (canonical) domain, the rest become aliases that 301-redirect to it. Hostnames missing from the list are unbound; pass an empty list to remove all custom domains. After binding, the owner must point DNS (CNAME) at Kanorio; call domains.status to see the exact record and verification progress. Requires a paid plan. Errors: FORBIDDEN, PRO_REQUIRED, INVALID_FORMAT, BLOCKED, HIGH_RISK_TLD, LIMIT_REACHED (details.max), TAKEN (used by another site), READD_COOLDOWN (details.retryAfterSeconds).","tags":["domains"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hostnames":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":253},"description":"Ordered hostnames without scheme, e.g. [\"www.example.com\", \"example.com\"]. First = primary."}},"required":["hostnames"]},"example":{"hostnames":["www.sunnybakery.example","sunnybakery.example"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"object","properties":{"hostname":{"type":"string"},"kind":{"type":"string","description":"CUSTOM_PRIMARY (canonical) or CUSTOM_ALIAS (301 to primary)."},"isPrimary":{"type":"boolean"},"status":{"type":"string","description":"PENDING until DNS and TLS are verified, then ACTIVE."}},"required":["hostname","kind","isPrimary","status"],"additionalProperties":{}}},"cloudflareErrors":{"type":"array","items":{"type":"string"},"description":"Non-fatal provisioning errors; the binding is saved and will be reconciled."},"cooldowns":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},{"type":"null"}],"description":"Removed hostnames → seconds before they can be re-added."}},"required":["domains","cloudflareErrors","cooldowns"],"additionalProperties":false},"example":{"domains":[{"hostname":"www.sunnybakery.example","kind":"CUSTOM","isPrimary":true,"status":"PENDING"}],"cloudflareErrors":[],"cooldowns":null}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"domains.bind","x-kanorio-mcp-tool":"domains_bind","x-kanorio-required-scope":"site:manage_settings","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/domains/status":{"get":{"operationId":"domains_status","summary":"domains.status","description":"Re-check DNS/TLS for every PENDING custom domain right now and return the current list. Domains that are still PENDING include a `diagnoses[hostname]` entry explaining what record is missing (expected vs. observed). Also returns the primary binding. Poll every 15-60 seconds after domains.bind until status is ACTIVE; DNS propagation can take minutes to hours. Errors: FORBIDDEN.","tags":["domains"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"object","properties":{"hostname":{"type":"string"},"kind":{"type":"string","description":"CUSTOM_PRIMARY (canonical) or CUSTOM_ALIAS (301 to primary)."},"isPrimary":{"type":"boolean"},"status":{"type":"string","description":"PENDING until DNS and TLS are verified, then ACTIVE."}},"required":["hostname","kind","isPrimary","status"],"additionalProperties":{}}},"primary":{"anyOf":[{"type":"object","properties":{"hostname":{"type":"string"},"status":{"type":"string"}},"required":["hostname","status"],"additionalProperties":false},{"type":"null"}]},"diagnoses":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["domains","primary","diagnoses"],"additionalProperties":false},"example":{"domains":[{"hostname":"www.sunnybakery.example","kind":"CUSTOM","isPrimary":true,"status":"ACTIVE"}],"primary":{"hostname":"www.sunnybakery.example","status":"ACTIVE"},"diagnoses":{}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"domains.status","x-kanorio-mcp-tool":"domains_status","x-kanorio-required-scope":"site:manage_settings","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/posts":{"get":{"operationId":"posts_list","summary":"posts.list","description":"List blog posts (drafts and published) with status, taxonomy and revision timestamps; contentMarkdown is not included, use posts.get. Filter by status, category, tag or search; sort by edited/published/views. Errors: FORBIDDEN.","tags":["posts"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["DRAFT","PUBLISHED"]},"example":"DRAFT"},{"name":"search","in":"query","required":false,"description":"Case-insensitive match on title or slug.","schema":{"description":"Case-insensitive match on title or slug.","type":"string","maxLength":200}},{"name":"categoryId","in":"query","required":false,"schema":{"type":"string"}},{"name":"tagId","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Defaults to edited_desc.","schema":{"description":"Defaults to edited_desc.","type":"string","enum":["edited_desc","edited_asc","published_desc","published_asc","views_desc","views_asc"]}},{"name":"limit","in":"query","required":false,"description":"Page size (1-100). Defaults vary per capability.","schema":{"description":"Page size (1-100). Defaults vary per capability.","type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Number of items to skip.","schema":{"description":"Number of items to skip.","type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["DRAFT","PUBLISHED"]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string"},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"readingTimeMin":{"anyOf":[{"type":"number"},{"type":"null"}]},"hasDraftChanges":{"type":"boolean","description":"Published post has edits not yet re-published."},"primaryCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false},{"type":"null"}]},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"coverImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ogImage, else auto-generated OG image, else first image in content."},"pageviews":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","slug","title","excerpt","status","publishedAt","updatedAt","contentUpdatedAt","readingTimeMin","hasDraftChanges","primaryCategory","categories","tags","authors","coverImage"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["posts","total"],"additionalProperties":false},"example":{"posts":[{"id":"post_example01","slug":"how-we-feed-our-starter","title":"How we feed our sourdough starter","excerpt":"The first thing we do at 5 a.m. every morning.","status":"DRAFT","publishedAt":null,"updatedAt":"2026-10-06T08:00:00.000Z","contentUpdatedAt":"2026-10-06T08:00:00.000Z","readingTimeMin":4,"hasDraftChanges":true,"primaryCategory":{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"},"categories":[{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"}],"tags":[{"id":"tag_example01","slug":"sourdough","name":"Sourdough"}],"authors":[{"id":"author_example01","slug":"sunny","name":"Sunny"}],"coverImage":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","pageviews":0}],"total":1}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"posts.list","x-kanorio-mcp-tool":"posts_list","x-kanorio-required-scope":"posts:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"posts_create","summary":"posts.create","description":"Create a blog post as a DRAFT. Drafts are not visible on the public site until posts.publish. Taxonomy ids (categoryIds, tagIds, authorIds) must belong to this website; use blog_categories.list / blog_tags.list first. Errors: FORBIDDEN, VALIDATION, SLUG_TAKEN, ASSET_NOT_FOUND (details.assetIds: not in this site's media library; the share image also must not be in the trash), ASSET_NOT_ALLOWED (product files, or a non-image as the share image).","tags":["posts"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"slug":{"description":"URL slug without leading slash; generated from title when omitted and de-duplicated per website.","type":"string","maxLength":200},"excerpt":{"type":"string","maxLength":2000},"contentMarkdown":{"description":"Markdown body. Reference media-library images as ![alt](asset:<assetId>) (media.upload, media.import_stock); content read with posts.get can be sent back unchanged.","type":"string"},"authorIds":{"description":"Ids from this website's blog authors.","type":"array","items":{"type":"string"}},"primaryCategoryId":{"description":"Must also be in categoryIds.","anyOf":[{"type":"string"},{"type":"null"}]},"categoryIds":{"description":"Ids from blog_categories.list.","type":"array","items":{"type":"string"}},"tagIds":{"description":"Ids from blog_tags.list.","type":"array","items":{"type":"string"}},"showToc":{"type":"boolean"},"seoTitle":{"type":"string","maxLength":200},"seoDescription":{"type":"string","maxLength":500},"seoKeywords":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":30}},"ogImageAlt":{"type":"string","maxLength":125},"ogTitle":{"type":"string","maxLength":200},"ogDescription":{"type":"string","maxLength":200},"canonicalUrl":{"type":"string"},"robotsIndex":{"type":"string","enum":["index","noindex"]},"robotsFollow":{"type":"string","enum":["follow","nofollow"]},"twitterCard":{"type":"string","enum":["summary","summary_large_image"]},"autoOgEnabled":{"type":"boolean"},"excludeFromSiteSearch":{"description":"Exclude this post from visitor site search (/api/v1/search and the /search page); does not affect search engine indexing (robotsIndex).","type":"boolean"},"ogImageAssetId":{"description":"Share image: assetId of an image in the media library. null removes it; without a share image one is generated automatically.","anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]}},"required":["title"]},"example":{"title":"How we feed our sourdough starter","contentMarkdown":"## 5 a.m. in the bakehouse\n\nDiscard half the starter, then fold in fresh flour and warm water...","categoryIds":["cat_example01"],"tagIds":["tag_example01"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["DRAFT","PUBLISHED"]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string"},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"readingTimeMin":{"anyOf":[{"type":"number"},{"type":"null"}]},"hasDraftChanges":{"type":"boolean","description":"Published post has edits not yet re-published."},"primaryCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false},{"type":"null"}]},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"contentMarkdown":{"type":"string"},"segments":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Structured content blocks (markdown, cta, faq, gallery, toggle, embed, audio, pdf, file) parsed from contentMarkdown."},"toc":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"level":{"anyOf":[{"type":"number","const":2},{"type":"number","const":3}]}},"required":["id","label","level"],"additionalProperties":false},"description":"Table of contents headings (H2/H3) with anchor ids."},"showToc":{"type":"boolean"},"seo":{"type":"object","properties":{"seoTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoKeywords":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Share image display URL (changes with versions; do not store it)."},"ogImageAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId of the share image when it is in the media library."},"ogImageAlt":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"canonicalUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsIndex":{"type":"string"},"robotsFollow":{"type":"string"},"twitterCard":{"type":"string"},"autoOgEnabled":{"type":"boolean"},"autoOgImage":{"anyOf":[{"type":"string"},{"type":"null"}]},"excludeFromSiteSearch":{"type":"boolean","description":"When true, this post is excluded from visitor site search (independent of robotsIndex)."}},"required":["seoTitle","seoDescription","seoKeywords","ogImage","ogImageAssetId","ogImageAlt","ogTitle","ogDescription","canonicalUrl","robotsIndex","robotsFollow","twitterCard","autoOgEnabled","autoOgImage","excludeFromSiteSearch"],"additionalProperties":false},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files contentMarkdown and the share image use, by assetId."},"createdAt":{"type":"string"}},"required":["id","slug","title","excerpt","status","publishedAt","updatedAt","contentUpdatedAt","readingTimeMin","hasDraftChanges","primaryCategory","categories","tags","authors","contentMarkdown","segments","toc","showToc","seo","assets","createdAt"],"additionalProperties":false},"example":{"id":"post_example01","slug":"how-we-feed-our-starter","title":"How we feed our sourdough starter","excerpt":"The first thing we do at 5 a.m. every morning.","status":"DRAFT","publishedAt":null,"updatedAt":"2026-10-06T08:00:00.000Z","contentUpdatedAt":"2026-10-06T08:00:00.000Z","readingTimeMin":4,"hasDraftChanges":true,"primaryCategory":{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"},"categories":[{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"}],"tags":[{"id":"tag_example01","slug":"sourdough","name":"Sourdough"}],"authors":[{"id":"author_example01","slug":"sunny","name":"Sunny"}],"contentMarkdown":"## 5 a.m. in the bakehouse\n\n![Starter jar on the counter](asset:asset_example01)\n\nDiscard half the starter, then fold in fresh flour and warm water...","segments":[{"type":"markdown","value":"## 5 a.m. in the bakehouse\n\n![Starter jar on the counter](https://media.kanorio.com/example/sunny-bakery-hero.jpg)\n\nDiscard half the starter, then fold in fresh flour and warm water..."}],"toc":[{"id":"5-am-in-the-bakehouse","label":"5 a.m. in the bakehouse","level":2}],"showToc":true,"seo":{"seoTitle":null,"seoDescription":null,"seoKeywords":null,"ogImage":null,"ogImageAssetId":null,"ogImageAlt":null,"ogTitle":null,"ogDescription":null,"canonicalUrl":null,"robotsIndex":"index","robotsFollow":"follow","twitterCard":"summary_large_image","autoOgEnabled":true,"autoOgImage":null,"excludeFromSiteSearch":false},"assets":{"asset_example01":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"sunny-bakery-hero.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":true,"createdAt":"2026-10-01T02:30:00.000Z"}},"createdAt":"2026-10-01T02:30:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"posts.create","x-kanorio-mcp-tool":"posts_create","x-kanorio-required-scope":"blog:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/posts/{postId}":{"get":{"operationId":"posts_get","summary":"posts.get","description":"Get one blog post including the working-copy contentMarkdown (what the editor shows, not necessarily the published copy) and SEO fields. Errors: FORBIDDEN, POST_NOT_FOUND.","tags":["posts"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"postId","in":"path","required":true,"description":"Blog post id. Get it from posts.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["DRAFT","PUBLISHED"]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string"},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"readingTimeMin":{"anyOf":[{"type":"number"},{"type":"null"}]},"hasDraftChanges":{"type":"boolean","description":"Published post has edits not yet re-published."},"primaryCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false},{"type":"null"}]},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"contentMarkdown":{"type":"string"},"segments":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Structured content blocks (markdown, cta, faq, gallery, toggle, embed, audio, pdf, file) parsed from contentMarkdown."},"toc":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"level":{"anyOf":[{"type":"number","const":2},{"type":"number","const":3}]}},"required":["id","label","level"],"additionalProperties":false},"description":"Table of contents headings (H2/H3) with anchor ids."},"showToc":{"type":"boolean"},"seo":{"type":"object","properties":{"seoTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoKeywords":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Share image display URL (changes with versions; do not store it)."},"ogImageAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId of the share image when it is in the media library."},"ogImageAlt":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"canonicalUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsIndex":{"type":"string"},"robotsFollow":{"type":"string"},"twitterCard":{"type":"string"},"autoOgEnabled":{"type":"boolean"},"autoOgImage":{"anyOf":[{"type":"string"},{"type":"null"}]},"excludeFromSiteSearch":{"type":"boolean","description":"When true, this post is excluded from visitor site search (independent of robotsIndex)."}},"required":["seoTitle","seoDescription","seoKeywords","ogImage","ogImageAssetId","ogImageAlt","ogTitle","ogDescription","canonicalUrl","robotsIndex","robotsFollow","twitterCard","autoOgEnabled","autoOgImage","excludeFromSiteSearch"],"additionalProperties":false},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files contentMarkdown and the share image use, by assetId."},"createdAt":{"type":"string"}},"required":["id","slug","title","excerpt","status","publishedAt","updatedAt","contentUpdatedAt","readingTimeMin","hasDraftChanges","primaryCategory","categories","tags","authors","contentMarkdown","segments","toc","showToc","seo","assets","createdAt"],"additionalProperties":false},"example":{"id":"post_example01","slug":"how-we-feed-our-starter","title":"How we feed our sourdough starter","excerpt":"The first thing we do at 5 a.m. every morning.","status":"DRAFT","publishedAt":null,"updatedAt":"2026-10-06T08:00:00.000Z","contentUpdatedAt":"2026-10-06T08:00:00.000Z","readingTimeMin":4,"hasDraftChanges":true,"primaryCategory":{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"},"categories":[{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"}],"tags":[{"id":"tag_example01","slug":"sourdough","name":"Sourdough"}],"authors":[{"id":"author_example01","slug":"sunny","name":"Sunny"}],"contentMarkdown":"## 5 a.m. in the bakehouse\n\n![Starter jar on the counter](asset:asset_example01)\n\nDiscard half the starter, then fold in fresh flour and warm water...","segments":[{"type":"markdown","value":"## 5 a.m. in the bakehouse\n\n![Starter jar on the counter](https://media.kanorio.com/example/sunny-bakery-hero.jpg)\n\nDiscard half the starter, then fold in fresh flour and warm water..."}],"toc":[{"id":"5-am-in-the-bakehouse","label":"5 a.m. in the bakehouse","level":2}],"showToc":true,"seo":{"seoTitle":null,"seoDescription":null,"seoKeywords":null,"ogImage":null,"ogImageAssetId":null,"ogImageAlt":null,"ogTitle":null,"ogDescription":null,"canonicalUrl":null,"robotsIndex":"index","robotsFollow":"follow","twitterCard":"summary_large_image","autoOgEnabled":true,"autoOgImage":null,"excludeFromSiteSearch":false},"assets":{"asset_example01":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"sunny-bakery-hero.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":true,"createdAt":"2026-10-01T02:30:00.000Z"}},"createdAt":"2026-10-01T02:30:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"posts.get","x-kanorio-mcp-tool":"posts_get","x-kanorio-required-scope":"posts:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"patch":{"operationId":"posts_update","summary":"posts.update","description":"Partially update a blog post's working copy (only provided fields change; categoryIds/tagIds/authorIds replace the whole list when provided). Editing a PUBLISHED post does not change the public copy until posts.publish is called again (hasDraftChanges becomes true). Errors: FORBIDDEN, POST_NOT_FOUND, VALIDATION, SLUG_TAKEN, ASSET_NOT_FOUND (details.assetIds: not in this site's media library; the share image also must not be in the trash), ASSET_NOT_ALLOWED (product files, or a non-image as the share image).","tags":["posts"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"postId","in":"path","required":true,"description":"Blog post id. Get it from posts.list.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"slug":{"description":"URL slug without leading slash; generated from title when omitted and de-duplicated per website.","type":"string","maxLength":200},"excerpt":{"type":"string","maxLength":2000},"contentMarkdown":{"description":"Markdown body. Reference media-library images as ![alt](asset:<assetId>) (media.upload, media.import_stock); content read with posts.get can be sent back unchanged.","type":"string"},"authorIds":{"description":"Ids from this website's blog authors.","type":"array","items":{"type":"string"}},"primaryCategoryId":{"description":"Must also be in categoryIds.","anyOf":[{"type":"string"},{"type":"null"}]},"categoryIds":{"description":"Ids from blog_categories.list.","type":"array","items":{"type":"string"}},"tagIds":{"description":"Ids from blog_tags.list.","type":"array","items":{"type":"string"}},"showToc":{"type":"boolean"},"seoTitle":{"type":"string","maxLength":200},"seoDescription":{"type":"string","maxLength":500},"seoKeywords":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":30}},"ogImageAlt":{"type":"string","maxLength":125},"ogTitle":{"type":"string","maxLength":200},"ogDescription":{"type":"string","maxLength":200},"canonicalUrl":{"type":"string"},"robotsIndex":{"type":"string","enum":["index","noindex"]},"robotsFollow":{"type":"string","enum":["follow","nofollow"]},"twitterCard":{"type":"string","enum":["summary","summary_large_image"]},"autoOgEnabled":{"type":"boolean"},"excludeFromSiteSearch":{"description":"Exclude this post from visitor site search (/api/v1/search and the /search page); does not affect search engine indexing (robotsIndex).","type":"boolean"},"ogImageAssetId":{"description":"Share image: assetId of an image in the media library. null removes it; without a share image one is generated automatically.","anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]}}},"example":{"excerpt":"The first thing we do at 5 a.m. every morning."}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["DRAFT","PUBLISHED"]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string"},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"readingTimeMin":{"anyOf":[{"type":"number"},{"type":"null"}]},"hasDraftChanges":{"type":"boolean","description":"Published post has edits not yet re-published."},"primaryCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false},{"type":"null"}]},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"contentMarkdown":{"type":"string"},"segments":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Structured content blocks (markdown, cta, faq, gallery, toggle, embed, audio, pdf, file) parsed from contentMarkdown."},"toc":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"level":{"anyOf":[{"type":"number","const":2},{"type":"number","const":3}]}},"required":["id","label","level"],"additionalProperties":false},"description":"Table of contents headings (H2/H3) with anchor ids."},"showToc":{"type":"boolean"},"seo":{"type":"object","properties":{"seoTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoKeywords":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Share image display URL (changes with versions; do not store it)."},"ogImageAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId of the share image when it is in the media library."},"ogImageAlt":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"canonicalUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsIndex":{"type":"string"},"robotsFollow":{"type":"string"},"twitterCard":{"type":"string"},"autoOgEnabled":{"type":"boolean"},"autoOgImage":{"anyOf":[{"type":"string"},{"type":"null"}]},"excludeFromSiteSearch":{"type":"boolean","description":"When true, this post is excluded from visitor site search (independent of robotsIndex)."}},"required":["seoTitle","seoDescription","seoKeywords","ogImage","ogImageAssetId","ogImageAlt","ogTitle","ogDescription","canonicalUrl","robotsIndex","robotsFollow","twitterCard","autoOgEnabled","autoOgImage","excludeFromSiteSearch"],"additionalProperties":false},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files contentMarkdown and the share image use, by assetId."},"createdAt":{"type":"string"}},"required":["id","slug","title","excerpt","status","publishedAt","updatedAt","contentUpdatedAt","readingTimeMin","hasDraftChanges","primaryCategory","categories","tags","authors","contentMarkdown","segments","toc","showToc","seo","assets","createdAt"],"additionalProperties":false},"example":{"id":"post_example01","slug":"how-we-feed-our-starter","title":"How we feed our sourdough starter","excerpt":"The first thing we do at 5 a.m. every morning.","status":"DRAFT","publishedAt":null,"updatedAt":"2026-10-06T08:00:00.000Z","contentUpdatedAt":"2026-10-06T08:00:00.000Z","readingTimeMin":4,"hasDraftChanges":true,"primaryCategory":{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"},"categories":[{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"}],"tags":[{"id":"tag_example01","slug":"sourdough","name":"Sourdough"}],"authors":[{"id":"author_example01","slug":"sunny","name":"Sunny"}],"contentMarkdown":"## 5 a.m. in the bakehouse\n\n![Starter jar on the counter](asset:asset_example01)\n\nDiscard half the starter, then fold in fresh flour and warm water...","segments":[{"type":"markdown","value":"## 5 a.m. in the bakehouse\n\n![Starter jar on the counter](https://media.kanorio.com/example/sunny-bakery-hero.jpg)\n\nDiscard half the starter, then fold in fresh flour and warm water..."}],"toc":[{"id":"5-am-in-the-bakehouse","label":"5 a.m. in the bakehouse","level":2}],"showToc":true,"seo":{"seoTitle":null,"seoDescription":null,"seoKeywords":null,"ogImage":null,"ogImageAssetId":null,"ogImageAlt":null,"ogTitle":null,"ogDescription":null,"canonicalUrl":null,"robotsIndex":"index","robotsFollow":"follow","twitterCard":"summary_large_image","autoOgEnabled":true,"autoOgImage":null,"excludeFromSiteSearch":false},"assets":{"asset_example01":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"sunny-bakery-hero.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":true,"createdAt":"2026-10-01T02:30:00.000Z"}},"createdAt":"2026-10-01T02:30:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"posts.update","x-kanorio-mcp-tool":"posts_update","x-kanorio-required-scope":"blog:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/posts/{postId}/publish":{"post":{"operationId":"posts_publish","summary":"posts.publish","description":"Publish a blog post (or re-publish a published post's pending edits). Snapshots the working copy to the public site immediately; the website itself must already be published (site.publish) and on a paid plan. Errors: FORBIDDEN, POST_NOT_FOUND, PRO_REQUIRED, SITE_NOT_PUBLISHED, SLUG_TAKEN.","tags":["posts"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"postId","in":"path","required":true,"description":"Blog post id. Get it from posts.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["DRAFT","PUBLISHED"]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string"},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"readingTimeMin":{"anyOf":[{"type":"number"},{"type":"null"}]},"hasDraftChanges":{"type":"boolean","description":"Published post has edits not yet re-published."},"primaryCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false},{"type":"null"}]},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"contentMarkdown":{"type":"string"},"segments":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Structured content blocks (markdown, cta, faq, gallery, toggle, embed, audio, pdf, file) parsed from contentMarkdown."},"toc":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"level":{"anyOf":[{"type":"number","const":2},{"type":"number","const":3}]}},"required":["id","label","level"],"additionalProperties":false},"description":"Table of contents headings (H2/H3) with anchor ids."},"showToc":{"type":"boolean"},"seo":{"type":"object","properties":{"seoTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoKeywords":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Share image display URL (changes with versions; do not store it)."},"ogImageAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId of the share image when it is in the media library."},"ogImageAlt":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"canonicalUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsIndex":{"type":"string"},"robotsFollow":{"type":"string"},"twitterCard":{"type":"string"},"autoOgEnabled":{"type":"boolean"},"autoOgImage":{"anyOf":[{"type":"string"},{"type":"null"}]},"excludeFromSiteSearch":{"type":"boolean","description":"When true, this post is excluded from visitor site search (independent of robotsIndex)."}},"required":["seoTitle","seoDescription","seoKeywords","ogImage","ogImageAssetId","ogImageAlt","ogTitle","ogDescription","canonicalUrl","robotsIndex","robotsFollow","twitterCard","autoOgEnabled","autoOgImage","excludeFromSiteSearch"],"additionalProperties":false},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files contentMarkdown and the share image use, by assetId."},"createdAt":{"type":"string"},"warning":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Set when the post went live but the automatic OG image could not be generated."}},"required":["id","slug","title","excerpt","status","publishedAt","updatedAt","contentUpdatedAt","readingTimeMin","hasDraftChanges","primaryCategory","categories","tags","authors","contentMarkdown","segments","toc","showToc","seo","assets","createdAt","warning"],"additionalProperties":false},"example":{"id":"post_example01","slug":"how-we-feed-our-starter","title":"How we feed our sourdough starter","excerpt":"The first thing we do at 5 a.m. every morning.","status":"PUBLISHED","publishedAt":"2026-10-06T08:00:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z","contentUpdatedAt":"2026-10-06T08:00:00.000Z","readingTimeMin":4,"hasDraftChanges":false,"primaryCategory":{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"},"categories":[{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"}],"tags":[{"id":"tag_example01","slug":"sourdough","name":"Sourdough"}],"authors":[{"id":"author_example01","slug":"sunny","name":"Sunny"}],"contentMarkdown":"## 5 a.m. in the bakehouse\n\n![Starter jar on the counter](asset:asset_example01)\n\nDiscard half the starter, then fold in fresh flour and warm water...","segments":[{"type":"markdown","value":"## 5 a.m. in the bakehouse\n\n![Starter jar on the counter](https://media.kanorio.com/example/sunny-bakery-hero.jpg)\n\nDiscard half the starter, then fold in fresh flour and warm water..."}],"toc":[{"id":"5-am-in-the-bakehouse","label":"5 a.m. in the bakehouse","level":2}],"showToc":true,"seo":{"seoTitle":null,"seoDescription":null,"seoKeywords":null,"ogImage":null,"ogImageAssetId":null,"ogImageAlt":null,"ogTitle":null,"ogDescription":null,"canonicalUrl":null,"robotsIndex":"index","robotsFollow":"follow","twitterCard":"summary_large_image","autoOgEnabled":true,"autoOgImage":null,"excludeFromSiteSearch":false},"assets":{"asset_example01":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"sunny-bakery-hero.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":true,"createdAt":"2026-10-01T02:30:00.000Z"}},"createdAt":"2026-10-01T02:30:00.000Z","warning":null}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"posts.publish","x-kanorio-mcp-tool":"posts_publish","x-kanorio-required-scope":"blog:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agentPublish (30/hour per token)"}},"/sites/{id}/posts/{postId}/unpublish":{"post":{"operationId":"posts_unpublish","summary":"posts.unpublish","description":"Revert a published post to DRAFT so it disappears from the public site. The content is kept; publishedAt is preserved as the first-publish date. Errors: FORBIDDEN, POST_NOT_FOUND.","tags":["posts"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"postId","in":"path","required":true,"description":"Blog post id. Get it from posts.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["DRAFT","PUBLISHED"]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string"},"contentUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"readingTimeMin":{"anyOf":[{"type":"number"},{"type":"null"}]},"hasDraftChanges":{"type":"boolean","description":"Published post has edits not yet re-published."},"primaryCategory":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false},{"type":"null"}]},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"],"additionalProperties":false}},"contentMarkdown":{"type":"string"},"segments":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Structured content blocks (markdown, cta, faq, gallery, toggle, embed, audio, pdf, file) parsed from contentMarkdown."},"toc":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"level":{"anyOf":[{"type":"number","const":2},{"type":"number","const":3}]}},"required":["id","label","level"],"additionalProperties":false},"description":"Table of contents headings (H2/H3) with anchor ids."},"showToc":{"type":"boolean"},"seo":{"type":"object","properties":{"seoTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"seoKeywords":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Share image display URL (changes with versions; do not store it)."},"ogImageAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId of the share image when it is in the media library."},"ogImageAlt":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogDescription":{"anyOf":[{"type":"string"},{"type":"null"}]},"canonicalUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsIndex":{"type":"string"},"robotsFollow":{"type":"string"},"twitterCard":{"type":"string"},"autoOgEnabled":{"type":"boolean"},"autoOgImage":{"anyOf":[{"type":"string"},{"type":"null"}]},"excludeFromSiteSearch":{"type":"boolean","description":"When true, this post is excluded from visitor site search (independent of robotsIndex)."}},"required":["seoTitle","seoDescription","seoKeywords","ogImage","ogImageAssetId","ogImageAlt","ogTitle","ogDescription","canonicalUrl","robotsIndex","robotsFollow","twitterCard","autoOgEnabled","autoOgImage","excludeFromSiteSearch"],"additionalProperties":false},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library files contentMarkdown and the share image use, by assetId."},"createdAt":{"type":"string"}},"required":["id","slug","title","excerpt","status","publishedAt","updatedAt","contentUpdatedAt","readingTimeMin","hasDraftChanges","primaryCategory","categories","tags","authors","contentMarkdown","segments","toc","showToc","seo","assets","createdAt"],"additionalProperties":false},"example":{"id":"post_example01","slug":"how-we-feed-our-starter","title":"How we feed our sourdough starter","excerpt":"The first thing we do at 5 a.m. every morning.","status":"DRAFT","publishedAt":null,"updatedAt":"2026-10-06T08:00:00.000Z","contentUpdatedAt":"2026-10-06T08:00:00.000Z","readingTimeMin":4,"hasDraftChanges":true,"primaryCategory":{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"},"categories":[{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes"}],"tags":[{"id":"tag_example01","slug":"sourdough","name":"Sourdough"}],"authors":[{"id":"author_example01","slug":"sunny","name":"Sunny"}],"contentMarkdown":"## 5 a.m. in the bakehouse\n\n![Starter jar on the counter](asset:asset_example01)\n\nDiscard half the starter, then fold in fresh flour and warm water...","segments":[{"type":"markdown","value":"## 5 a.m. in the bakehouse\n\n![Starter jar on the counter](https://media.kanorio.com/example/sunny-bakery-hero.jpg)\n\nDiscard half the starter, then fold in fresh flour and warm water..."}],"toc":[{"id":"5-am-in-the-bakehouse","label":"5 a.m. in the bakehouse","level":2}],"showToc":true,"seo":{"seoTitle":null,"seoDescription":null,"seoKeywords":null,"ogImage":null,"ogImageAssetId":null,"ogImageAlt":null,"ogTitle":null,"ogDescription":null,"canonicalUrl":null,"robotsIndex":"index","robotsFollow":"follow","twitterCard":"summary_large_image","autoOgEnabled":true,"autoOgImage":null,"excludeFromSiteSearch":false},"assets":{"asset_example01":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"sunny-bakery-hero.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":true,"createdAt":"2026-10-01T02:30:00.000Z"}},"createdAt":"2026-10-01T02:30:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"posts.unpublish","x-kanorio-mcp-tool":"posts_unpublish","x-kanorio-required-scope":"blog:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agentPublish (30/hour per token)"}},"/sites/{id}/blog/categories":{"get":{"operationId":"blog_categories_list","summary":"blog_categories.list","description":"List this website's blog categories (id, slug, name, counts.posts). Use the ids in posts.create / posts.update categoryIds and primaryCategoryId. Errors: FORBIDDEN.","tags":["blog_categories"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"counts":{"type":"object","properties":{"posts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of published posts in this taxonomy."}},"required":["posts"],"additionalProperties":false,"description":"Published post count."}},"required":["id","slug","name","description","sortOrder","counts"],"additionalProperties":false}}},"required":["categories"],"additionalProperties":false},"example":{"categories":[{"id":"cat_example01","slug":"bread-notes","name":"Bread Notes","description":"Notes from the bakehouse.","sortOrder":0,"counts":{"posts":3}}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"blog_categories.list","x-kanorio-mcp-tool":"blog_categories_list","x-kanorio-required-scope":"posts:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/blog/tags":{"get":{"operationId":"blog_tags_list","summary":"blog_tags.list","description":"List this website's blog tags (id, slug, name, counts.posts). Use the ids in posts.create / posts.update tagIds. Errors: FORBIDDEN.","tags":["blog_tags"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"counts":{"type":"object","properties":{"posts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of published posts in this taxonomy."}},"required":["posts"],"additionalProperties":false,"description":"Published post count."}},"required":["id","slug","name","counts"],"additionalProperties":false}}},"required":["tags"],"additionalProperties":false},"example":{"tags":[{"id":"tag_example01","slug":"sourdough","name":"Sourdough","counts":{"posts":3}}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"blog_tags.list","x-kanorio-mcp-tool":"blog_tags_list","x-kanorio-required-scope":"posts:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/collections":{"get":{"operationId":"collections_list","summary":"collections.list","description":"List the site's collections (custom and system) with their field schemas and item counts. Call this before reading or writing items. Errors: FORBIDDEN.","tags":["collections"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"displayName":{"type":"string"},"singularName":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string","enum":["custom","system"],"description":"system collections (blog) have reserved fields that cannot be removed or retyped."},"systemKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"text"},"min":{"type":"integer","minimum":0,"maximum":20000},"max":{"type":"integer","minimum":1,"maximum":20000},"pattern":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"rich_text"},"max":{"type":"integer","minimum":1,"maximum":50000}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"email"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"phone"},"defaultCountry":{"type":"string","minLength":2,"maxLength":2}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"url"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"video_url"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"number"},"integer":{"type":"boolean"},"min":{"type":"number"},"max":{"type":"number"},"default":{"type":"number"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"boolean"},"default":{"type":"boolean"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"date"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"datetime"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"],"additionalProperties":false}},"default":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","required","type","options"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"],"additionalProperties":false}},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50},"default":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}}},"required":["id","name","required","type","options"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"color"},"default":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"image"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"gallery"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"file"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","required","type","targetCollectionKey"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","required","type","targetCollectionKey"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"json"}},"required":["id","name","required","type"],"additionalProperties":false}]}},"titleFieldId":{"type":"string"},"createdBy":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","user"]},"actorId":{"type":"string"},"clientName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","actorId"],"additionalProperties":false},"itemCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","displayName","singularName","description","kind","systemKey","fields","titleFieldId","createdBy","itemCount","createdAt","updatedAt"],"additionalProperties":false}}},"required":["collections"],"additionalProperties":false},"example":{"collections":[{"id":"coll_example01","key":"teachers","displayName":"Teachers","singularName":"Teacher","description":"Faculty shown on the About page.","kind":"custom","systemKey":null,"fields":[{"id":"name","name":"Name","type":"text","required":true,"max":80,"unique":true,"aiHint":"Full name as shown on the site."},{"id":"avatar","name":"Avatar","type":"image","required":false,"help":"Square portrait."},{"id":"subjects","name":"Subjects","type":"multi_select","required":true,"options":[{"id":"math","label":"Math"},{"id":"english","label":"English"},{"id":"physics","label":"Physics"}]},{"id":"bio","name":"Bio","type":"rich_text","required":false,"max":2000},{"id":"website","name":"Personal website","type":"url","required":false},{"id":"course","name":"Main course","type":"reference","required":false,"targetCollectionKey":"courses"}],"titleFieldId":"name","createdBy":{"kind":"agent","actorId":"user_example01","clientName":"Cursor"},"itemCount":3,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"},{"id":"coll_example02","key":"courses","displayName":"Courses","singularName":"Course","description":null,"kind":"custom","systemKey":null,"fields":[{"id":"name","name":"Name","type":"text","required":true}],"titleFieldId":"name","createdBy":{"kind":"agent","actorId":"user_example01","clientName":"Cursor"},"itemCount":2,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"collections.list","x-kanorio-mcp-tool":"collections_list","x-kanorio-required-scope":"collections:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"collections_create","summary":"collections.create","description":"Create a collection (a small database for site content: teachers, projects, locations, FAQ…). Not for app data such as members, orders or comments. Field types: text, rich_text, email, phone, url, video_url, number, boolean, date, datetime, select, multi_select, color, image, gallery, file, reference, multi_reference, json. Every field needs id (snake_case), name, type; required defaults to false. Constraints: text min/max/pattern/unique/default; number integer/min/max/unique; select/multi_select options [{id,label}]; reference/multi_reference targetCollectionKey; gallery/multi_* max. Add aiHint to tell future agents how to fill a field. titleFieldId must point to a text/email/url field; it names items and generates slugs. Returns the Delivery API endpoints and a fetch example. Errors: FORBIDDEN, VALIDATION (details.issues), KEY_TAKEN, COLLECTION_LIMIT_REACHED, SYSTEM_COLLECTION (reserved key).","tags":["collections"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"displayName":{"type":"string","minLength":1,"maxLength":80},"singularName":{"type":"string","minLength":1,"maxLength":80},"description":{"type":"string","maxLength":500},"fields":{"minItems":1,"maxItems":50,"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"text"},"min":{"type":"integer","minimum":0,"maximum":20000},"max":{"type":"integer","minimum":1,"maximum":20000},"pattern":{"type":"string"},"default":{"type":"string"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"rich_text"},"max":{"type":"integer","minimum":1,"maximum":50000}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"email"},"default":{"type":"string"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"phone"},"defaultCountry":{"type":"string","minLength":2,"maxLength":2}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"url"},"default":{"type":"string"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"video_url"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"number"},"integer":{"type":"boolean"},"min":{"type":"number"},"max":{"type":"number"},"default":{"type":"number"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"boolean"},"default":{"type":"boolean"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"date"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"datetime"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"]}},"default":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","type","options"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"]}},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50},"default":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}}},"required":["id","name","type","options"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"color"},"default":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"image"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"gallery"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"file"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","type","targetCollectionKey"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","type","targetCollectionKey"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"json"}},"required":["id","name","type"]}]}},"titleFieldId":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["key","displayName","singularName","fields","titleFieldId"]},"example":{"key":"teachers","displayName":"Teachers","singularName":"Teacher","description":"Faculty shown on the About page.","titleFieldId":"name","fields":[{"id":"name","name":"Name","type":"text","required":true,"max":80,"unique":true,"aiHint":"Full name as shown on the site."},{"id":"avatar","name":"Avatar","type":"image","required":false,"help":"Square portrait."},{"id":"subjects","name":"Subjects","type":"multi_select","required":true,"options":[{"id":"math","label":"Math"},{"id":"english","label":"English"},{"id":"physics","label":"Physics"}]},{"id":"bio","name":"Bio","type":"rich_text","required":false,"max":2000},{"id":"website","name":"Personal website","type":"url","required":false},{"id":"course","name":"Main course","type":"reference","required":false,"targetCollectionKey":"courses"}]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"displayName":{"type":"string"},"singularName":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string","enum":["custom","system"],"description":"system collections (blog) have reserved fields that cannot be removed or retyped."},"systemKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"text"},"min":{"type":"integer","minimum":0,"maximum":20000},"max":{"type":"integer","minimum":1,"maximum":20000},"pattern":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"rich_text"},"max":{"type":"integer","minimum":1,"maximum":50000}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"email"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"phone"},"defaultCountry":{"type":"string","minLength":2,"maxLength":2}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"url"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"video_url"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"number"},"integer":{"type":"boolean"},"min":{"type":"number"},"max":{"type":"number"},"default":{"type":"number"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"boolean"},"default":{"type":"boolean"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"date"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"datetime"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"],"additionalProperties":false}},"default":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","required","type","options"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"],"additionalProperties":false}},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50},"default":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}}},"required":["id","name","required","type","options"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"color"},"default":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"image"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"gallery"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"file"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","required","type","targetCollectionKey"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","required","type","targetCollectionKey"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"json"}},"required":["id","name","required","type"],"additionalProperties":false}]}},"titleFieldId":{"type":"string"},"createdBy":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","user"]},"actorId":{"type":"string"},"clientName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","actorId"],"additionalProperties":false},"itemCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","displayName","singularName","description","kind","systemKey","fields","titleFieldId","createdBy","itemCount","createdAt","updatedAt"],"additionalProperties":false},"delivery":{"type":"object","properties":{"baseUrl":{"type":"string","description":"The site's public origin."},"listUrl":{"type":"string"},"itemUrl":{"type":"string","description":"Replace {slug} with an item's slug."},"schemaUrl":{"type":"string"},"fetchExample":{"type":"string","description":"Copy-paste JavaScript using fetch()."},"cors":{"type":"string","description":"How cross-origin access works and where to allow origins."}},"required":["baseUrl","listUrl","itemUrl","schemaUrl","fetchExample","cors"],"additionalProperties":false}},"required":["collection","delivery"],"additionalProperties":false},"example":{"collection":{"id":"coll_example01","key":"teachers","displayName":"Teachers","singularName":"Teacher","description":"Faculty shown on the About page.","kind":"custom","systemKey":null,"fields":[{"id":"name","name":"Name","type":"text","required":true,"max":80,"unique":true,"aiHint":"Full name as shown on the site."},{"id":"avatar","name":"Avatar","type":"image","required":false,"help":"Square portrait."},{"id":"subjects","name":"Subjects","type":"multi_select","required":true,"options":[{"id":"math","label":"Math"},{"id":"english","label":"English"},{"id":"physics","label":"Physics"}]},{"id":"bio","name":"Bio","type":"rich_text","required":false,"max":2000},{"id":"website","name":"Personal website","type":"url","required":false},{"id":"course","name":"Main course","type":"reference","required":false,"targetCollectionKey":"courses"}],"titleFieldId":"name","createdBy":{"kind":"agent","actorId":"user_example01","clientName":"Cursor"},"itemCount":0,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"},"delivery":{"baseUrl":"https://sunny-bakery.kanorio.com","listUrl":"https://sunny-bakery.kanorio.com/api/v1/collections/teachers/items","itemUrl":"https://sunny-bakery.kanorio.com/api/v1/collections/teachers/items/{slug}","schemaUrl":"https://sunny-bakery.kanorio.com/api/v1/collections","fetchExample":"const res = await fetch(\"https://sunny-bakery.kanorio.com/api/v1/collections/teachers/items?limit=20&sort=-publishedAt\");\nconst { items, nextCursor } = await res.json();","cors":"Same-origin requests need no setup. Other origins must be added with site.update_allowed_origins; localhost is always allowed."}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"collections.create","x-kanorio-mcp-tool":"collections_create","x-kanorio-required-scope":"collections:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/collections/{key}":{"get":{"operationId":"collections_get","summary":"collections.get","description":"Get one collection's schema (fields, constraints, aiHint) plus its Content Delivery API endpoints. Errors: FORBIDDEN, COLLECTION_NOT_FOUND.","tags":["collections"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"displayName":{"type":"string"},"singularName":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string","enum":["custom","system"],"description":"system collections (blog) have reserved fields that cannot be removed or retyped."},"systemKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"text"},"min":{"type":"integer","minimum":0,"maximum":20000},"max":{"type":"integer","minimum":1,"maximum":20000},"pattern":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"rich_text"},"max":{"type":"integer","minimum":1,"maximum":50000}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"email"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"phone"},"defaultCountry":{"type":"string","minLength":2,"maxLength":2}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"url"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"video_url"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"number"},"integer":{"type":"boolean"},"min":{"type":"number"},"max":{"type":"number"},"default":{"type":"number"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"boolean"},"default":{"type":"boolean"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"date"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"datetime"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"],"additionalProperties":false}},"default":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","required","type","options"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"],"additionalProperties":false}},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50},"default":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}}},"required":["id","name","required","type","options"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"color"},"default":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"image"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"gallery"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"file"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","required","type","targetCollectionKey"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","required","type","targetCollectionKey"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"json"}},"required":["id","name","required","type"],"additionalProperties":false}]}},"titleFieldId":{"type":"string"},"createdBy":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","user"]},"actorId":{"type":"string"},"clientName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","actorId"],"additionalProperties":false},"itemCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","displayName","singularName","description","kind","systemKey","fields","titleFieldId","createdBy","itemCount","createdAt","updatedAt"],"additionalProperties":false},"delivery":{"type":"object","properties":{"baseUrl":{"type":"string","description":"The site's public origin."},"listUrl":{"type":"string"},"itemUrl":{"type":"string","description":"Replace {slug} with an item's slug."},"schemaUrl":{"type":"string"},"fetchExample":{"type":"string","description":"Copy-paste JavaScript using fetch()."},"cors":{"type":"string","description":"How cross-origin access works and where to allow origins."}},"required":["baseUrl","listUrl","itemUrl","schemaUrl","fetchExample","cors"],"additionalProperties":false}},"required":["collection","delivery"],"additionalProperties":false},"example":{"collection":{"id":"coll_example01","key":"teachers","displayName":"Teachers","singularName":"Teacher","description":"Faculty shown on the About page.","kind":"custom","systemKey":null,"fields":[{"id":"name","name":"Name","type":"text","required":true,"max":80,"unique":true,"aiHint":"Full name as shown on the site."},{"id":"avatar","name":"Avatar","type":"image","required":false,"help":"Square portrait."},{"id":"subjects","name":"Subjects","type":"multi_select","required":true,"options":[{"id":"math","label":"Math"},{"id":"english","label":"English"},{"id":"physics","label":"Physics"}]},{"id":"bio","name":"Bio","type":"rich_text","required":false,"max":2000},{"id":"website","name":"Personal website","type":"url","required":false},{"id":"course","name":"Main course","type":"reference","required":false,"targetCollectionKey":"courses"}],"titleFieldId":"name","createdBy":{"kind":"agent","actorId":"user_example01","clientName":"Cursor"},"itemCount":3,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"},"delivery":{"baseUrl":"https://sunny-bakery.kanorio.com","listUrl":"https://sunny-bakery.kanorio.com/api/v1/collections/teachers/items","itemUrl":"https://sunny-bakery.kanorio.com/api/v1/collections/teachers/items/{slug}","schemaUrl":"https://sunny-bakery.kanorio.com/api/v1/collections","fetchExample":"const res = await fetch(\"https://sunny-bakery.kanorio.com/api/v1/collections/teachers/items?limit=20&sort=-publishedAt\");\nconst { items, nextCursor } = await res.json();","cors":"Same-origin requests need no setup. Other origins must be added with site.update_allowed_origins; localhost is always allowed."}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"collections.get","x-kanorio-mcp-tool":"collections_get","x-kanorio-required-scope":"collections:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"patch":{"operationId":"collections_update","summary":"collections.update","description":"Change a collection's name, description, titleFieldId or fields. fields replaces the whole ordered list: read it with collections.get, edit, send it back. Allowed immediately: add fields, rename, change help/aiHint, add options, relax constraints, remove custom fields (data is ignored, cleaned on next write). Type changes only along compatible paths (e.g. text→rich_text, select→multi_select, reference→multi_reference, image→gallery); otherwise add a new field, migrate, remove the old one. Tightened constraints are checked against existing items first. System collections (blog): reserved fields cannot be removed or retyped. Errors: FORBIDDEN, COLLECTION_NOT_FOUND, VALIDATION (details.issues), SCHEMA_CHANGE_REJECTED (details.schemaIssues).","tags":["collections"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":80},"singularName":{"type":"string","minLength":1,"maxLength":80},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"fields":{"minItems":1,"maxItems":50,"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"text"},"min":{"type":"integer","minimum":0,"maximum":20000},"max":{"type":"integer","minimum":1,"maximum":20000},"pattern":{"type":"string"},"default":{"type":"string"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"rich_text"},"max":{"type":"integer","minimum":1,"maximum":50000}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"email"},"default":{"type":"string"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"phone"},"defaultCountry":{"type":"string","minLength":2,"maxLength":2}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"url"},"default":{"type":"string"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"video_url"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"number"},"integer":{"type":"boolean"},"min":{"type":"number"},"max":{"type":"number"},"default":{"type":"number"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"boolean"},"default":{"type":"boolean"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"date"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"datetime"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"]}},"default":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","type","options"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"]}},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50},"default":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}}},"required":["id","name","type","options"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"color"},"default":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"image"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"gallery"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"file"}},"required":["id","name","type"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","type","targetCollectionKey"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","type","targetCollectionKey"]},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"json"}},"required":["id","name","type"]}]}},"titleFieldId":{"type":"string"}}},"example":{"description":"Faculty and guest lecturers.","fields":[{"id":"name","name":"Name","type":"text","required":true,"max":80,"unique":true,"aiHint":"Full name as shown on the site."},{"id":"avatar","name":"Avatar","type":"image","required":false,"help":"Square portrait."},{"id":"subjects","name":"Subjects","type":"multi_select","required":true,"options":[{"id":"math","label":"Math"},{"id":"english","label":"English"},{"id":"physics","label":"Physics"}]},{"id":"bio","name":"Bio","type":"rich_text","required":false,"max":2000},{"id":"website","name":"Personal website","type":"url","required":false},{"id":"course","name":"Main course","type":"reference","required":false,"targetCollectionKey":"courses"},{"id":"years","name":"Years of experience","type":"number","required":false,"integer":true,"min":0}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"displayName":{"type":"string"},"singularName":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string","enum":["custom","system"],"description":"system collections (blog) have reserved fields that cannot be removed or retyped."},"systemKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"text"},"min":{"type":"integer","minimum":0,"maximum":20000},"max":{"type":"integer","minimum":1,"maximum":20000},"pattern":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"rich_text"},"max":{"type":"integer","minimum":1,"maximum":50000}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"email"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"phone"},"defaultCountry":{"type":"string","minLength":2,"maxLength":2}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"url"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"video_url"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"unique":{"type":"boolean"},"type":{"type":"string","const":"number"},"integer":{"type":"boolean"},"min":{"type":"number"},"max":{"type":"number"},"default":{"type":"number"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"boolean"},"default":{"type":"boolean"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"date"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"datetime"},"min":{"type":"string"},"max":{"type":"string"},"default":{"type":"string"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"],"additionalProperties":false}},"default":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","required","type","options"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_select"},"options":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"label":{"type":"string","minLength":1,"maxLength":80},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","label"],"additionalProperties":false}},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50},"default":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}}},"required":["id","name","required","type","options"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"color"},"default":{"type":"string","pattern":"^#[0-9a-f]{6}$"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"image"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"gallery"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"file"}},"required":["id","name","required","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"}},"required":["id","name","required","type","targetCollectionKey"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"multi_reference"},"targetCollectionKey":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"min":{"type":"integer","minimum":0,"maximum":50},"max":{"type":"integer","minimum":1,"maximum":50}},"required":["id","name","required","type","targetCollectionKey"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"name":{"type":"string","minLength":1,"maxLength":80},"required":{"default":false,"type":"boolean"},"help":{"type":"string","maxLength":300},"aiHint":{"type":"string","maxLength":500},"system":{"type":"boolean"},"indexed":{"type":"boolean"},"type":{"type":"string","const":"json"}},"required":["id","name","required","type"],"additionalProperties":false}]}},"titleFieldId":{"type":"string"},"createdBy":{"type":"object","properties":{"kind":{"type":"string","enum":["agent","user"]},"actorId":{"type":"string"},"clientName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","actorId"],"additionalProperties":false},"itemCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","displayName","singularName","description","kind","systemKey","fields","titleFieldId","createdBy","itemCount","createdAt","updatedAt"],"additionalProperties":false}},"required":["collection"],"additionalProperties":false},"example":{"collection":{"id":"coll_example01","key":"teachers","displayName":"Teachers","singularName":"Teacher","description":"Faculty and guest lecturers.","kind":"custom","systemKey":null,"fields":[{"id":"name","name":"Name","type":"text","required":true,"max":80,"unique":true,"aiHint":"Full name as shown on the site."},{"id":"avatar","name":"Avatar","type":"image","required":false,"help":"Square portrait."},{"id":"subjects","name":"Subjects","type":"multi_select","required":true,"options":[{"id":"math","label":"Math"},{"id":"english","label":"English"},{"id":"physics","label":"Physics"}]},{"id":"bio","name":"Bio","type":"rich_text","required":false,"max":2000},{"id":"website","name":"Personal website","type":"url","required":false},{"id":"course","name":"Main course","type":"reference","required":false,"targetCollectionKey":"courses"}],"titleFieldId":"name","createdBy":{"kind":"agent","actorId":"user_example01","clientName":"Cursor"},"itemCount":3,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"collections.update","x-kanorio-mcp-tool":"collections_update","x-kanorio-required-scope":"collections:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"},"delete":{"operationId":"collections_delete","summary":"collections.delete","description":"Delete a custom collection and ALL its items. Irreversible. confirmKey must equal key. Refused while another collection references it, and for system collections. Not included in any OAuth scope preset; a PAT must grant collections:manage explicitly. Errors: FORBIDDEN, COLLECTION_NOT_FOUND, CONFIRM_REQUIRED, REFERENCED (details.referencedBy), SYSTEM_COLLECTION.","tags":["collections"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}},{"name":"confirmKey","in":"query","required":true,"description":"Must equal key.","schema":{"type":"string","description":"Must equal key."},"example":"teachers"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deletedItems":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["deletedItems"],"additionalProperties":false},"example":{"deletedItems":3}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"collections.delete","x-kanorio-mcp-tool":"collections_delete","x-kanorio-required-scope":"collections:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/collections/{key}/items":{"get":{"operationId":"items_list","summary":"items.list","description":"List or query items with the same filter/sort DSL the Content Delivery API uses: AND of up to 10 conditions, 3 sort fields, cursor or offset paging. source=draft (default) includes unpublished edits; source=published returns only what the public API serves. Over REST (GET) pass filter and sort as JSON strings, e.g. ?filter={\"subjects\":{\"has\":\"math\"}}&sort=-publishedAt. Errors: FORBIDDEN, COLLECTION_NOT_FOUND, VALIDATION (details.queryIssues: unknown field, op not allowed for the type, invalid value).","tags":["items"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["draft","published"]},"example":"published"},{"name":"status","in":"query","required":false,"description":"Only with source=draft.","schema":{"description":"Only with source=draft.","type":"string","enum":["draft","published","changed"]}},{"name":"filter","in":"query","required":false,"schema":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]},{"type":"object","propertyNames":{"type":"string","enum":["eq","ne","in","nin","gt","gte","lt","lte","contains","ncontains","has","has_slug","eq_slug","exists"]},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}]}}]},"description":"AND of conditions keyed by fieldId or slug/publishedAt/createdAt/updatedAt. Value = eq; or { op: value } with ops eq ne in nin gt gte lt lte contains ncontains has has_slug eq_slug exists (allowed ops depend on the field type). Example: { \"subjects\": { \"has\": \"math\" }, \"categories\": { \"has_slug\": \"news\" }, \"years\": { \"gte\": 5 } }."},{"type":"string"}]},"example":"{\"subjects\":{\"has\":\"math\"},\"name\":{\"contains\":\"chen\"}}"},{"name":"sort","in":"query","required":false,"description":"Array of { field, direction } or a comma-separated shorthand, e.g. \"-publishedAt,name\".","schema":{"description":"Array of { field, direction } or a comma-separated shorthand, e.g. \"-publishedAt,name\".","anyOf":[{"type":"string","maxLength":200},{"maxItems":3,"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field"]},"description":"Up to 3 fields; rich_text, json, image, gallery, file and multi_* fields cannot be sorted."}]},"example":"-publishedAt,name"},{"name":"limit","in":"query","required":false,"description":"Page size (1-100). Defaults vary per capability.","schema":{"description":"Page size (1-100). Defaults vary per capability.","type":"integer","minimum":1,"maximum":100},"example":20},{"name":"offset","in":"query","required":false,"description":"Number of items to skip.","schema":{"description":"Number of items to skip.","type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Only return these fieldIds.","schema":{"description":"Only return these fieldIds.","type":"array","items":{"type":"string"}},"style":"form","explode":false},{"name":"expand","in":"query","required":false,"description":"Reference fields to expand one level (id, slug, title).","schema":{"description":"Reference fields to expand one level (id, slug, title).","type":"array","items":{"type":"string"}},"style":"form","explode":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"collectionKey":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","changed"],"description":"changed = published, but the draft has unpublished edits."},"title":{"type":"string"},"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Draft values (what the dashboard shows)."},"publishedFieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"What the Content Delivery API serves; null when never published or unpublished."},"publishedSlug":{"anyOf":[{"type":"string"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","collectionKey","slug","status","title","fieldData","publishedFieldData","publishedSlug","publishedAt","sortOrder","createdAt","updatedAt"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","total","nextCursor","limit","offset"],"additionalProperties":false},"example":{"items":[{"id":"item_example01","collectionKey":"teachers","slug":"amy-chen","status":"published","title":"Amy Chen","fieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedFieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedSlug":"amy-chen","publishedAt":"2026-10-06T08:00:00.000Z","sortOrder":0,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}],"total":1,"nextCursor":null,"limit":20,"offset":0}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"items.list","x-kanorio-mcp-tool":"items_list","x-kanorio-required-scope":"collections:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"items_create","summary":"items.create","description":"Create one item. Values are validated against the collection schema; fix the listed fieldIds on VALIDATION. slug is generated from the title field when omitted. Errors: FORBIDDEN, COLLECTION_NOT_FOUND, VALIDATION (details.issues: fieldId, code, message, example), UNIQUE_CONFLICT, SLUG_TAKEN, PLAN_ITEM_LIMIT_REACHED (details.quota), COLLECTION_ITEM_LIMIT_REACHED, SYSTEM_COLLECTION (blog collections are read-only here; use blog.*).","tags":["items"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Field values keyed by fieldId. Call collections.get first to read the schema (types, required, options, aiHint). Image/gallery/file fields take assetIds from media.upload; reference fields take item ids from the target collection."},"slug":{"type":"string","maxLength":100},"publish":{"description":"Default true: the write is published immediately. false keeps it as a draft (status draft or changed).","type":"boolean"}},"required":["fieldData"]},"example":{"fieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publish":true}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"collectionKey":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","changed"],"description":"changed = published, but the draft has unpublished edits."},"title":{"type":"string"},"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Draft values (what the dashboard shows)."},"publishedFieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"What the Content Delivery API serves; null when never published or unpublished."},"publishedSlug":{"anyOf":[{"type":"string"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","collectionKey","slug","status","title","fieldData","publishedFieldData","publishedSlug","publishedAt","sortOrder","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"item_example01","collectionKey":"teachers","slug":"amy-chen","status":"published","title":"Amy Chen","fieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedFieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedSlug":"amy-chen","publishedAt":"2026-10-06T08:00:00.000Z","sortOrder":0,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"items.create","x-kanorio-mcp-tool":"items_create","x-kanorio-required-scope":"collections:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/collections/{key}/items/bulk":{"post":{"operationId":"items_bulk_create","summary":"items.bulk_create","description":"Create up to 200 items in one transaction (all or nothing). On failure nothing is written and failed[] lists each bad entry by index with its issues. Errors: FORBIDDEN, COLLECTION_NOT_FOUND, VALIDATION, UNIQUE_CONFLICT, SLUG_TAKEN, PLAN_ITEM_LIMIT_REACHED (details.quota), COLLECTION_ITEM_LIMIT_REACHED, SYSTEM_COLLECTION.","tags":["items"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Field values keyed by fieldId. Call collections.get first to read the schema (types, required, options, aiHint). Image/gallery/file fields take assetIds from media.upload; reference fields take item ids from the target collection."},"slug":{"type":"string","maxLength":100}},"required":["fieldData"]}},"publish":{"description":"Default true: the write is published immediately. false keeps it as a draft (status draft or changed).","type":"boolean"}},"required":["items"]},"example":{"items":[{"fieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"}},{"fieldData":{"name":"Ben Lin","subjects":["english"]}}],"publish":true}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"collectionKey":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","changed"],"description":"changed = published, but the draft has unpublished edits."},"title":{"type":"string"},"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Draft values (what the dashboard shows)."},"publishedFieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"What the Content Delivery API serves; null when never published or unpublished."},"publishedSlug":{"anyOf":[{"type":"string"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","collectionKey","slug","status","title","fieldData","publishedFieldData","publishedSlug","publishedAt","sortOrder","createdAt","updatedAt"],"additionalProperties":false}},"failed":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["code","message"],"additionalProperties":false}},"required":["index","error"],"additionalProperties":false}}},"required":["created","failed"],"additionalProperties":false},"example":{"created":[{"id":"item_example01","collectionKey":"teachers","slug":"amy-chen","status":"published","title":"Amy Chen","fieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedFieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedSlug":"amy-chen","publishedAt":"2026-10-06T08:00:00.000Z","sortOrder":0,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"},{"id":"item_example03","collectionKey":"teachers","slug":"ben-lin","status":"published","title":"Ben Lin","fieldData":{"name":"Ben Lin","subjects":["english"]},"publishedFieldData":{"name":"Ben Lin","subjects":["english"]},"publishedSlug":"ben-lin","publishedAt":"2026-10-06T08:00:00.000Z","sortOrder":1,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}],"failed":[]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"items.bulk_create","x-kanorio-mcp-tool":"items_bulk_create","x-kanorio-required-scope":"collections:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"},"patch":{"operationId":"items_bulk_update","summary":"items.bulk_update","description":"Update up to 200 items in one transaction (all or nothing); each entry is a partial update by itemId. Errors: FORBIDDEN, COLLECTION_NOT_FOUND, ITEM_NOT_FOUND, VALIDATION, UNIQUE_CONFLICT, SLUG_TAKEN, SYSTEM_COLLECTION.","tags":["items"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","minLength":1,"description":"Item id. Get it from items.list."},"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Field values keyed by fieldId. Call collections.get first to read the schema (types, required, options, aiHint). Image/gallery/file fields take assetIds from media.upload; reference fields take item ids from the target collection."},"slug":{"type":"string","maxLength":100}},"required":["itemId","fieldData"]}},"publish":{"description":"Default true: the write is published immediately. false keeps it as a draft (status draft or changed).","type":"boolean"}},"required":["items"]},"example":{"items":[{"itemId":"item_example01","fieldData":{"subjects":["math"]}}],"publish":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"collectionKey":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","changed"],"description":"changed = published, but the draft has unpublished edits."},"title":{"type":"string"},"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Draft values (what the dashboard shows)."},"publishedFieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"What the Content Delivery API serves; null when never published or unpublished."},"publishedSlug":{"anyOf":[{"type":"string"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","collectionKey","slug","status","title","fieldData","publishedFieldData","publishedSlug","publishedAt","sortOrder","createdAt","updatedAt"],"additionalProperties":false}},"failed":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["code","message"],"additionalProperties":false}},"required":["index","error"],"additionalProperties":false}}},"required":["updated","failed"],"additionalProperties":false},"example":{"updated":[{"id":"item_example01","collectionKey":"teachers","slug":"amy-chen","status":"published","title":"Amy Chen","fieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedFieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedSlug":"amy-chen","publishedAt":"2026-10-06T08:00:00.000Z","sortOrder":0,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}],"failed":[]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"items.bulk_update","x-kanorio-mcp-tool":"items_bulk_update","x-kanorio-required-scope":"collections:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/collections/{key}/items/publish":{"post":{"operationId":"items_publish","summary":"items.publish","description":"Publish up to 200 items: copies each draft to the public copy. Returns the updated items and ids that were not found. Errors: FORBIDDEN, COLLECTION_NOT_FOUND, VALIDATION, SYSTEM_COLLECTION.","tags":["items"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"string","minLength":1,"description":"Item id. Get it from items.list."}}},"required":["itemIds"]},"example":{"itemIds":["item_example01"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"collectionKey":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","changed"],"description":"changed = published, but the draft has unpublished edits."},"title":{"type":"string"},"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Draft values (what the dashboard shows)."},"publishedFieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"What the Content Delivery API serves; null when never published or unpublished."},"publishedSlug":{"anyOf":[{"type":"string"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","collectionKey","slug","status","title","fieldData","publishedFieldData","publishedSlug","publishedAt","sortOrder","createdAt","updatedAt"],"additionalProperties":false}},"missing":{"type":"array","items":{"type":"string"}}},"required":["items","missing"],"additionalProperties":false},"example":{"items":[{"id":"item_example01","collectionKey":"teachers","slug":"amy-chen","status":"published","title":"Amy Chen","fieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedFieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedSlug":"amy-chen","publishedAt":"2026-10-06T08:00:00.000Z","sortOrder":0,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}],"missing":[]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"items.publish","x-kanorio-mcp-tool":"items_publish","x-kanorio-required-scope":"collections:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/collections/{key}/items/unpublish":{"post":{"operationId":"items_unpublish","summary":"items.unpublish","description":"Unpublish up to 200 items: removes them from the Content Delivery API; drafts are kept. Errors: FORBIDDEN, COLLECTION_NOT_FOUND, VALIDATION, SYSTEM_COLLECTION.","tags":["items"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"string","minLength":1,"description":"Item id. Get it from items.list."}}},"required":["itemIds"]},"example":{"itemIds":["item_example01"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"collectionKey":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","changed"],"description":"changed = published, but the draft has unpublished edits."},"title":{"type":"string"},"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Draft values (what the dashboard shows)."},"publishedFieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"What the Content Delivery API serves; null when never published or unpublished."},"publishedSlug":{"anyOf":[{"type":"string"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","collectionKey","slug","status","title","fieldData","publishedFieldData","publishedSlug","publishedAt","sortOrder","createdAt","updatedAt"],"additionalProperties":false}},"missing":{"type":"array","items":{"type":"string"}}},"required":["items","missing"],"additionalProperties":false},"example":{"items":[{"id":"item_example01","collectionKey":"teachers","slug":"amy-chen","status":"draft","title":"Amy Chen","fieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedFieldData":null,"publishedSlug":null,"publishedAt":null,"sortOrder":0,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}],"missing":[]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"items.unpublish","x-kanorio-mcp-tool":"items_unpublish","x-kanorio-required-scope":"collections:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/collections/{key}/items/{itemId}":{"get":{"operationId":"items_get","summary":"items.get","description":"Get one item by id or slug, with draft and published values. Errors: FORBIDDEN, COLLECTION_NOT_FOUND, ITEM_NOT_FOUND.","tags":["items"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"description":"Item id or slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"collectionKey":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","changed"],"description":"changed = published, but the draft has unpublished edits."},"title":{"type":"string"},"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Draft values (what the dashboard shows)."},"publishedFieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"What the Content Delivery API serves; null when never published or unpublished."},"publishedSlug":{"anyOf":[{"type":"string"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","collectionKey","slug","status","title","fieldData","publishedFieldData","publishedSlug","publishedAt","sortOrder","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"item_example01","collectionKey":"teachers","slug":"amy-chen","status":"published","title":"Amy Chen","fieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedFieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedSlug":"amy-chen","publishedAt":"2026-10-06T08:00:00.000Z","sortOrder":0,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"items.get","x-kanorio-mcp-tool":"items_get","x-kanorio-required-scope":"collections:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"patch":{"operationId":"items_update","summary":"items.update","description":"Partially update an item: only the fieldIds you send change; send null to clear a field. publish=false keeps the public copy unchanged (status becomes changed). Errors: FORBIDDEN, COLLECTION_NOT_FOUND, ITEM_NOT_FOUND, VALIDATION (details.issues: fieldId, code, message, example), UNIQUE_CONFLICT, SLUG_TAKEN, PLAN_ITEM_LIMIT_REACHED (details.quota), COLLECTION_ITEM_LIMIT_REACHED, SYSTEM_COLLECTION (blog collections are read-only here; use blog.*).","tags":["items"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"description":"Item id. Get it from items.list.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Field values keyed by fieldId. Call collections.get first to read the schema (types, required, options, aiHint). Image/gallery/file fields take assetIds from media.upload; reference fields take item ids from the target collection."},"slug":{"type":"string","maxLength":100},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"publish":{"description":"Default true: the write is published immediately. false keeps it as a draft (status draft or changed).","type":"boolean"}}},"example":{"fieldData":{"bio":"Updated bio, not yet published."},"publish":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"collectionKey":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","published","changed"],"description":"changed = published, but the draft has unpublished edits."},"title":{"type":"string"},"fieldData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Draft values (what the dashboard shows)."},"publishedFieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"What the Content Delivery API serves; null when never published or unpublished."},"publishedSlug":{"anyOf":[{"type":"string"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","collectionKey","slug","status","title","fieldData","publishedFieldData","publishedSlug","publishedAt","sortOrder","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"item_example01","collectionKey":"teachers","slug":"amy-chen","status":"changed","title":"Amy Chen","fieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Updated bio, not yet published.","website":"https://amychen.example.com","course":"item_example02"},"publishedFieldData":{"name":"Amy Chen","avatar":"asset_example01","subjects":["math","physics"],"bio":"Ten years of teaching high-school math.","website":"https://amychen.example.com","course":"item_example02"},"publishedSlug":"amy-chen","publishedAt":"2026-10-06T08:00:00.000Z","sortOrder":0,"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"items.update","x-kanorio-mcp-tool":"items_update","x-kanorio-required-scope":"collections:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"},"delete":{"operationId":"items_delete","summary":"items.delete","description":"Delete one item. Refused with REFERENCED (details.referencedBy) while other items reference it, unless force=true (readers then ignore the dangling id). Errors: FORBIDDEN, COLLECTION_NOT_FOUND, ITEM_NOT_FOUND, REFERENCED, SYSTEM_COLLECTION.","tags":["items"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Collection key (slug). Get it from collections.list.","schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"description":"Item id. Get it from items.list.","schema":{"type":"string"}},{"name":"force","in":"query","required":false,"schema":{"type":"boolean"},"example":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false},"example":{"id":"item_example01"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"items.delete","x-kanorio-mcp-tool":"items_delete","x-kanorio-required-scope":"collections:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/allowed-origins":{"get":{"operationId":"site_get_allowed_origins","summary":"site.get_allowed_origins","description":"List the origins allowed to call the Content Delivery API cross-origin (CORS allowlist). Same-origin and localhost need no entry. Errors: FORBIDDEN.","tags":["site"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"origins":{"type":"array","items":{"type":"string"}}},"required":["origins"],"additionalProperties":false},"example":{"origins":["https://app.example.com"]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"site.get_allowed_origins","x-kanorio-mcp-tool":"site_get_allowed_origins","x-kanorio-required-scope":"collections:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"put":{"operationId":"site_update_allowed_origins","summary":"site.update_allowed_origins","description":"Replace the CORS allowlist for the Content Delivery API (up to 20 https origins such as https://app.example.com; no paths or wildcards). Errors: FORBIDDEN, VALIDATION (details.issues).","tags":["site"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origins":{"maxItems":20,"type":"array","items":{"type":"string"}}},"required":["origins"]},"example":{"origins":["https://app.example.com","https://preview.example.com"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"origins":{"type":"array","items":{"type":"string"}}},"required":["origins"],"additionalProperties":false},"example":{"origins":["https://app.example.com","https://preview.example.com"]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"site.update_allowed_origins","x-kanorio-mcp-tool":"site_update_allowed_origins","x-kanorio-required-scope":"site:manage_settings","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/developer-settings":{"patch":{"operationId":"site_update_developer_settings","summary":"site.update_developer_settings","description":"Update headless developer settings for the website: enable headless mode (so the Content Delivery API and blog publishing work without publishing the hosted template site) and/or set the external storefront URL (so visitor traffic on the hosted site 302-redirects to your external frontend while /api/v1/*, /checkout and /account stay active). Pass null to externalStorefrontUrl to clear it. Returns the site's permanent systemHost (s-xxx.kanorio.com). Errors: FORBIDDEN, VALIDATION (details.issues).","tags":["site"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"headlessEnabled":{"type":"boolean"},"externalStorefrontUrl":{"anyOf":[{"type":"string","maxLength":253,"pattern":"^https:\\/\\/[^\\s/$.?#].[^\\s]*$"},{"type":"null"}]}}},"example":{"headlessEnabled":true,"externalStorefrontUrl":"https://www.sunnybakery.example"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"systemHandle":{"type":"string","description":"Permanent system handle (s-<base32>) assigned to the website."},"systemHost":{"type":"string","description":"System hostname (s-<base32>.kanorio.com) that always serves the Content Delivery API, /checkout and /account."},"headlessEnabled":{"type":"boolean","description":"When true, the Content Delivery API, form submissions and blog publishing work even while the hosted site is unpublished."},"externalStorefrontUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"External frontend origin (e.g. https://www.example.com). When set, hosted pages 302-redirect there while /api/v1/*, /checkout and /account stay served."},"allowedOrigins":{"type":"array","items":{"type":"string"}}},"required":["systemHandle","systemHost","headlessEnabled","externalStorefrontUrl","allowedOrigins"],"additionalProperties":false},"example":{"systemHandle":"s-k4m9x2p7q8w3","systemHost":"s-k4m9x2p7q8w3.kanorio.com","headlessEnabled":true,"externalStorefrontUrl":"https://www.sunnybakery.example","allowedOrigins":["https://www.sunnybakery.example"]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"site.update_developer_settings","x-kanorio-mcp-tool":"site_update_developer_settings","x-kanorio-required-scope":"site:manage_settings","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/preview-tokens":{"post":{"operationId":"site_create_preview_token","summary":"site.create_preview_token","description":"Mint a read-only headless preview token (knr_pv_…) for reading unpublished drafts via the Content Delivery API (send X-Kanorio-Preview: knr_pv_… or Authorization: Bearer knr_pv_… with ?preview=1). Unlike a PAT, a preview token can only read drafts of this website and expires automatically. Errors: FORBIDDEN, VALIDATION.","tags":["site"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"description":"Optional label (e.g. 'Next.js Draft Mode').","anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"ttlSeconds":{"description":"Token lifetime in seconds (60 to 2592000 = 30 days; default 604800 = 7 days).","type":"integer","minimum":60,"maximum":2592000}}},"example":{"label":"Next.js Draft Mode","ttlSeconds":604800}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string","description":"Read-only preview token (knr_pv_…). Shown only once."},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","token","label","createdAt","expiresAt"],"additionalProperties":false},"example":{"id":"pv_01j8x9k2","token":"knr_pv_cm9example0001website.1761652800.pv_01j8x9k2.sig_example","label":"Next.js Draft Mode","createdAt":"2026-10-06T08:00:00.000Z","expiresAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"site.create_preview_token","x-kanorio-mcp-tool":"site_create_preview_token","x-kanorio-required-scope":"site:manage_settings","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agentPublish (30/hour per token)"}},"/sites/{id}/webhooks":{"get":{"operationId":"webhooks_list","summary":"webhooks.list","description":"List the website's webhook endpoints, recent deliveries, plan quota (Pro: 3, Business: 10) and subscribable event keys. Errors: FORBIDDEN.","tags":["webhooks"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"addressPreview":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Masked destination URL (domain + last 4 chars of path)."},"status":{"type":"string","description":"ACTIVE or DISABLED."},"withinPlan":{"type":"boolean"},"autoDisabled":{"type":"boolean"},"createdAt":{"type":"string"},"subscribedEvents":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"null = subscribed to all events (including future events); array = only these event keys."},"filter":{"description":"Optional sub-event filter for collection keys or form IDs (Business plan).","anyOf":[{"type":"object","properties":{"collectionKeys":{"description":"Only deliver collections.* events for these collection keys.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"formIds":{"description":"Only deliver customers.form.submitted events for these form IDs.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},{"type":"null"}]},"recentDeliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"eventKey":{"type":"string"},"status":{"type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextRetryAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"statusCode":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationMs":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","eventKey","status","error","createdAt","attempts","nextRetryAt","statusCode","durationMs"],"additionalProperties":false}}},"required":["id","label","addressPreview","status","withinPlan","autoDisabled","createdAt","subscribedEvents","recentDeliveries"],"additionalProperties":false}},"subscribableEvents":{"type":"array","items":{"type":"string"}},"planAllowed":{"type":"boolean"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["webhooks","subscribableEvents","planAllowed","limit","remaining"],"additionalProperties":false},"example":{"webhooks":[{"id":"wh_example01","label":"Vercel ISR Revalidate","addressPreview":"https://www.sunnybakery.example/…date","status":"ACTIVE","withinPlan":true,"autoDisabled":false,"createdAt":"2026-10-01T02:30:00.000Z","subscribedEvents":["collections.item.published","collections.items.bulkChanged"],"filter":null,"recentDeliveries":[]}],"subscribableEvents":["collections.item.created","collections.item.updated","collections.item.published","collections.item.unpublished","collections.item.deleted","collections.items.bulkChanged","collections.schema.changed","content.site.published","content.page.published","content.page.updated","content.page.unpublished","content.page.deleted","customers.form.submitted"],"planAllowed":true,"limit":3,"remaining":2}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"webhooks.list","x-kanorio-mcp-tool":"webhooks_list","x-kanorio-required-scope":"site:integrations","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"webhooks_create","summary":"webhooks.create","description":"Create a webhook endpoint (public https URL). Returns the HMAC-SHA256 signingSecret (whsec_…) once — store it in your receiver's environment to verify X-Kanorio-Signature. Pass events (from webhooks.list subscribableEvents) to subscribe to specific events, or omit/null to subscribe to all events. Errors: FORBIDDEN, PLAN_REQUIRED, WEBHOOK_LIMIT_REACHED, DUPLICATE_WEBHOOK, VALIDATION.","tags":["webhooks"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"pattern":"^https:\\/\\/.+","description":"Public https endpoint URL."},"label":{"description":"Display label in the dashboard, e.g. 'Vercel ISR Revalidate'.","anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"events":{"description":"Event keys to subscribe to (e.g. ['collections.item.published', 'collections.items.bulkChanged']), or null/omit for all events.","anyOf":[{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},{"type":"null"}]},"filter":{"description":"Optional sub-event filter for collection keys or form IDs (Business plan).","anyOf":[{"type":"object","properties":{"collectionKeys":{"description":"Only deliver collections.* events for these collection keys.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"formIds":{"description":"Only deliver customers.form.submitted events for these form IDs.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}}}},{"type":"null"}]}},"required":["url"]},"example":{"url":"https://www.sunnybakery.example/api/revalidate","label":"Vercel ISR Revalidate","events":["collections.item.published","collections.items.bulkChanged"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"signingSecret":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"HMAC-SHA256 signing secret (whsec_…). Shown only on creation."},"subscribedEvents":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"filter":{"description":"Optional sub-event filter for collection keys or form IDs (Business plan).","anyOf":[{"type":"object","properties":{"collectionKeys":{"description":"Only deliver collections.* events for these collection keys.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"formIds":{"description":"Only deliver customers.form.submitted events for these form IDs.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},{"type":"null"}]}},"required":["id","signingSecret","subscribedEvents"],"additionalProperties":false},"example":{"id":"wh_example01","signingSecret":"whsec_example_signing_secret_01","subscribedEvents":["collections.item.published","collections.items.bulkChanged"],"filter":null}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"webhooks.create","x-kanorio-mcp-tool":"webhooks_create","x-kanorio-required-scope":"site:integrations","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/webhooks/{webhookId}/events":{"put":{"operationId":"webhooks_update_events","summary":"webhooks.update_events","description":"Replace the subscribed event list and optional filter (collectionKeys / formIds) of a webhook endpoint. Pass null for events to subscribe to all events (including future events). Filters require the Business plan. Errors: FORBIDDEN, WEBHOOK_NOT_FOUND, PLAN_REQUIRED, VALIDATION.","tags":["webhooks"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"webhookId","in":"path","required":true,"description":"Webhook destination id. Get it from webhooks.list.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"anyOf":[{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},{"type":"null"}],"description":"Subscribable event keys, or null for all events."},"filter":{"description":"Optional sub-event filter for collection keys or form IDs (Business plan).","anyOf":[{"type":"object","properties":{"collectionKeys":{"description":"Only deliver collections.* events for these collection keys.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"formIds":{"description":"Only deliver customers.form.submitted events for these form IDs.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}}}},{"type":"null"}]}},"required":["events"]},"example":{"events":["collections.item.published"],"filter":{"collectionKeys":["blog"]}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"subscribedEvents":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"filter":{"description":"Optional sub-event filter for collection keys or form IDs (Business plan).","anyOf":[{"type":"object","properties":{"collectionKeys":{"description":"Only deliver collections.* events for these collection keys.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"formIds":{"description":"Only deliver customers.form.submitted events for these form IDs.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},{"type":"null"}]}},"required":["id","subscribedEvents"],"additionalProperties":false},"example":{"id":"wh_example01","subscribedEvents":["collections.item.published"],"filter":{"collectionKeys":["blog"]}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"webhooks.update_events","x-kanorio-mcp-tool":"webhooks_update_events","x-kanorio-required-scope":"site:integrations","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/webhooks/{webhookId}":{"delete":{"operationId":"webhooks_delete","summary":"webhooks.delete","description":"Delete a webhook endpoint. Errors: FORBIDDEN, WEBHOOK_NOT_FOUND.","tags":["webhooks"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"webhookId","in":"path","required":true,"description":"Webhook destination id. Get it from webhooks.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false},"example":{"id":"wh_example01","deleted":true}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"webhooks.delete","x-kanorio-mcp-tool":"webhooks_delete","x-kanorio-required-scope":"site:integrations","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/webhooks/{webhookId}/test":{"post":{"operationId":"webhooks_test","summary":"webhooks.test","description":"Send a one-off team.test ping to a webhook endpoint and return the HTTP status and latency (does not count toward auto-disable failures). Errors: FORBIDDEN, WEBHOOK_NOT_FOUND.","tags":["webhooks"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"webhookId","in":"path","required":true,"description":"Webhook destination id. Get it from webhooks.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"success":{"type":"boolean"},"status":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","success","status","durationMs","error"],"additionalProperties":false},"example":{"id":"wh_example01","success":true,"status":200,"durationMs":142,"error":null}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"webhooks.test","x-kanorio-mcp-tool":"webhooks_test","x-kanorio-required-scope":"site:integrations","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/forms":{"get":{"operationId":"forms_list","summary":"forms.list","description":"List this website's online forms with status, availability and submission counts. Errors: FORBIDDEN.","tags":["forms"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"forms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"availability":{"type":"string","description":"open, paused, closed_by_schedule, full, ... (see FormAvailability)."},"hasIdentity":{"type":"boolean","description":"false = anonymous form (no email/phone field); submissions do not create contacts."},"fieldCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"submissionCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Non-spam submissions."},"unreadCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"updatedAt":{"type":"string"}},"required":["id","name","status","availability","hasIdentity","fieldCount","submissionCount","unreadCount","updatedAt"],"additionalProperties":false}}},"required":["forms"],"additionalProperties":false},"example":{"forms":[{"id":"form_example01","name":"Pre-order form","status":"PUBLISHED","availability":"OPEN","hasIdentity":true,"fieldCount":4,"submissionCount":12,"unreadCount":2,"updatedAt":"2026-10-01T02:30:00.000Z"}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"forms.list","x-kanorio-mcp-tool":"forms_list","x-kanorio-required-scope":"marketing:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/forms/{formId}":{"get":{"operationId":"forms_get","summary":"forms.get","description":"Get one form including its field definitions and settings (read-only; forms are edited in the console). Errors: FORBIDDEN, FORM_NOT_FOUND.","tags":["forms"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"formId","in":"path","required":true,"description":"Form id. Get it from forms.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"availability":{"type":"string","description":"open, paused, closed_by_schedule, full, ... (see FormAvailability)."},"fields":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Form field definitions (id, type, label, required, options, contactMapping...)."},"settings":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"replyEmailEnabled":{"type":"boolean"},"submissionCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","description","status","availability","fields","settings","replyEmailEnabled","submissionCount","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"form_example01","name":"Pre-order form","description":"Leave your details and we'll confirm your order by email.","status":"PUBLISHED","availability":"OPEN","fields":[{"id":"name","type":"text","label":"Name","required":true},{"id":"email","type":"email","label":"Email","required":true},{"id":"message","type":"textarea","label":"Message","required":false}],"settings":{"successMessage":"Thanks! We'll get back to you shortly."},"replyEmailEnabled":true,"submissionCount":12,"createdAt":"2026-08-12T03:20:00.000Z","updatedAt":"2026-10-01T02:30:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"forms.get","x-kanorio-mcp-tool":"forms_get","x-kanorio-required-scope":"marketing:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/forms/{formId}/submissions":{"get":{"operationId":"submissions_list","summary":"submissions.list","description":"List submissions of one form, newest first, with answers keyed by field id. Filter by status, full-text query and recent days. Attachments are returned as metadata only; downloading files and exporting CSV are not available to agents. Errors: FORBIDDEN, FORM_NOT_FOUND.","tags":["submissions"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"formId","in":"path","required":true,"description":"Form id. Get it from forms.list.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"description":"1-based page number.","type":"integer","minimum":1,"maximum":10000},"example":1},{"name":"pageSize","in":"query","required":false,"description":"10-100; defaults to 50.","schema":{"description":"10-100; defaults to 50.","type":"integer","minimum":1,"maximum":100},"example":20},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ALL","NEW","READ","SPAM","ARCHIVED"]}},{"name":"q","in":"query","required":false,"description":"Full-text search in answers.","schema":{"description":"Full-text search in answers.","type":"string","maxLength":100}},{"name":"days","in":"query","required":false,"description":"Only submissions from the last N days in the website's timezone; one of 1, 7, 30, 90.","schema":{"description":"Only submissions from the last N days in the website's timezone; one of 1, 7, 30, 90.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"submissions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","description":"NEW, READ, SPAM or ARCHIVED."},"submittedAt":{"type":"string"},"contactId":{"anyOf":[{"type":"string"},{"type":"null"}]},"display":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name, else email, else phone; null for anonymous forms."},"answers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Keyed by field id; file fields hold attachment ids (see attachments)."}},"required":["id","status","submittedAt","contactId","display","answers"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pageSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attachments":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"id":{"type":"string"},"fileName":{"type":"string"},"mimeType":{"type":"string"},"fileSize":{"type":"number"}},"required":["id","fileName","mimeType","fileSize"],"additionalProperties":false}}},"required":["submissions","total","page","pageSize","attachments"],"additionalProperties":false},"example":{"submissions":[{"id":"sub_example01","status":"NEW","submittedAt":"2026-10-06T08:00:00.000Z","contactId":"contact_example01","display":"Alex Chen","answers":{"name":"Alex Chen","email":"customer@example.com","message":"I'd like to pre-order a birthday cake for Saturday."}}],"total":1,"page":1,"pageSize":20,"attachments":{}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"submissions.list","x-kanorio-mcp-tool":"submissions_list","x-kanorio-required-scope":"marketing:view","x-kanorio-read-only":true,"x-kanorio-untrusted-content":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/forms/{formId}/submissions/{submissionId}":{"get":{"operationId":"submissions_get","summary":"submissions.get","description":"Get one submission of a form with its answers and attachment metadata. Errors: FORBIDDEN, SUBMISSION_NOT_FOUND.","tags":["submissions"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"formId","in":"path","required":true,"description":"Form id. Get it from forms.list.","schema":{"type":"string"}},{"name":"submissionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"submission":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","description":"NEW, READ, SPAM or ARCHIVED."},"submittedAt":{"type":"string"},"contactId":{"anyOf":[{"type":"string"},{"type":"null"}]},"display":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name, else email, else phone; null for anonymous forms."},"answers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Keyed by field id; file fields hold attachment ids (see attachments)."}},"required":["id","status","submittedAt","contactId","display","answers"],"additionalProperties":false},"attachments":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"id":{"type":"string"},"fileName":{"type":"string"},"mimeType":{"type":"string"},"fileSize":{"type":"number"}},"required":["id","fileName","mimeType","fileSize"],"additionalProperties":false}}},"required":["submission","attachments"],"additionalProperties":false},"example":{"submission":{"id":"sub_example01","status":"NEW","submittedAt":"2026-10-06T08:00:00.000Z","contactId":"contact_example01","display":"Alex Chen","answers":{"name":"Alex Chen","email":"customer@example.com","message":"I'd like to pre-order a birthday cake for Saturday."}},"attachments":{}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"submissions.get","x-kanorio-mcp-tool":"submissions_get","x-kanorio-required-scope":"marketing:view","x-kanorio-read-only":true,"x-kanorio-untrusted-content":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/contacts":{"get":{"operationId":"contacts_list","summary":"contacts.list","description":"List contacts (50 per page) with email marketing status, tags and purchase summary. Filter by status, source, buyers only, or search on email/name/phone; sort by RECENT, SPENT or LAST_ORDER. Errors: FORBIDDEN.","tags":["contacts"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"description":"1-based page number.","type":"integer","minimum":1,"maximum":10000},"example":1},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ALL","NEVER_SUBSCRIBED","PENDING","SUBSCRIBED","UNSUBSCRIBED","BOUNCED","COMPLAINED"]}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["ALL","CHECKOUT","ORDER","IMPORT","FORM","MANUAL","ADMIN"]}},{"name":"buyer","in":"query","required":false,"description":"BUYERS = has at least one paid order.","schema":{"description":"BUYERS = has at least one paid order.","type":"string","enum":["ALL","BUYERS"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["RECENT","SPENT","LAST_ORDER"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"E.164."},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"emailStatus":{"type":"string","description":"Email marketing consent: NEVER_SUBSCRIBED, PENDING, SUBSCRIBED, UNSUBSCRIBED, BOUNCED, COMPLAINED."},"source":{"type":"string"},"createdAt":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"customer":{"anyOf":[{"type":"object","properties":{"ordersCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalSpent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units in the website currency (orders in other currencies are not included)."},"lastOrderAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ordersCount","totalSpent","lastOrderAt"],"additionalProperties":false},{"type":"null"}],"description":"EC purchase summary; null when the contact never bought anything."}},"required":["id","email","phone","name","emailStatus","source","createdAt","tags","customer"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pageSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["contacts","total","page","pageSize"],"additionalProperties":false},"example":{"contacts":[{"id":"contact_example01","email":"customer@example.com","phone":"+886912345678","name":"Alex Chen","emailStatus":"SUBSCRIBED","source":"FORM","createdAt":"2026-10-01T02:30:00.000Z","tags":["VIP","cake-order"],"customer":{"ordersCount":3,"totalSpent":2640,"lastOrderAt":"2026-10-06T08:00:00.000Z"}}],"total":1,"page":1,"pageSize":20}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"contacts.list","x-kanorio-mcp-tool":"contacts_list","x-kanorio-required-scope":"customers:view","x-kanorio-read-only":true,"x-kanorio-untrusted-content":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"contacts_add","summary":"contacts.add","description":"Add one contact by email (source MANUAL). Only set marketingConsent=true when the person has explicitly agreed to receive marketing email; otherwise the contact is created without consent. Errors: FORBIDDEN, DUPLICATE (email already exists), SUPPRESSED (address is blocked), INVALID_EMAIL, INVALID_PHONE.","tags":["contacts"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","minLength":3,"maxLength":320},"name":{"type":"string","maxLength":120},"phone":{"description":"Any common format; normalized to E.164 using the store's country.","type":"string","maxLength":32},"tags":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":50}},"note":{"type":"string","maxLength":2000},"marketingConsent":{"description":"Defaults to false.","type":"boolean"}},"required":["email"]},"example":{"email":"customer@example.com","name":"Alex Chen","tags":["cake-order"],"marketingConsent":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string"}},"required":["contactId"],"additionalProperties":false},"example":{"contactId":"contact_example01"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"contacts.add","x-kanorio-mcp-tool":"contacts_add","x-kanorio-required-scope":"customers:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/contacts/{contactId}":{"get":{"operationId":"contacts_get","summary":"contacts.get","description":"Get one contact with consent state, note, custom profile attributes, purchase summary with recent orders, and the last 50 timeline events/messages. Errors: FORBIDDEN, CONTACT_NOT_FOUND.","tags":["contacts"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"contactId","in":"path","required":true,"description":"Contact id. Get it from contacts.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"E.164."},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"emailStatus":{"type":"string","description":"Email marketing consent: NEVER_SUBSCRIBED, PENDING, SUBSCRIBED, UNSUBSCRIBED, BOUNCED, COMPLAINED."},"source":{"type":"string"},"createdAt":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"customer":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"ordersCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalSpent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lastOrderAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"acceptsMarketing":{"type":"boolean"},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"recentOrders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orderNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"status":{"type":"string"},"paidAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currency":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","orderNumber","status","paidAmount","currency","createdAt"],"additionalProperties":false}}},"required":["id","ordersCount","totalSpent","lastOrderAt","acceptsMarketing","country","recentOrders"],"additionalProperties":false},{"type":"null"}]},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"emailConsentAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"emailUnsubscribedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"note":{"type":"string"},"suppressed":{"type":"boolean","description":"On the tenant suppression list (bounce/complaint/manual block)."},"profile":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"}},"required":["key","label","value"],"additionalProperties":false},"description":"Custom attributes collected via forms."},"consentLogs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string"},"action":{"type":"string"},"source":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","channel","action","source","createdAt"],"additionalProperties":false}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"occurredAt":{"type":"string"},"payload":{}},"required":["id","type","occurredAt","payload"],"additionalProperties":false}},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string"},"kind":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"at":{"type":"string"}},"required":["id","channel","kind","type","status","at"],"additionalProperties":false}}},"required":["id","email","phone","name","emailStatus","source","createdAt","tags","customer","locale","emailConsentAt","emailUnsubscribedAt","note","suppressed","profile","consentLogs","events","messages"],"additionalProperties":false},"example":{"id":"contact_example01","email":"customer@example.com","phone":"+886912345678","name":"Alex Chen","emailStatus":"SUBSCRIBED","source":"FORM","createdAt":"2026-10-01T02:30:00.000Z","tags":["VIP","cake-order"],"customer":{"id":"customer_example01","ordersCount":3,"totalSpent":2640,"lastOrderAt":"2026-10-06T08:00:00.000Z","acceptsMarketing":true,"country":"TW","recentOrders":[{"id":"order_example01","orderNumber":1024,"status":"PAID","paidAmount":980,"currency":"TWD","createdAt":"2026-10-06T08:00:00.000Z"}]},"locale":"zh-Hant","emailConsentAt":"2026-10-01T02:30:00.000Z","emailUnsubscribedAt":null,"note":"Prefers less sugar.","suppressed":false,"profile":[{"key":"birthday","label":"Birthday","value":"10-20"}],"consentLogs":[{"id":"consent_example01","channel":"EMAIL","action":"SUBSCRIBE","source":"FORM","createdAt":"2026-10-01T02:30:00.000Z"}],"events":[{"id":"evt_example01","type":"form.submitted","occurredAt":"2026-10-01T02:30:00.000Z","payload":{"formId":"form_example01"}}],"messages":[{"id":"msg_example01","channel":"EMAIL","kind":"CAMPAIGN","type":"campaign","status":"DELIVERED","at":"2026-10-06T08:00:00.000Z"}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"contacts.get","x-kanorio-mcp-tool":"contacts_get","x-kanorio-required-scope":"customers:view","x-kanorio-read-only":true,"x-kanorio-untrusted-content":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"patch":{"operationId":"contacts_update_tags_note","summary":"contacts.update_tags_note","description":"Replace a contact's tags and/or owner note (provide at least one; the other keeps its current value). Tags are trimmed, de-duplicated, max 20 × 50 chars. Errors: FORBIDDEN, VALIDATION, CONTACT_NOT_FOUND.","tags":["contacts"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"contactId","in":"path","required":true,"description":"Contact id. Get it from contacts.list.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":50}},"note":{"type":"string","maxLength":2000}}},"example":{"tags":["VIP","cake-order"],"note":"Prefers less sugar."}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["contactId","tags","note"],"additionalProperties":false},"example":{"contactId":"contact_example01","tags":["VIP","cake-order"],"note":"Prefers less sugar."}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"contacts.update_tags_note","x-kanorio-mcp-tool":"contacts_update_tags_note","x-kanorio-required-scope":"customers:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/segments":{"get":{"operationId":"segments_list","summary":"segments.list","description":"List contact segments with their rules and live audience counts. Use a segment id as campaigns.* audience. Errors: FORBIDDEN.","tags":["segments"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"segments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"isSystem":{"type":"boolean","description":"System segments (e.g. all subscribers) are read-only."},"systemKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"rules":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"counts":{"type":"object","properties":{"matched":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sendable":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["matched","sendable"],"additionalProperties":false,"description":"Live audience counts: matched = all contacts matching the rules; sendable = with valid email consent."}},"required":["id","name","description","isSystem","systemKey","rules","counts"],"additionalProperties":false}}},"required":["segments"],"additionalProperties":false},"example":{"segments":[{"id":"seg_example01","name":"Ordered in the last 90 days","description":null,"isSystem":false,"systemKey":null,"rules":{"lastOrderWithinDays":90},"counts":{"matched":340,"sendable":320}}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"segments.list","x-kanorio-mcp-tool":"segments_list","x-kanorio-required-scope":"customers:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/deliverables":{"get":{"operationId":"deliverables_list","summary":"deliverables.list","description":"List deliverables (courses, e-books, audio series, template packs) with unit counts and linked products. A deliverable is what a buyer receives; products only sell it. Errors: FORBIDDEN.","tags":["deliverables"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"description":"1-based page number.","type":"integer","minimum":1,"maximum":10000}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ALL","ACTIVE","ARCHIVED"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deliverables":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"coverAssetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"structure":{"type":"string","enum":["COURSE","DOWNLOAD"],"description":"Hint for UI and descriptions only; access rules are identical."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"unitCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"productIds":{"type":"array","items":{"type":"string"},"description":"Products that grant this deliverable on purchase (see products.update deliverables)."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","description","coverAssetId","structure","status","unitCount","productIds","createdAt","updatedAt"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pageSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["deliverables","total","page","pageSize"],"additionalProperties":false},"example":{"deliverables":[{"id":"dlv_example01","key":"sourdough-fundamentals","title":"Sourdough Fundamentals","description":"Six-week video course with downloadable recipe cards.","coverAssetId":"asset_example01","structure":"COURSE","status":"ACTIVE","unitCount":3,"productIds":["prod_example01"],"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}],"total":1,"page":1,"pageSize":50}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"deliverables.list","x-kanorio-mcp-tool":"deliverables_list","x-kanorio-required-scope":"store:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"deliverables_create","summary":"deliverables.create","description":"Create a deliverable. Add chapters and units with deliverable_units.replace_tree, then link it to a product with products.update({ deliverables }) or grant it directly with entitlements.grant. Use structure DOWNLOAD for a plain file bundle (e-book, template pack) and COURSE when learners should see chapters and progress. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND, KEY_TAKEN, VALIDATION (details.issues), ASSET_NOT_FOUND (details.assetIds).","tags":["deliverables"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"URL-safe slug, unique per site (a-z, 0-9, hyphen). Used by the Customer API."},"title":{"type":"string","minLength":1,"maxLength":200},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"coverAssetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"structure":{"description":"COURSE (default) for chapters/progress; DOWNLOAD for a flat file list.","type":"string","enum":["COURSE","DOWNLOAD"]},"settings":{"type":"object","properties":{"completionRule":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all_units"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"percent"},"percent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","percent"]},{"type":"object","properties":{"type":{"type":"string","const":"quiz_passed"},"unitId":{"type":"string"}},"required":["type","unitId"]}]},"certificate":{"type":"object","properties":{"enabled":{"type":"boolean"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"signatureName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","title","signatureName"]},"comments":{"type":"object","properties":{"enabled":{"type":"boolean"},"threaded":{"type":"boolean"},"requireReview":{"type":"boolean"},"reactions":{"type":"boolean"}},"required":["enabled","threaded","requireReview","reactions"]},"requireSequential":{"type":"boolean"},"transcriptDownloads":{"type":"boolean"},"estimatedDurationOverride":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"fieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["key","title"]},"example":{"key":"sourdough-fundamentals","title":"Sourdough Fundamentals","description":"Six-week video course with downloadable recipe cards.","coverAssetId":"asset_example01","structure":"COURSE"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"coverAssetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"structure":{"type":"string","enum":["COURSE","DOWNLOAD"],"description":"Hint for UI and descriptions only; access rules are identical."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"unitCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"productIds":{"type":"array","items":{"type":"string"},"description":"Products that grant this deliverable on purchase (see products.update deliverables)."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"settings":{"type":"object","properties":{"completionRule":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all_units"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"percent"},"percent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","percent"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quiz_passed"},"unitId":{"type":"string"}},"required":["type","unitId"],"additionalProperties":false}]},"certificate":{"type":"object","properties":{"enabled":{"type":"boolean"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"signatureName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","title","signatureName"],"additionalProperties":false},"comments":{"type":"object","properties":{"enabled":{"type":"boolean"},"threaded":{"type":"boolean"},"requireReview":{"type":"boolean"},"reactions":{"type":"boolean"}},"required":["enabled","threaded","requireReview","reactions"],"additionalProperties":false},"requireSequential":{"type":"boolean"},"transcriptDownloads":{"type":"boolean"},"estimatedDurationOverride":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["completionRule","certificate","comments","requireSequential","transcriptDownloads","estimatedDurationOverride"],"additionalProperties":false},"fieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter id for units inside a chapter; null for top-level chapters or flat units."},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"kind":{"type":"string","description":"Open string. Known values: video, audio, file, text, quiz; \"chapter\" for grouping rows. Unknown kinds render as a download card."},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"primaryAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Media-library asset (private products bucket). Upload with media.upload first."},"attachmentAssetIds":{"type":"array","items":{"type":"string"}},"fileUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Legacy fallback when the unit predates the asset ledger. Prefer primaryAssetId."},"embed":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string"},"id":{"type":"string"}},"required":["provider","id"],"additionalProperties":false},{"type":"null"}],"description":"External video embed (youtube/vimeo/loom). Not protected by Kanorio; use for FREE sites that cannot host video."},"body":{"description":"text units: { markdown }; quiz units: questions and settings."},"isPreview":{"type":"boolean","description":"Free preview: anonymous visitors can open it."},"visibility":{"type":"string","enum":["VISIBLE","HIDDEN"]},"releaseAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Absolute unlock time."},"releaseAfterDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Unlock N days after the learner's entitlement started."},"allowDownload":{"type":"boolean"},"appliesToAllTiers":{"type":"boolean"},"applicableTierKeys":{"type":"array","items":{"type":"string"},"description":"When appliesToAllTiers is false: PricingTier ids (or the custom-amount key) that unlock this unit."}},"required":["id","parentId","order","kind","title","description","primaryAssetId","attachmentAssetIds","fileUrl","embed","body","isPreview","visibility","releaseAt","releaseAfterDays","allowDownload","appliesToAllTiers","applicableTierKeys"],"additionalProperties":false},"description":"Flat list ordered by chapter then unit; use parentId to rebuild the tree."},"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"accessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["productId","tierId","accessDays"],"additionalProperties":false}}},"required":["id","key","title","description","coverAssetId","structure","status","unitCount","productIds","createdAt","updatedAt","settings","fieldData","units","products"],"additionalProperties":false},"example":{"id":"dlv_example01","key":"sourdough-fundamentals","title":"Sourdough Fundamentals","description":"Six-week video course with downloadable recipe cards.","coverAssetId":"asset_example01","structure":"COURSE","status":"ACTIVE","unitCount":0,"productIds":[],"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z","settings":{"completionRule":{"type":"all_units"},"certificate":{"enabled":false,"title":null,"signatureName":null},"comments":{"enabled":false,"threaded":true,"requireReview":true,"reactions":false},"requireSequential":false,"transcriptDownloads":false,"estimatedDurationOverride":null},"fieldData":null,"units":[],"products":[]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"deliverables.create","x-kanorio-mcp-tool":"deliverables_create","x-kanorio-required-scope":"commerce:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/deliverables/{deliverableId}":{"get":{"operationId":"deliverables_get","summary":"deliverables.get","description":"Get one deliverable with settings and the full chapter/unit tree (no signed file URLs). Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND.","tags":["deliverables"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"deliverableId","in":"path","required":true,"description":"Deliverable id or key. Get it from deliverables.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"coverAssetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"structure":{"type":"string","enum":["COURSE","DOWNLOAD"],"description":"Hint for UI and descriptions only; access rules are identical."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"unitCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"productIds":{"type":"array","items":{"type":"string"},"description":"Products that grant this deliverable on purchase (see products.update deliverables)."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"settings":{"type":"object","properties":{"completionRule":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all_units"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"percent"},"percent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","percent"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quiz_passed"},"unitId":{"type":"string"}},"required":["type","unitId"],"additionalProperties":false}]},"certificate":{"type":"object","properties":{"enabled":{"type":"boolean"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"signatureName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","title","signatureName"],"additionalProperties":false},"comments":{"type":"object","properties":{"enabled":{"type":"boolean"},"threaded":{"type":"boolean"},"requireReview":{"type":"boolean"},"reactions":{"type":"boolean"}},"required":["enabled","threaded","requireReview","reactions"],"additionalProperties":false},"requireSequential":{"type":"boolean"},"transcriptDownloads":{"type":"boolean"},"estimatedDurationOverride":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["completionRule","certificate","comments","requireSequential","transcriptDownloads","estimatedDurationOverride"],"additionalProperties":false},"fieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter id for units inside a chapter; null for top-level chapters or flat units."},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"kind":{"type":"string","description":"Open string. Known values: video, audio, file, text, quiz; \"chapter\" for grouping rows. Unknown kinds render as a download card."},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"primaryAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Media-library asset (private products bucket). Upload with media.upload first."},"attachmentAssetIds":{"type":"array","items":{"type":"string"}},"fileUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Legacy fallback when the unit predates the asset ledger. Prefer primaryAssetId."},"embed":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string"},"id":{"type":"string"}},"required":["provider","id"],"additionalProperties":false},{"type":"null"}],"description":"External video embed (youtube/vimeo/loom). Not protected by Kanorio; use for FREE sites that cannot host video."},"body":{"description":"text units: { markdown }; quiz units: questions and settings."},"isPreview":{"type":"boolean","description":"Free preview: anonymous visitors can open it."},"visibility":{"type":"string","enum":["VISIBLE","HIDDEN"]},"releaseAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Absolute unlock time."},"releaseAfterDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Unlock N days after the learner's entitlement started."},"allowDownload":{"type":"boolean"},"appliesToAllTiers":{"type":"boolean"},"applicableTierKeys":{"type":"array","items":{"type":"string"},"description":"When appliesToAllTiers is false: PricingTier ids (or the custom-amount key) that unlock this unit."}},"required":["id","parentId","order","kind","title","description","primaryAssetId","attachmentAssetIds","fileUrl","embed","body","isPreview","visibility","releaseAt","releaseAfterDays","allowDownload","appliesToAllTiers","applicableTierKeys"],"additionalProperties":false},"description":"Flat list ordered by chapter then unit; use parentId to rebuild the tree."},"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"accessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["productId","tierId","accessDays"],"additionalProperties":false}}},"required":["id","key","title","description","coverAssetId","structure","status","unitCount","productIds","createdAt","updatedAt","settings","fieldData","units","products"],"additionalProperties":false},"example":{"id":"dlv_example01","key":"sourdough-fundamentals","title":"Sourdough Fundamentals","description":"Six-week video course with downloadable recipe cards.","coverAssetId":"asset_example01","structure":"COURSE","status":"ACTIVE","unitCount":3,"productIds":["prod_example01"],"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z","settings":{"completionRule":{"type":"all_units"},"certificate":{"enabled":false,"title":null,"signatureName":null},"comments":{"enabled":false,"threaded":true,"requireReview":true,"reactions":false},"requireSequential":false,"transcriptDownloads":false,"estimatedDurationOverride":null},"fieldData":null,"units":[{"id":"unit_chapter01","parentId":null,"order":0,"kind":"chapter","title":"Week 1 · Getting started","description":null,"primaryAssetId":null,"attachmentAssetIds":[],"fileUrl":null,"embed":null,"body":null,"isPreview":false,"visibility":"VISIBLE","releaseAt":null,"releaseAfterDays":null,"allowDownload":false,"appliesToAllTiers":true,"applicableTierKeys":[]},{"id":"unit_video01","parentId":"unit_chapter01","order":0,"kind":"video","title":"Welcome and course overview","description":"What you will build in six weeks.","primaryAssetId":"asset_example01","attachmentAssetIds":[],"fileUrl":null,"embed":null,"body":null,"isPreview":true,"visibility":"VISIBLE","releaseAt":null,"releaseAfterDays":null,"allowDownload":false,"appliesToAllTiers":true,"applicableTierKeys":[]},{"id":"unit_text01","parentId":"unit_chapter01","order":1,"kind":"text","title":"Set up your workspace","description":null,"primaryAssetId":null,"attachmentAssetIds":[],"fileUrl":null,"embed":null,"body":{"markdown":"## Install\n\n1. Download the starter kit…"},"isPreview":false,"visibility":"VISIBLE","releaseAt":null,"releaseAfterDays":2,"allowDownload":false,"appliesToAllTiers":true,"applicableTierKeys":[]}],"products":[{"productId":"prod_example01","tierId":null,"accessDays":null}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"deliverables.get","x-kanorio-mcp-tool":"deliverables_get","x-kanorio-required-scope":"store:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"patch":{"operationId":"deliverables_update","summary":"deliverables.update","description":"Partially update a deliverable (title, description, cover, structure, settings such as completionRule/certificate/comments). Units are managed with deliverable_units.*. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND, KEY_TAKEN, VALIDATION (details.issues), ASSET_NOT_FOUND (details.assetIds).","tags":["deliverables"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"deliverableId","in":"path","required":true,"description":"Deliverable id or key. Get it from deliverables.list.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"URL-safe slug, unique per site (a-z, 0-9, hyphen). Used by the Customer API."},"title":{"type":"string","minLength":1,"maxLength":200},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"coverAssetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"structure":{"description":"COURSE (default) for chapters/progress; DOWNLOAD for a flat file list.","type":"string","enum":["COURSE","DOWNLOAD"]},"settings":{"type":"object","properties":{"completionRule":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all_units"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"percent"},"percent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","percent"]},{"type":"object","properties":{"type":{"type":"string","const":"quiz_passed"},"unitId":{"type":"string"}},"required":["type","unitId"]}]},"certificate":{"type":"object","properties":{"enabled":{"type":"boolean"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"signatureName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","title","signatureName"]},"comments":{"type":"object","properties":{"enabled":{"type":"boolean"},"threaded":{"type":"boolean"},"requireReview":{"type":"boolean"},"reactions":{"type":"boolean"}},"required":["enabled","threaded","requireReview","reactions"]},"requireSequential":{"type":"boolean"},"transcriptDownloads":{"type":"boolean"},"estimatedDurationOverride":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}}},"fieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}}},"example":{"settings":{"completionRule":{"type":"percent","percent":80},"certificate":{"enabled":true,"title":"Certificate of Completion","signatureName":"Head Baker"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"coverAssetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"structure":{"type":"string","enum":["COURSE","DOWNLOAD"],"description":"Hint for UI and descriptions only; access rules are identical."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"unitCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"productIds":{"type":"array","items":{"type":"string"},"description":"Products that grant this deliverable on purchase (see products.update deliverables)."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"settings":{"type":"object","properties":{"completionRule":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all_units"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"percent"},"percent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","percent"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quiz_passed"},"unitId":{"type":"string"}},"required":["type","unitId"],"additionalProperties":false}]},"certificate":{"type":"object","properties":{"enabled":{"type":"boolean"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"signatureName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","title","signatureName"],"additionalProperties":false},"comments":{"type":"object","properties":{"enabled":{"type":"boolean"},"threaded":{"type":"boolean"},"requireReview":{"type":"boolean"},"reactions":{"type":"boolean"}},"required":["enabled","threaded","requireReview","reactions"],"additionalProperties":false},"requireSequential":{"type":"boolean"},"transcriptDownloads":{"type":"boolean"},"estimatedDurationOverride":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["completionRule","certificate","comments","requireSequential","transcriptDownloads","estimatedDurationOverride"],"additionalProperties":false},"fieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter id for units inside a chapter; null for top-level chapters or flat units."},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"kind":{"type":"string","description":"Open string. Known values: video, audio, file, text, quiz; \"chapter\" for grouping rows. Unknown kinds render as a download card."},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"primaryAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Media-library asset (private products bucket). Upload with media.upload first."},"attachmentAssetIds":{"type":"array","items":{"type":"string"}},"fileUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Legacy fallback when the unit predates the asset ledger. Prefer primaryAssetId."},"embed":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string"},"id":{"type":"string"}},"required":["provider","id"],"additionalProperties":false},{"type":"null"}],"description":"External video embed (youtube/vimeo/loom). Not protected by Kanorio; use for FREE sites that cannot host video."},"body":{"description":"text units: { markdown }; quiz units: questions and settings."},"isPreview":{"type":"boolean","description":"Free preview: anonymous visitors can open it."},"visibility":{"type":"string","enum":["VISIBLE","HIDDEN"]},"releaseAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Absolute unlock time."},"releaseAfterDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Unlock N days after the learner's entitlement started."},"allowDownload":{"type":"boolean"},"appliesToAllTiers":{"type":"boolean"},"applicableTierKeys":{"type":"array","items":{"type":"string"},"description":"When appliesToAllTiers is false: PricingTier ids (or the custom-amount key) that unlock this unit."}},"required":["id","parentId","order","kind","title","description","primaryAssetId","attachmentAssetIds","fileUrl","embed","body","isPreview","visibility","releaseAt","releaseAfterDays","allowDownload","appliesToAllTiers","applicableTierKeys"],"additionalProperties":false},"description":"Flat list ordered by chapter then unit; use parentId to rebuild the tree."},"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"accessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["productId","tierId","accessDays"],"additionalProperties":false}}},"required":["id","key","title","description","coverAssetId","structure","status","unitCount","productIds","createdAt","updatedAt","settings","fieldData","units","products"],"additionalProperties":false},"example":{"id":"dlv_example01","key":"sourdough-fundamentals","title":"Sourdough Fundamentals","description":"Six-week video course with downloadable recipe cards.","coverAssetId":"asset_example01","structure":"COURSE","status":"ACTIVE","unitCount":3,"productIds":["prod_example01"],"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z","settings":{"completionRule":{"type":"percent","percent":80},"certificate":{"enabled":true,"title":"Certificate of Completion","signatureName":"Head Baker"},"comments":{"enabled":false,"threaded":true,"requireReview":true,"reactions":false},"requireSequential":false,"transcriptDownloads":false,"estimatedDurationOverride":null},"fieldData":null,"units":[{"id":"unit_chapter01","parentId":null,"order":0,"kind":"chapter","title":"Week 1 · Getting started","description":null,"primaryAssetId":null,"attachmentAssetIds":[],"fileUrl":null,"embed":null,"body":null,"isPreview":false,"visibility":"VISIBLE","releaseAt":null,"releaseAfterDays":null,"allowDownload":false,"appliesToAllTiers":true,"applicableTierKeys":[]},{"id":"unit_video01","parentId":"unit_chapter01","order":0,"kind":"video","title":"Welcome and course overview","description":"What you will build in six weeks.","primaryAssetId":"asset_example01","attachmentAssetIds":[],"fileUrl":null,"embed":null,"body":null,"isPreview":true,"visibility":"VISIBLE","releaseAt":null,"releaseAfterDays":null,"allowDownload":false,"appliesToAllTiers":true,"applicableTierKeys":[]},{"id":"unit_text01","parentId":"unit_chapter01","order":1,"kind":"text","title":"Set up your workspace","description":null,"primaryAssetId":null,"attachmentAssetIds":[],"fileUrl":null,"embed":null,"body":{"markdown":"## Install\n\n1. Download the starter kit…"},"isPreview":false,"visibility":"VISIBLE","releaseAt":null,"releaseAfterDays":2,"allowDownload":false,"appliesToAllTiers":true,"applicableTierKeys":[]}],"products":[{"productId":"prod_example01","tierId":null,"accessDays":null}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"deliverables.update","x-kanorio-mcp-tool":"deliverables_update","x-kanorio-required-scope":"commerce:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/deliverables/{deliverableId}/archive":{"post":{"operationId":"deliverables_archive","summary":"deliverables.archive","description":"Archive a deliverable: it can no longer be granted or sold, existing learners keep access until you revoke their entitlements. Deliverables are never deleted. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND.","tags":["deliverables"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"deliverableId","in":"path","required":true,"description":"Deliverable id or key. Get it from deliverables.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"coverAssetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"structure":{"type":"string","enum":["COURSE","DOWNLOAD"],"description":"Hint for UI and descriptions only; access rules are identical."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"unitCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"productIds":{"type":"array","items":{"type":"string"},"description":"Products that grant this deliverable on purchase (see products.update deliverables)."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","key","title","description","coverAssetId","structure","status","unitCount","productIds","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"dlv_example01","key":"sourdough-fundamentals","title":"Sourdough Fundamentals","description":"Six-week video course with downloadable recipe cards.","coverAssetId":"asset_example01","structure":"COURSE","status":"ARCHIVED","unitCount":3,"productIds":["prod_example01"],"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"deliverables.archive","x-kanorio-mcp-tool":"deliverables_archive","x-kanorio-required-scope":"commerce:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/deliverables/{deliverableId}/units":{"put":{"operationId":"deliverable_units_replace_tree","summary":"deliverable_units.replace_tree","description":"Replace the whole chapter/unit tree of a deliverable (PUT semantics): units with an id are updated, units without an id are created, units missing from the payload are deleted along with learner progress on them. Two levels only: top-level nodes may have children; children cannot. For a flat download bundle just pass units without children. Upload files with media.upload first and reference them by primaryAssetId / attachmentAssetIds. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND, UNIT_TREE_INVALID (details.reason), ASSET_NOT_FOUND, VALIDATION.","tags":["deliverable_units"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"deliverableId","in":"path","required":true,"description":"Deliverable id or key. Get it from deliverables.list.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1,"maxLength":32},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"primaryAssetId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"attachmentAssetIds":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"embed":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["youtube","vimeo","loom"]},"id":{"type":"string","minLength":1,"maxLength":128}},"required":["provider","id"]},{"type":"null"}]},"body":{},"isPreview":{"type":"boolean"},"visibility":{"type":"string","enum":["VISIBLE","HIDDEN"]},"releaseAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"releaseAfterDays":{"anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]},"allowDownload":{"type":"boolean"},"appliesToAllTiers":{"type":"boolean"},"applicableTierKeys":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"children":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1,"maxLength":32},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"primaryAssetId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"attachmentAssetIds":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"embed":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["youtube","vimeo","loom"]},"id":{"type":"string","minLength":1,"maxLength":128}},"required":["provider","id"]},{"type":"null"}]},"body":{},"isPreview":{"type":"boolean"},"visibility":{"type":"string","enum":["VISIBLE","HIDDEN"]},"releaseAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"releaseAfterDays":{"anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]},"allowDownload":{"type":"boolean"},"appliesToAllTiers":{"type":"boolean"},"applicableTierKeys":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"required":["kind"],"additionalProperties":false}}},"required":["kind"],"additionalProperties":false}}},"required":["units"]},"example":{"units":[{"kind":"chapter","title":"Week 1 · Getting started","children":[{"kind":"video","title":"Welcome and course overview","primaryAssetId":"asset_example01","isPreview":true},{"kind":"text","title":"Set up your workspace","body":{"markdown":"## Install\n\n1. Download the starter kit…"},"releaseAfterDays":2}]}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"coverAssetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"structure":{"type":"string","enum":["COURSE","DOWNLOAD"],"description":"Hint for UI and descriptions only; access rules are identical."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"unitCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"productIds":{"type":"array","items":{"type":"string"},"description":"Products that grant this deliverable on purchase (see products.update deliverables)."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"settings":{"type":"object","properties":{"completionRule":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all_units"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"percent"},"percent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","percent"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"quiz_passed"},"unitId":{"type":"string"}},"required":["type","unitId"],"additionalProperties":false}]},"certificate":{"type":"object","properties":{"enabled":{"type":"boolean"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"signatureName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["enabled","title","signatureName"],"additionalProperties":false},"comments":{"type":"object","properties":{"enabled":{"type":"boolean"},"threaded":{"type":"boolean"},"requireReview":{"type":"boolean"},"reactions":{"type":"boolean"}},"required":["enabled","threaded","requireReview","reactions"],"additionalProperties":false},"requireSequential":{"type":"boolean"},"transcriptDownloads":{"type":"boolean"},"estimatedDurationOverride":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["completionRule","certificate","comments","requireSequential","transcriptDownloads","estimatedDurationOverride"],"additionalProperties":false},"fieldData":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter id for units inside a chapter; null for top-level chapters or flat units."},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"kind":{"type":"string","description":"Open string. Known values: video, audio, file, text, quiz; \"chapter\" for grouping rows. Unknown kinds render as a download card."},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"primaryAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Media-library asset (private products bucket). Upload with media.upload first."},"attachmentAssetIds":{"type":"array","items":{"type":"string"}},"fileUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Legacy fallback when the unit predates the asset ledger. Prefer primaryAssetId."},"embed":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string"},"id":{"type":"string"}},"required":["provider","id"],"additionalProperties":false},{"type":"null"}],"description":"External video embed (youtube/vimeo/loom). Not protected by Kanorio; use for FREE sites that cannot host video."},"body":{"description":"text units: { markdown }; quiz units: questions and settings."},"isPreview":{"type":"boolean","description":"Free preview: anonymous visitors can open it."},"visibility":{"type":"string","enum":["VISIBLE","HIDDEN"]},"releaseAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Absolute unlock time."},"releaseAfterDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Unlock N days after the learner's entitlement started."},"allowDownload":{"type":"boolean"},"appliesToAllTiers":{"type":"boolean"},"applicableTierKeys":{"type":"array","items":{"type":"string"},"description":"When appliesToAllTiers is false: PricingTier ids (or the custom-amount key) that unlock this unit."}},"required":["id","parentId","order","kind","title","description","primaryAssetId","attachmentAssetIds","fileUrl","embed","body","isPreview","visibility","releaseAt","releaseAfterDays","allowDownload","appliesToAllTiers","applicableTierKeys"],"additionalProperties":false},"description":"Flat list ordered by chapter then unit; use parentId to rebuild the tree."},"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"accessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["productId","tierId","accessDays"],"additionalProperties":false}},"changes":{"type":"object","properties":{"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"updated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"deleted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["created","updated","deleted"],"additionalProperties":false}},"required":["id","key","title","description","coverAssetId","structure","status","unitCount","productIds","createdAt","updatedAt","settings","fieldData","units","products","changes"],"additionalProperties":false},"example":{"id":"dlv_example01","key":"sourdough-fundamentals","title":"Sourdough Fundamentals","description":"Six-week video course with downloadable recipe cards.","coverAssetId":"asset_example01","structure":"COURSE","status":"ACTIVE","unitCount":3,"productIds":["prod_example01"],"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z","settings":{"completionRule":{"type":"all_units"},"certificate":{"enabled":false,"title":null,"signatureName":null},"comments":{"enabled":false,"threaded":true,"requireReview":true,"reactions":false},"requireSequential":false,"transcriptDownloads":false,"estimatedDurationOverride":null},"fieldData":null,"units":[{"id":"unit_chapter01","parentId":null,"order":0,"kind":"chapter","title":"Week 1 · Getting started","description":null,"primaryAssetId":null,"attachmentAssetIds":[],"fileUrl":null,"embed":null,"body":null,"isPreview":false,"visibility":"VISIBLE","releaseAt":null,"releaseAfterDays":null,"allowDownload":false,"appliesToAllTiers":true,"applicableTierKeys":[]},{"id":"unit_video01","parentId":"unit_chapter01","order":0,"kind":"video","title":"Welcome and course overview","description":"What you will build in six weeks.","primaryAssetId":"asset_example01","attachmentAssetIds":[],"fileUrl":null,"embed":null,"body":null,"isPreview":true,"visibility":"VISIBLE","releaseAt":null,"releaseAfterDays":null,"allowDownload":false,"appliesToAllTiers":true,"applicableTierKeys":[]},{"id":"unit_text01","parentId":"unit_chapter01","order":1,"kind":"text","title":"Set up your workspace","description":null,"primaryAssetId":null,"attachmentAssetIds":[],"fileUrl":null,"embed":null,"body":{"markdown":"## Install\n\n1. Download the starter kit…"},"isPreview":false,"visibility":"VISIBLE","releaseAt":null,"releaseAfterDays":2,"allowDownload":false,"appliesToAllTiers":true,"applicableTierKeys":[]}],"products":[{"productId":"prod_example01","tierId":null,"accessDays":null}],"changes":{"created":3,"updated":0,"deleted":0}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"deliverable_units.replace_tree","x-kanorio-mcp-tool":"deliverable_units_replace_tree","x-kanorio-required-scope":"commerce:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/deliverables/{deliverableId}/units/reorder":{"post":{"operationId":"deliverable_units_reorder","summary":"deliverable_units.reorder","description":"Reorder sibling units: pass every id of one level (top level when parentId is null) in the new order. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND, UNIT_TREE_INVALID.","tags":["deliverable_units"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"deliverableId","in":"path","required":true,"description":"Deliverable id or key. Get it from deliverables.list.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter id, or null for the top level."},"orderedIds":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","minLength":1}}},"required":["parentId","orderedIds"]},"example":{"parentId":"unit_chapter01","orderedIds":["unit_text01","unit_video01"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false},"example":{"count":2}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"deliverable_units.reorder","x-kanorio-mcp-tool":"deliverable_units_reorder","x-kanorio-required-scope":"commerce:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/deliverable-units/{unitId}":{"patch":{"operationId":"deliverable_units_update","summary":"deliverable_units.update","description":"Update one unit in place (title, file, preview flag, unlock schedule, tier scope) without touching the tree. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND, ASSET_NOT_FOUND, VALIDATION.","tags":["deliverable_units"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"unitId","in":"path","required":true,"description":"Unit id. Get it from deliverables.get.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":32},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"primaryAssetId":{"anyOf":[{"type":"string"},{"type":"null"}]},"attachmentAssetIds":{"maxItems":50,"type":"array","items":{"type":"string"}},"embed":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["youtube","vimeo","loom"]},"id":{"type":"string"}},"required":["provider","id"]},{"type":"null"}]},"body":{},"isPreview":{"type":"boolean"},"visibility":{"type":"string","enum":["VISIBLE","HIDDEN"]},"releaseAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO-8601 timestamp with timezone, e.g. 2026-10-05T12:34:56.789Z."},{"type":"null"}]},"releaseAfterDays":{"anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]},"allowDownload":{"type":"boolean"},"appliesToAllTiers":{"type":"boolean"},"applicableTierKeys":{"maxItems":50,"type":"array","items":{"type":"string"}}}},"example":{"title":"Welcome!","isPreview":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chapter id for units inside a chapter; null for top-level chapters or flat units."},"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"kind":{"type":"string","description":"Open string. Known values: video, audio, file, text, quiz; \"chapter\" for grouping rows. Unknown kinds render as a download card."},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"primaryAssetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Media-library asset (private products bucket). Upload with media.upload first."},"attachmentAssetIds":{"type":"array","items":{"type":"string"}},"fileUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Legacy fallback when the unit predates the asset ledger. Prefer primaryAssetId."},"embed":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string"},"id":{"type":"string"}},"required":["provider","id"],"additionalProperties":false},{"type":"null"}],"description":"External video embed (youtube/vimeo/loom). Not protected by Kanorio; use for FREE sites that cannot host video."},"body":{"description":"text units: { markdown }; quiz units: questions and settings."},"isPreview":{"type":"boolean","description":"Free preview: anonymous visitors can open it."},"visibility":{"type":"string","enum":["VISIBLE","HIDDEN"]},"releaseAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Absolute unlock time."},"releaseAfterDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Unlock N days after the learner's entitlement started."},"allowDownload":{"type":"boolean"},"appliesToAllTiers":{"type":"boolean"},"applicableTierKeys":{"type":"array","items":{"type":"string"},"description":"When appliesToAllTiers is false: PricingTier ids (or the custom-amount key) that unlock this unit."}},"required":["id","parentId","order","kind","title","description","primaryAssetId","attachmentAssetIds","fileUrl","embed","body","isPreview","visibility","releaseAt","releaseAfterDays","allowDownload","appliesToAllTiers","applicableTierKeys"],"additionalProperties":false},"example":{"id":"unit_video01","parentId":"unit_chapter01","order":0,"kind":"video","title":"Welcome!","description":"What you will build in six weeks.","primaryAssetId":"asset_example01","attachmentAssetIds":[],"fileUrl":null,"embed":null,"body":null,"isPreview":true,"visibility":"VISIBLE","releaseAt":null,"releaseAfterDays":null,"allowDownload":false,"appliesToAllTiers":true,"applicableTierKeys":[]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"deliverable_units.update","x-kanorio-mcp-tool":"deliverable_units_update","x-kanorio-required-scope":"commerce:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/entitlements":{"get":{"operationId":"entitlements_list","summary":"entitlements.list","description":"List entitlements (who can access which deliverable) filtered by contact or deliverable; includes revoked and expired rows. Errors: FORBIDDEN.","tags":["entitlements"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"description":"1-based page number.","type":"integer","minimum":1,"maximum":10000}},{"name":"contactId","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"deliverableId","in":"query","required":false,"description":"Deliverable id or key. Get it from deliverables.list.","schema":{"type":"string","minLength":1,"description":"Deliverable id or key. Get it from deliverables.list."}},{"name":"activeOnly","in":"query","required":false,"description":"Only rows that are not revoked and not expired.","schema":{"description":"Only rows that are not revoked and not expired.","type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"entitlements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contactId":{"type":"string"},"deliverableId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"productId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Source product snapshot when the entitlement came from an order."},"source":{"type":"string","description":"ORDER_LINE, MANUAL_GRANT, PREPAID_REDEMPTION, FREE."},"sourceRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"startsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"endsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokeReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","contactId","deliverableId","unitId","tierId","productId","source","sourceRef","startsAt","endsAt","revokedAt","revokeReason","createdAt"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pageSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["entitlements","total","page","pageSize"],"additionalProperties":false},"example":{"entitlements":[{"id":"ent_example01","contactId":"contact_example01","deliverableId":"dlv_example01","unitId":null,"tierId":null,"productId":null,"source":"MANUAL_GRANT","sourceRef":null,"startsAt":"2026-10-01T02:30:00.000Z","endsAt":null,"revokedAt":null,"revokeReason":null,"createdAt":"2026-10-01T02:30:00.000Z"}],"total":1,"page":1,"pageSize":50}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"entitlements.list","x-kanorio-mcp-tool":"entitlements_list","x-kanorio-required-scope":"customers:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"entitlements_grant","summary":"entitlements.grant","description":"Grant a contact access to a deliverable without a purchase (gift, corporate seat, lead magnet). Idempotent: an existing active manual grant for the same deliverable is extended instead of duplicated. Errors: FORBIDDEN, CONTACT_NOT_FOUND, DELIVERABLE_NOT_FOUND (archived deliverables cannot be granted).","tags":["entitlements"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string","minLength":1,"description":"Get it from contacts.list or contacts.add."},"deliverableId":{"type":"string","minLength":1,"description":"Deliverable id or key. Get it from deliverables.list."},"endsAt":{"description":"Access expiry; omit for permanent access.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"ISO-8601 timestamp with timezone, e.g. 2026-10-05T12:34:56.789Z."},{"type":"null"}]}},"required":["contactId","deliverableId"]},"example":{"contactId":"contact_example01","deliverableId":"dlv_example01"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"contactId":{"type":"string"},"deliverableId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"productId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Source product snapshot when the entitlement came from an order."},"source":{"type":"string","description":"ORDER_LINE, MANUAL_GRANT, PREPAID_REDEMPTION, FREE."},"sourceRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"startsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"endsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokeReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","contactId","deliverableId","unitId","tierId","productId","source","sourceRef","startsAt","endsAt","revokedAt","revokeReason","createdAt"],"additionalProperties":false},"example":{"id":"ent_example01","contactId":"contact_example01","deliverableId":"dlv_example01","unitId":null,"tierId":null,"productId":null,"source":"MANUAL_GRANT","sourceRef":null,"startsAt":"2026-10-01T02:30:00.000Z","endsAt":null,"revokedAt":null,"revokeReason":null,"createdAt":"2026-10-01T02:30:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"entitlements.grant","x-kanorio-mcp-tool":"entitlements_grant","x-kanorio-required-scope":"customers:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/entitlements/check":{"get":{"operationId":"entitlements_check","summary":"entitlements.check","description":"Check whether a contact can access a deliverable or a single unit right now (entitlement, free preview, release schedule, expiry). Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND.","tags":["entitlements"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"contactId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"contact_example01"},{"name":"deliverableId","in":"query","required":false,"description":"Deliverable id or key. Get it from deliverables.list.","schema":{"type":"string","minLength":1,"description":"Deliverable id or key. Get it from deliverables.list."},"example":"dlv_example01"},{"name":"unitId","in":"query","required":false,"description":"Unit id. Get it from deliverables.get.","schema":{"type":"string","minLength":1,"description":"Unit id. Get it from deliverables.get."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"granted":{"type":"boolean"},"reason":{"type":"string","enum":["entitlement","preview","none","not_released","expired","hidden","not_found"]},"availableAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["granted","reason","availableAt"],"additionalProperties":false},"example":{"granted":true,"reason":"entitlement","availableAt":null}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"entitlements.check","x-kanorio-mcp-tool":"entitlements_check","x-kanorio-required-scope":"customers:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/entitlements/{entitlementId}/revoke":{"post":{"operationId":"entitlements_revoke","summary":"entitlements.revoke","description":"Revoke one entitlement (learner loses access immediately; the row is kept for audit). Errors: FORBIDDEN, ENTITLEMENT_NOT_FOUND.","tags":["entitlements"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"entitlementId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":200}}},"example":{"reason":"Corporate seat reassigned"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"contactId":{"type":"string"},"deliverableId":{"anyOf":[{"type":"string"},{"type":"null"}]},"unitId":{"anyOf":[{"type":"string"},{"type":"null"}]},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"productId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Source product snapshot when the entitlement came from an order."},"source":{"type":"string","description":"ORDER_LINE, MANUAL_GRANT, PREPAID_REDEMPTION, FREE."},"sourceRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"startsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"endsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"revokeReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","contactId","deliverableId","unitId","tierId","productId","source","sourceRef","startsAt","endsAt","revokedAt","revokeReason","createdAt"],"additionalProperties":false},"example":{"id":"ent_example01","contactId":"contact_example01","deliverableId":"dlv_example01","unitId":null,"tierId":null,"productId":null,"source":"MANUAL_GRANT","sourceRef":null,"startsAt":"2026-10-01T02:30:00.000Z","endsAt":null,"revokedAt":"2026-10-06T08:00:00.000Z","revokeReason":"Corporate seat reassigned","createdAt":"2026-10-01T02:30:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"entitlements.revoke","x-kanorio-mcp-tool":"entitlements_revoke","x-kanorio-required-scope":"customers:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/deliverables/{deliverableId}/progress":{"get":{"operationId":"progress_list","summary":"progress.list","description":"List learner progress for one deliverable (percent, completed, per-unit status). One row per contact that has an active entitlement. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND.","tags":["progress"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"deliverableId","in":"path","required":true,"description":"Deliverable id or key. Get it from deliverables.list.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"description":"1-based page number.","type":"integer","minimum":1,"maximum":10000}},{"name":"contactId","in":"query","required":false,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"progress":{"type":"array","items":{"type":"object","properties":{"contactId":{"type":"string"},"percent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"completed":{"type":"boolean"},"units":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","enum":["not_started","in-progress","completed"]}}},"required":["contactId","percent","completed","units"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pageSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["progress","total","page","pageSize"],"additionalProperties":false},"example":{"progress":[{"contactId":"contact_example01","percent":50,"completed":false,"units":{"unit_video01":"completed","unit_text01":"in-progress"}}],"total":1,"page":1,"pageSize":50}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"progress.list","x-kanorio-mcp-tool":"progress_list","x-kanorio-required-scope":"customers:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/products":{"get":{"operationId":"products_list","summary":"products.list","description":"List products (ACTIVE first, then ARCHIVED) with images, variants and paid order counts; storeCurrency is the ISO 4217 code all amounts use. Errors: FORBIDDEN.","tags":["products"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ACTIVE","ARCHIVED"]}},{"name":"limit","in":"query","required":false,"description":"Page size (1-100). Defaults vary per capability.","schema":{"description":"Page size (1-100). Defaults vary per capability.","type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Number of items to skip.","schema":{"description":"Number of items to skip.","type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last URL segment of the product page."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"type":{"type":"string","enum":["DIGITAL","PHYSICAL","SERVICE"]},"isTemplate":{"type":"boolean","description":"Sample product seeded for new sellers; not public."},"images":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId in the media library; null for older images that are not in it."},"url":{"type":"string","description":"Display URL (changes with versions; do not store it)."},"alt":{"type":"string","maxLength":200},"width":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"height":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["assetId","url"],"additionalProperties":false}},"purchaseNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"allowCustomAmount":{"type":"boolean"},"reviewsEnabled":{"type":"boolean"},"primaryCategoryId":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"values":{"type":"array","items":{"type":"string"}}},"required":["id","name","position","values"],"additionalProperties":false}},"pricingTiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","description":"Variant title derived from option values (or the legacy name)."},"optionValues":{"type":"array","items":{"type":"string"}},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units in the store currency."},"compareAtAmount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"isPublished":{"type":"boolean"},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"highlightBadge":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","optionValues","amount","compareAtAmount","isPublished","sortOrder","highlightBadge"],"additionalProperties":false},"description":"Purchasable variants; manage them in the console."},"deliverables":{"type":"array","items":{"type":"object","properties":{"deliverableId":{"type":"string"},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"accessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["deliverableId","tierId","accessDays"],"additionalProperties":false},"description":"Deliverables granted on purchase (DIGITAL products). tierId null = every variant; accessDays null = permanent. Manage with products.update({ deliverables })."},"orderCount":{"description":"Paid orders (list only).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","description","slug","status","type","isTemplate","images","purchaseNotes","allowCustomAmount","reviewsEnabled","primaryCategoryId","options","pricingTiers","deliverables","createdAt","updatedAt"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"storeCurrency":{"type":"string","description":"Lowercase ISO 4217, e.g. twd, usd."}},"required":["products","total","storeCurrency"],"additionalProperties":false},"example":{"products":[{"id":"prod_example01","title":"Strawberry Birthday Cake","description":"Seasonal strawberries and fresh whipped cream. Pre-order at least one day ahead.","slug":"strawberry-birthday-cake","status":"ACTIVE","type":"PHYSICAL","isTemplate":false,"images":[{"assetId":"asset_example01","url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","alt":"Strawberry birthday cake","width":2400,"height":1600}],"purchaseNotes":"Please leave your preferred pickup time in the order note.","allowCustomAmount":false,"reviewsEnabled":true,"primaryCategoryId":"pcat_example01","options":[{"id":"opt_example01","name":"Size","position":0,"values":["6-inch","8-inch"]}],"pricingTiers":[{"id":"tier_example01","title":"6-inch","optionValues":["6-inch"],"amount":880,"compareAtAmount":null,"isPublished":true,"sortOrder":0,"highlightBadge":null},{"id":"tier_example02","title":"8-inch","optionValues":["8-inch"],"amount":1280,"compareAtAmount":null,"isPublished":true,"sortOrder":1,"highlightBadge":null}],"deliverables":[],"orderCount":18,"createdAt":"2026-08-20T06:00:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}],"total":1,"storeCurrency":"TWD"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"products.list","x-kanorio-mcp-tool":"products_list","x-kanorio-required-scope":"store:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"products_create","summary":"products.create","description":"Create an ACTIVE product. Products have no draft state: it appears in the store immediately once it has at least one published variant (add variants/prices in the console). Images are media-library assets: pass their assetId (upload with media.upload or media.import_stock first). Slug is generated from the title when omitted. Errors: FORBIDDEN, VALIDATION (details.reason), PRODUCT_LIMIT_REACHED, SITE_SUSPENDED, ASSET_NOT_FOUND (details.assetIds: not in this site's media library, in the trash, or its file is missing), ASSET_NOT_ALLOWED (not an image, or a product file).","tags":["products"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","minLength":1,"maxLength":20000,"description":"Plain text / Markdown description shown on the store card, checkout and product page."},"images":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string","minLength":1,"maxLength":64,"description":"assetId of an image in the media library (media.upload, media.import_stock, media.list)."},"alt":{"type":"string","maxLength":200}},"required":["assetId"]},"description":"At least one; the first is the cover image."},"purchaseNotes":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"allowCustomAmount":{"type":"boolean"},"reviewsEnabled":{"type":"boolean"},"slug":{"type":"string","maxLength":80},"productType":{"description":"Defaults to DIGITAL.","type":"string","enum":["DIGITAL","PHYSICAL","SERVICE"]}},"required":["title","description","images"]},"example":{"title":"Strawberry Birthday Cake","productType":"PHYSICAL","description":"Seasonal strawberries and fresh whipped cream. Pre-order at least one day ahead.","images":[{"assetId":"asset_example01","alt":"Strawberry birthday cake"}]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last URL segment of the product page."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"type":{"type":"string","enum":["DIGITAL","PHYSICAL","SERVICE"]},"isTemplate":{"type":"boolean","description":"Sample product seeded for new sellers; not public."},"images":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId in the media library; null for older images that are not in it."},"url":{"type":"string","description":"Display URL (changes with versions; do not store it)."},"alt":{"type":"string","maxLength":200},"width":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"height":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["assetId","url"],"additionalProperties":false}},"purchaseNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"allowCustomAmount":{"type":"boolean"},"reviewsEnabled":{"type":"boolean"},"primaryCategoryId":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"values":{"type":"array","items":{"type":"string"}}},"required":["id","name","position","values"],"additionalProperties":false}},"pricingTiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","description":"Variant title derived from option values (or the legacy name)."},"optionValues":{"type":"array","items":{"type":"string"}},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units in the store currency."},"compareAtAmount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"isPublished":{"type":"boolean"},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"highlightBadge":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","optionValues","amount","compareAtAmount","isPublished","sortOrder","highlightBadge"],"additionalProperties":false},"description":"Purchasable variants; manage them in the console."},"deliverables":{"type":"array","items":{"type":"object","properties":{"deliverableId":{"type":"string"},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"accessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["deliverableId","tierId","accessDays"],"additionalProperties":false},"description":"Deliverables granted on purchase (DIGITAL products). tierId null = every variant; accessDays null = permanent. Manage with products.update({ deliverables })."},"orderCount":{"description":"Paid orders (list only).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","description","slug","status","type","isTemplate","images","purchaseNotes","allowCustomAmount","reviewsEnabled","primaryCategoryId","options","pricingTiers","deliverables","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"prod_example01","title":"Strawberry Birthday Cake","description":"Seasonal strawberries and fresh whipped cream. Pre-order at least one day ahead.","slug":"strawberry-birthday-cake","status":"ACTIVE","type":"PHYSICAL","isTemplate":false,"images":[{"assetId":"asset_example01","url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","alt":"Strawberry birthday cake","width":2400,"height":1600}],"purchaseNotes":"Please leave your preferred pickup time in the order note.","allowCustomAmount":false,"reviewsEnabled":true,"primaryCategoryId":"pcat_example01","options":[{"id":"opt_example01","name":"Size","position":0,"values":["6-inch","8-inch"]}],"pricingTiers":[{"id":"tier_example01","title":"6-inch","optionValues":["6-inch"],"amount":880,"compareAtAmount":null,"isPublished":true,"sortOrder":0,"highlightBadge":null},{"id":"tier_example02","title":"8-inch","optionValues":["8-inch"],"amount":1280,"compareAtAmount":null,"isPublished":true,"sortOrder":1,"highlightBadge":null}],"deliverables":[],"orderCount":18,"createdAt":"2026-08-20T06:00:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"products.create","x-kanorio-mcp-tool":"products_create","x-kanorio-required-scope":"commerce:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/products/{productId}":{"get":{"operationId":"products_get","summary":"products.get","description":"Get one product with images, options and variants. Errors: FORBIDDEN, PRODUCT_NOT_FOUND.","tags":["products"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"Product id. Get it from products.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last URL segment of the product page."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"type":{"type":"string","enum":["DIGITAL","PHYSICAL","SERVICE"]},"isTemplate":{"type":"boolean","description":"Sample product seeded for new sellers; not public."},"images":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId in the media library; null for older images that are not in it."},"url":{"type":"string","description":"Display URL (changes with versions; do not store it)."},"alt":{"type":"string","maxLength":200},"width":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"height":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["assetId","url"],"additionalProperties":false}},"purchaseNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"allowCustomAmount":{"type":"boolean"},"reviewsEnabled":{"type":"boolean"},"primaryCategoryId":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"values":{"type":"array","items":{"type":"string"}}},"required":["id","name","position","values"],"additionalProperties":false}},"pricingTiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","description":"Variant title derived from option values (or the legacy name)."},"optionValues":{"type":"array","items":{"type":"string"}},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units in the store currency."},"compareAtAmount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"isPublished":{"type":"boolean"},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"highlightBadge":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","optionValues","amount","compareAtAmount","isPublished","sortOrder","highlightBadge"],"additionalProperties":false},"description":"Purchasable variants; manage them in the console."},"deliverables":{"type":"array","items":{"type":"object","properties":{"deliverableId":{"type":"string"},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"accessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["deliverableId","tierId","accessDays"],"additionalProperties":false},"description":"Deliverables granted on purchase (DIGITAL products). tierId null = every variant; accessDays null = permanent. Manage with products.update({ deliverables })."},"orderCount":{"description":"Paid orders (list only).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","description","slug","status","type","isTemplate","images","purchaseNotes","allowCustomAmount","reviewsEnabled","primaryCategoryId","options","pricingTiers","deliverables","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"prod_example01","title":"Strawberry Birthday Cake","description":"Seasonal strawberries and fresh whipped cream. Pre-order at least one day ahead.","slug":"strawberry-birthday-cake","status":"ACTIVE","type":"PHYSICAL","isTemplate":false,"images":[{"assetId":"asset_example01","url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","alt":"Strawberry birthday cake","width":2400,"height":1600}],"purchaseNotes":"Please leave your preferred pickup time in the order note.","allowCustomAmount":false,"reviewsEnabled":true,"primaryCategoryId":"pcat_example01","options":[{"id":"opt_example01","name":"Size","position":0,"values":["6-inch","8-inch"]}],"pricingTiers":[{"id":"tier_example01","title":"6-inch","optionValues":["6-inch"],"amount":880,"compareAtAmount":null,"isPublished":true,"sortOrder":0,"highlightBadge":null},{"id":"tier_example02","title":"8-inch","optionValues":["8-inch"],"amount":1280,"compareAtAmount":null,"isPublished":true,"sortOrder":1,"highlightBadge":null}],"deliverables":[],"orderCount":18,"createdAt":"2026-08-20T06:00:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"products.get","x-kanorio-mcp-tool":"products_get","x-kanorio-required-scope":"store:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"patch":{"operationId":"products_update","summary":"products.update","description":"Partially update a product (only provided fields change; images replace the whole list). Changes go live on the public store immediately. Errors: FORBIDDEN, PRODUCT_NOT_FOUND, VALIDATION (details.reason), SITE_SUSPENDED, ASSET_NOT_FOUND (details.assetIds: not in this site's media library, in the trash, or its file is missing), ASSET_NOT_ALLOWED (not an image, or a product file).","tags":["products"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"Product id. Get it from products.list.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","minLength":1,"maxLength":20000,"description":"Plain text / Markdown description shown on the store card, checkout and product page."},"images":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string","minLength":1,"maxLength":64,"description":"assetId of an image in the media library (media.upload, media.import_stock, media.list)."},"alt":{"type":"string","maxLength":200}},"required":["assetId"]},"description":"At least one; the first is the cover image."},"purchaseNotes":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"allowCustomAmount":{"type":"boolean"},"reviewsEnabled":{"type":"boolean"},"slug":{"type":"string","maxLength":80},"productType":{"description":"Defaults to DIGITAL.","type":"string","enum":["DIGITAL","PHYSICAL","SERVICE"]},"deliverables":{"description":"Replace the whole list of deliverables granted on purchase. Create deliverables first with deliverables.create. Pass [] to unlink all.","maxItems":50,"type":"array","items":{"type":"object","properties":{"deliverableId":{"type":"string","minLength":1},"tierId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"accessDays":{"anyOf":[{"type":"integer","minimum":1,"maximum":3650},{"type":"null"}]}},"required":["deliverableId"]}}}},"example":{"purchaseNotes":"Please leave your preferred pickup time in the order note."}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last URL segment of the product page."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"type":{"type":"string","enum":["DIGITAL","PHYSICAL","SERVICE"]},"isTemplate":{"type":"boolean","description":"Sample product seeded for new sellers; not public."},"images":{"type":"array","items":{"type":"object","properties":{"assetId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"assetId in the media library; null for older images that are not in it."},"url":{"type":"string","description":"Display URL (changes with versions; do not store it)."},"alt":{"type":"string","maxLength":200},"width":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"height":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["assetId","url"],"additionalProperties":false}},"purchaseNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"allowCustomAmount":{"type":"boolean"},"reviewsEnabled":{"type":"boolean"},"primaryCategoryId":{"anyOf":[{"type":"string"},{"type":"null"}]},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"values":{"type":"array","items":{"type":"string"}}},"required":["id","name","position","values"],"additionalProperties":false}},"pricingTiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","description":"Variant title derived from option values (or the legacy name)."},"optionValues":{"type":"array","items":{"type":"string"}},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units in the store currency."},"compareAtAmount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"isPublished":{"type":"boolean"},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"highlightBadge":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","optionValues","amount","compareAtAmount","isPublished","sortOrder","highlightBadge"],"additionalProperties":false},"description":"Purchasable variants; manage them in the console."},"deliverables":{"type":"array","items":{"type":"object","properties":{"deliverableId":{"type":"string"},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"accessDays":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["deliverableId","tierId","accessDays"],"additionalProperties":false},"description":"Deliverables granted on purchase (DIGITAL products). tierId null = every variant; accessDays null = permanent. Manage with products.update({ deliverables })."},"orderCount":{"description":"Paid orders (list only).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","description","slug","status","type","isTemplate","images","purchaseNotes","allowCustomAmount","reviewsEnabled","primaryCategoryId","options","pricingTiers","deliverables","createdAt","updatedAt"],"additionalProperties":false},"example":{"id":"prod_example01","title":"Strawberry Birthday Cake","description":"Seasonal strawberries and fresh whipped cream. Pre-order at least one day ahead.","slug":"strawberry-birthday-cake","status":"ACTIVE","type":"PHYSICAL","isTemplate":false,"images":[{"assetId":"asset_example01","url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","alt":"Strawberry birthday cake","width":2400,"height":1600}],"purchaseNotes":"Please leave your preferred pickup time in the order note.","allowCustomAmount":false,"reviewsEnabled":true,"primaryCategoryId":"pcat_example01","options":[{"id":"opt_example01","name":"Size","position":0,"values":["6-inch","8-inch"]}],"pricingTiers":[{"id":"tier_example01","title":"6-inch","optionValues":["6-inch"],"amount":880,"compareAtAmount":null,"isPublished":true,"sortOrder":0,"highlightBadge":null},{"id":"tier_example02","title":"8-inch","optionValues":["8-inch"],"amount":1280,"compareAtAmount":null,"isPublished":true,"sortOrder":1,"highlightBadge":null}],"deliverables":[],"orderCount":18,"createdAt":"2026-08-20T06:00:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"products.update","x-kanorio-mcp-tool":"products_update","x-kanorio-required-scope":"commerce:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/products/{productId}/archive":{"post":{"operationId":"products_archive","summary":"products.archive","description":"Archive a product: it disappears from the store but keeps its orders and can be restored in the console. Deleting products is not available to agents. Errors: FORBIDDEN, PRODUCT_NOT_FOUND, SITE_SUSPENDED.","tags":["products"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"Product id. Get it from products.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","const":"ARCHIVED"}},"required":["id","status"],"additionalProperties":false},"example":{"id":"prod_example01","status":"ARCHIVED"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"products.archive","x-kanorio-mcp-tool":"products_archive","x-kanorio-required-scope":"commerce:manage","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/product-categories":{"get":{"operationId":"product_categories_list","summary":"product_categories.list","description":"List product categories (id, slug, name, sortOrder). Category assignment is managed in the console. Errors: FORBIDDEN.","tags":["product_categories"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","slug","name","description","sortOrder"],"additionalProperties":false}}},"required":["categories"],"additionalProperties":false},"example":{"categories":[{"id":"pcat_example01","slug":"cakes","name":"Cakes","description":null,"sortOrder":0}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"product_categories.list","x-kanorio-mcp-tool":"product_categories_list","x-kanorio-required-scope":"store:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/orders":{"get":{"operationId":"orders_list","summary":"orders.list","description":"List orders newest first with line items and shipment summary (amounts in minor units of order.currency). Refunds, payment settings and invoices are not available to agents. Errors: FORBIDDEN.","tags":["orders"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["PAID","PARTIALLY_REFUNDED","REFUNDED","DISPUTED","PAYMENT_REVERSED"]}},{"name":"limit","in":"query","required":false,"description":"Page size (1-100). Defaults vary per capability.","schema":{"description":"Page size (1-100). Defaults vary per capability.","type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Number of items to skip.","schema":{"description":"Number of items to skip.","type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orderNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Human-readable per-store number (#1001...)."},"status":{"type":"string"},"currency":{"type":"string"},"subtotalAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"discountAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items after discount, excluding shipping."},"shippingFee":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalRefunded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"itemCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"customerEmail":{"type":"string"},"customerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"customerPhone":{"anyOf":[{"type":"string"},{"type":"null"}]},"buyerNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"promotionCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"paymentProvider":{"type":"string"},"paidAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"refundedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"productTitle":{"type":"string"},"tierName":{"anyOf":[{"type":"string"},{"type":"null"}]},"productType":{"type":"string"},"unitPrice":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lineAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"refundedQuantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","productId","tierId","productTitle","tierName","productType","unitPrice","quantity","lineAmount","refundedQuantity","refundedAmount"],"additionalProperties":false}},"shipments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"provider":{"type":"string"},"method":{"type":"string"},"trackingNo":{"anyOf":[{"type":"string"},{"type":"null"}]},"trackingUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","provider","method","trackingNo","trackingUrl"],"additionalProperties":false}}},"required":["id","orderNumber","status","currency","subtotalAmount","discountAmount","amount","shippingFee","totalRefunded","itemCount","customerEmail","customerName","customerPhone","buyerNote","promotionCode","paymentProvider","paidAt","refundedAt","createdAt","items","shipments"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["orders","total"],"additionalProperties":false},"example":{"orders":[{"id":"order_example01","orderNumber":1024,"status":"PAID","currency":"TWD","subtotalAmount":880,"discountAmount":0,"amount":980,"shippingFee":100,"totalRefunded":0,"itemCount":1,"customerEmail":"customer@example.com","customerName":"Alex Chen","customerPhone":"+886912345678","buyerNote":"Pickup on Saturday at 2 p.m.","promotionCode":null,"paymentProvider":"STRIPE","paidAt":"2026-10-06T08:00:00.000Z","refundedAt":null,"createdAt":"2026-10-06T08:00:00.000Z","items":[{"id":"item_example01","productId":"prod_example01","tierId":"tier_example01","productTitle":"Strawberry Birthday Cake","tierName":"6-inch","productType":"PHYSICAL","unitPrice":880,"quantity":1,"lineAmount":880,"refundedQuantity":0,"refundedAmount":0}],"shipments":[{"id":"ship_example01","status":"PENDING","provider":"MANUAL","method":"PICKUP","trackingNo":null,"trackingUrl":null}]}],"total":1}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"orders.list","x-kanorio-mcp-tool":"orders_list","x-kanorio-required-scope":"store:view","x-kanorio-read-only":true,"x-kanorio-untrusted-content":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/orders/{orderId}":{"get":{"operationId":"orders_get","summary":"orders.get","description":"Get one order with line items and shipments. Errors: FORBIDDEN, ORDER_NOT_FOUND.","tags":["orders"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"orderNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Human-readable per-store number (#1001...)."},"status":{"type":"string"},"currency":{"type":"string"},"subtotalAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"discountAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Items after discount, excluding shipping."},"shippingFee":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalRefunded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"itemCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"customerEmail":{"type":"string"},"customerName":{"anyOf":[{"type":"string"},{"type":"null"}]},"customerPhone":{"anyOf":[{"type":"string"},{"type":"null"}]},"buyerNote":{"anyOf":[{"type":"string"},{"type":"null"}]},"promotionCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"paymentProvider":{"type":"string"},"paidAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"refundedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"tierId":{"anyOf":[{"type":"string"},{"type":"null"}]},"productTitle":{"type":"string"},"tierName":{"anyOf":[{"type":"string"},{"type":"null"}]},"productType":{"type":"string"},"unitPrice":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lineAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"refundedQuantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","productId","tierId","productTitle","tierName","productType","unitPrice","quantity","lineAmount","refundedQuantity","refundedAmount"],"additionalProperties":false}},"shipments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"provider":{"type":"string"},"method":{"type":"string"},"trackingNo":{"anyOf":[{"type":"string"},{"type":"null"}]},"trackingUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","provider","method","trackingNo","trackingUrl"],"additionalProperties":false}}},"required":["id","orderNumber","status","currency","subtotalAmount","discountAmount","amount","shippingFee","totalRefunded","itemCount","customerEmail","customerName","customerPhone","buyerNote","promotionCode","paymentProvider","paidAt","refundedAt","createdAt","items","shipments"],"additionalProperties":false},"example":{"id":"order_example01","orderNumber":1024,"status":"PAID","currency":"TWD","subtotalAmount":880,"discountAmount":0,"amount":980,"shippingFee":100,"totalRefunded":0,"itemCount":1,"customerEmail":"customer@example.com","customerName":"Alex Chen","customerPhone":"+886912345678","buyerNote":"Pickup on Saturday at 2 p.m.","promotionCode":null,"paymentProvider":"STRIPE","paidAt":"2026-10-06T08:00:00.000Z","refundedAt":null,"createdAt":"2026-10-06T08:00:00.000Z","items":[{"id":"item_example01","productId":"prod_example01","tierId":"tier_example01","productTitle":"Strawberry Birthday Cake","tierName":"6-inch","productType":"PHYSICAL","unitPrice":880,"quantity":1,"lineAmount":880,"refundedQuantity":0,"refundedAmount":0}],"shipments":[{"id":"ship_example01","status":"PENDING","provider":"MANUAL","method":"PICKUP","trackingNo":null,"trackingUrl":null}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"orders.get","x-kanorio-mcp-tool":"orders_get","x-kanorio-required-scope":"store:view","x-kanorio-read-only":true,"x-kanorio-untrusted-content":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/campaigns":{"get":{"operationId":"campaigns_list","summary":"campaigns.list","description":"List email campaigns (newest updated first) with status, audience segment and delivery stats for sent ones. Errors: FORBIDDEN, PLAN_REQUIRED.","tags":["campaigns"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"campaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"channel":{"type":"string"},"status":{"type":"string","description":"DRAFT, SCHEDULED, SENDING, PAUSED, SENT or CANCELED. Agents can only edit DRAFT."},"pausedReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"segmentName":{"anyOf":[{"type":"string"},{"type":"null"}]},"scheduledAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"type":"string"},"recipientCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"stats":{"anyOf":[{"type":"object","properties":{"recipients":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"delivered":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bounced":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"complained":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"notSent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"opened":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clicked":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unsubscribed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["recipients","pending","sent","delivered","bounced","complained","notSent","opened","clicked","unsubscribed"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","channel","status","pausedReason","segmentName","scheduledAt","startedAt","completedAt","updatedAt","recipientCount","stats"],"additionalProperties":false}}},"required":["campaigns"],"additionalProperties":false},"example":{"campaigns":[{"id":"camp_example01","name":"October seasonal bake","channel":"EMAIL","status":"DRAFT","pausedReason":null,"segmentName":"Ordered in the last 90 days","scheduledAt":null,"startedAt":null,"completedAt":null,"updatedAt":"2026-10-06T08:00:00.000Z","recipientCount":320,"stats":null}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"campaigns.list","x-kanorio-mcp-tool":"campaigns_list","x-kanorio-required-scope":"marketing:send","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"campaigns_create_draft","summary":"campaigns.create_draft","description":"Create an email campaign as a DRAFT. Agents cannot send or schedule campaigns; the owner reviews and sends from the console. content is optional; when provided it must match the email design-template content shape (subject, previewText, blocks). Audience defaults to the all-subscribers segment. Reference images as asset:<assetId> (media.upload, media.import_stock). Errors: FORBIDDEN, PLAN_REQUIRED, VALIDATION, INVALID_CONTENT (details.detail lists issues), CHANNEL_UNAVAILABLE, ASSET_NOT_FOUND, ASSET_NOT_ALLOWED.","tags":["campaigns"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"channel":{"description":"Defaults to EMAIL.","type":"string","enum":["EMAIL"]},"content":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["name"]},"example":{"name":"October seasonal bake","channel":"EMAIL"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"channel":{"type":"string"},"status":{"type":"string"},"content":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Channel content (email: subject, previewText, blocks...). Media-library images appear as asset:<assetId>."},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library images the content uses, by assetId."},"audience":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"segment"},"segmentId":{"type":"string","minLength":1}},"required":["kind","segmentId"],"additionalProperties":false,"description":"Who receives it: a segment id from segments.list. New drafts default to the all-subscribers segment."},{"type":"null"}]},"scheduledAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipientCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"updatedAt":{"type":"string"},"timeZone":{"type":"string"}},"required":["id","name","channel","status","content","assets","audience","scheduledAt","recipientCount","updatedAt","timeZone"],"additionalProperties":false},"example":{"id":"camp_example01","name":"October seasonal bake","channel":"EMAIL","status":"DRAFT","content":{"subject":"October special: chestnut croissants are here","body":"This month we're baking..."},"assets":{},"audience":{"kind":"segment","segmentId":"seg_example01"},"scheduledAt":null,"recipientCount":320,"updatedAt":"2026-10-06T08:00:00.000Z","timeZone":"Asia/Taipei"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"campaigns.create_draft","x-kanorio-mcp-tool":"campaigns_create_draft","x-kanorio-required-scope":"marketing:send","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/campaigns/{campaignId}":{"patch":{"operationId":"campaigns_update_draft","summary":"campaigns.update_draft","description":"Update a DRAFT campaign's name, content and/or audience segment. Only drafts can be changed by agents (NOT_EDITABLE otherwise); scheduling and sending stay in the console. Errors: FORBIDDEN, PLAN_REQUIRED, CAMPAIGN_NOT_FOUND, NOT_EDITABLE, INVALID_CONTENT, INVALID_AUDIENCE, SEGMENT_NOT_FOUND, ASSET_NOT_FOUND, ASSET_NOT_ALLOWED.","tags":["campaigns"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"campaignId","in":"path","required":true,"description":"Campaign id. Get it from campaigns.list.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"content":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"audience":{"type":"object","properties":{"kind":{"type":"string","const":"segment"},"segmentId":{"type":"string","minLength":1}},"required":["kind","segmentId"],"description":"Who receives it: a segment id from segments.list. New drafts default to the all-subscribers segment."}}},"example":{"audience":{"kind":"segment","segmentId":"seg_example01"}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"channel":{"type":"string"},"status":{"type":"string"},"content":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Channel content (email: subject, previewText, blocks...). Media-library images appear as asset:<assetId>."},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"description":"The media-library images the content uses, by assetId."},"audience":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"segment"},"segmentId":{"type":"string","minLength":1}},"required":["kind","segmentId"],"additionalProperties":false,"description":"Who receives it: a segment id from segments.list. New drafts default to the all-subscribers segment."},{"type":"null"}]},"scheduledAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipientCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"updatedAt":{"type":"string"},"timeZone":{"type":"string"}},"required":["id","name","channel","status","content","assets","audience","scheduledAt","recipientCount","updatedAt","timeZone"],"additionalProperties":false},"example":{"id":"camp_example01","name":"October seasonal bake","channel":"EMAIL","status":"DRAFT","content":{"subject":"October special: chestnut croissants are here","body":"This month we're baking..."},"assets":{},"audience":{"kind":"segment","segmentId":"seg_example01"},"scheduledAt":null,"recipientCount":320,"updatedAt":"2026-10-06T08:00:00.000Z","timeZone":"Asia/Taipei"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"campaigns.update_draft","x-kanorio-mcp-tool":"campaigns_update_draft","x-kanorio-required-scope":"marketing:send","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/media":{"get":{"operationId":"media_list","summary":"media.list","description":"List the website's media library (the same files the user sees in the dashboard): images, videos, audio, PDFs, documents and product files, newest first, plus storage usage. Filter with assetKind, unusedOnly and search (file name); pages hold 40 files, so pass offset to continue while hasMore is true. Files in the trash and older versions kept after media.replace are not listed; files in the trash still count toward storage. Errors: FORBIDDEN.","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"assetKind","in":"query","required":false,"description":"Only this kind of file; all kinds by default.","schema":{"description":"Only this kind of file; all kinds by default.","type":"string","enum":["image","video","audio","pdf","document","product"]},"example":"image"},{"name":"unusedOnly","in":"query","required":false,"description":"Only files no content uses (candidates for cleaning up storage).","schema":{"description":"Only files no content uses (candidates for cleaning up storage).","anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"example":false},{"name":"search","in":"query","required":false,"description":"Part of the file name.","schema":{"description":"Part of the file name.","type":"string","maxLength":100}},{"name":"sort","in":"query","required":false,"description":"newest (default), oldest or largest.","schema":{"description":"newest (default), oldest or largest.","type":"string","enum":["newest","oldest","largest"]}},{"name":"offset","in":"query","required":false,"description":"Number of items to skip.","schema":{"description":"Number of items to skip.","type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Files matching the filters."},"hasMore":{"type":"boolean"},"usage":{"type":"object","properties":{"totalBytes":{"type":"number"},"quotaBytes":{"type":"number","description":"Bytes counted against the plan storage limit: every user-uploaded original (images, media, product files, form attachments). Platform-generated derivatives (favicon, auto OG images, map previews) are excluded."},"fileCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["totalBytes","quotaBytes","fileCount"],"additionalProperties":false}},"required":["assets","total","hasMore","usage"],"additionalProperties":false},"example":{"assets":[{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"sunny-bakery-hero.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":true,"createdAt":"2026-10-01T02:30:00.000Z"}],"total":1,"hasMore":false,"usage":{"totalBytes":482133,"quotaBytes":5368709120,"fileCount":1}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.list","x-kanorio-mcp-tool":"media_list","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"media_upload","summary":"media.upload","description":"Upload one image into the website's media library. Provide exactly one of base64 or url. Files the user attaches in chat are not available to you: use media.create_upload_link for those, media.list_page_images for a page the user owns, or media.search_stock when they have no photos. Returns the asset: put asset.url in sections (pages.replace_sections), blog posts and product images, and keep asset.assetId to manage the file later (media.get, media.replace, media.trash). Uploads are kept; unused files show as unused in the media library. Errors: FORBIDDEN, VALIDATION, INVALID_IMAGE_DATA, UNSUPPORTED_IMAGE_TYPE, FILE_TOO_LARGE, FETCH_FAILED, UPLOAD_FAILED, STORAGE_LIMIT_EXCEEDED (plan storage is full; images count toward it).","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"base64":{"description":"Image bytes as base64 (plain or data: URL). JPEG, PNG, WebP, GIF, SVG or HEIC, max 40 MB decoded; originals are stored as-is (only downscaled when over Cloudflare limits).","type":"string","minLength":1,"maxLength":55924118},"url":{"description":"Public https URL serving image/* under 40 MB. Private networks and redirects to them are rejected.","type":"string","maxLength":2048,"format":"uri"},"usage":{"description":"Hint for bookkeeping: content (default), blog, product, favicon.","type":"string","maxLength":40}}},"example":{"url":"https://example.com/photos/croissant.jpg"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false}},"required":["asset"],"additionalProperties":false},"example":{"asset":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"croissant.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":false,"createdAt":"2026-10-06T08:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.upload","x-kanorio-mcp-tool":"media_upload","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/media/upload-links":{"post":{"operationId":"media_create_upload_link","summary":"media.create_upload_link","description":"Create a short-lived (15 min) upload page the user opens on their phone or computer to send you photos. Use it whenever the user offers photos in the conversation: chat clients never pass attachments to tools, so you cannot see or upload those files yourself and must not pretend you did. Reply to the user with the returned url in plain words (e.g. 'Open this link and add your photos, then tell me when you're done'). Afterwards call media.upload_link_status with the same token to get the uploaded images. Errors: FORBIDDEN, SERVICE_UNAVAILABLE (try again shortly).","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"maxFiles":{"description":"How many photos the link accepts (default 10, max 20).","type":"integer","minimum":1,"maximum":20},"purpose":{"description":"Shown on the upload page in the user's words, e.g. 'menu photos' or 'storefront and team'.","type":"string","minLength":1,"maxLength":80}}},"example":{"maxFiles":6,"purpose":"menu photos"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Give this to the user."},"token":{"type":"string","description":"Keep it to call media.upload_link_status."},"linkId":{"type":"string"},"expiresAt":{"type":"string"},"maxFiles":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["url","token","linkId","expiresAt","maxFiles"],"additionalProperties":false},"example":{"url":"https://app.kanorio.com/u/example-upload-link-token","token":"example-upload-link-token","linkId":"lnk_example01","expiresAt":"2026-10-06T08:00:00.000Z","maxFiles":6}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.create_upload_link","x-kanorio-mcp-tool":"media_create_upload_link","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/media/upload-links/status":{"get":{"operationId":"media_upload_link_status","summary":"media.upload_link_status","description":"Check what the user has uploaded through an upload link (media.create_upload_link). Call it when the user says they are done, or to poll every 20-30 seconds while waiting. Returns the uploaded images as assets (put asset.url in sections, keep assetId to manage them) and how many more the link accepts. The status stays readable for a few minutes after the link expires. Errors: FORBIDDEN, LINK_INVALID (token does not belong to this website or is malformed).","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"token","in":"query","required":true,"description":"The token returned by media.create_upload_link.","schema":{"type":"string","minLength":1,"maxLength":1024,"description":"The token returned by media.create_upload_link."},"example":"example-upload-link-token"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"linkId":{"type":"string"},"expiresAt":{"type":"string"},"maxFiles":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"uploadedCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"purpose":{"anyOf":[{"type":"string"},{"type":"null"}]},"assets":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"},"uploadedAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt","uploadedAt"],"additionalProperties":false}}},"required":["linkId","expiresAt","maxFiles","uploadedCount","remaining","purpose","assets"],"additionalProperties":false},"example":{"linkId":"lnk_example01","expiresAt":"2026-10-06T08:00:00.000Z","maxFiles":6,"uploadedCount":2,"remaining":4,"purpose":"menu photos","assets":[{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"menu-front.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":false,"createdAt":"2026-10-06T08:00:00.000Z","uploadedAt":"2026-10-06T08:00:00.000Z"},{"assetId":"asset_example02","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"menu-back.jpg","mimeType":"image/jpeg","bytes":391204,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":false,"createdAt":"2026-10-06T08:00:00.000Z","uploadedAt":"2026-10-06T08:00:00.000Z"}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.upload_link_status","x-kanorio-mcp-tool":"media_upload_link_status","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/media/stock":{"get":{"operationId":"media_search_stock","summary":"media.search_stock","description":"Search free stock photos (Pexels and Pixabay) when the user has no photos of their own. Ask the user first whether they have photos; use stock as the fallback and tell them the images are stock photos they can replace later. Write the query in English with concrete nouns (e.g. 'sourdough bread bakery counter', not 'nice bakery'); add orientation=landscape for hero backgrounds. Both libraries allow commercial use without attribution; do not use stock photos as the brand logo or to imply endorsement. Pick a hit, then call media.import_stock to copy it into the website's media library. Errors: FORBIDDEN, SEARCH_BUSY (retry after details.retryAfter seconds), SEARCH_FAILED, UNKNOWN_PROVIDER.","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website the photos are for (scopes the token's access).","schema":{"type":"string"}},{"name":"query","in":"query","required":true,"description":"English search terms work best.","schema":{"type":"string","minLength":1,"maxLength":100,"description":"English search terms work best."},"example":"sourdough bread bakery counter"},{"name":"orientation","in":"query","required":false,"schema":{"type":"string","enum":["landscape","portrait","square"]},"example":"landscape"},{"name":"provider","in":"query","required":false,"description":"Defaults to all (results interleaved).","schema":{"description":"Defaults to all (results interleaved).","type":"string","enum":["all","pexels","pixabay"]}},{"name":"perPage","in":"query","required":false,"description":"Defaults to 9.","schema":{"description":"Defaults to 9.","type":"integer","minimum":3,"maximum":12},"example":3},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string","description":"pexels or pixabay."},"previewURL":{"type":"string","description":"Small preview; do not put this in sections."},"displayURL":{"type":"string"},"downloadURL":{"type":"string","description":"Pass to media.import_stock together with id and provider."},"width":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"height":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"photographerName":{"type":"string"},"photoPageURL":{"type":"string"},"alt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","provider","previewURL","displayURL","downloadURL","width","height","photographerName","photoPageURL","alt"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"type":"boolean"}},"required":["hits","total","hasMore"],"additionalProperties":false},"example":{"hits":[{"id":"1234567","provider":"pexels","previewURL":"https://images.pexels.com/photos/1234567/pexels-photo-1234567.jpeg?w=280","displayURL":"https://images.pexels.com/photos/1234567/pexels-photo-1234567.jpeg?w=1280","downloadURL":"https://images.pexels.com/photos/1234567/pexels-photo-1234567.jpeg","width":4000,"height":2667,"photographerName":"Example Photographer","photoPageURL":"https://www.pexels.com/photo/1234567/","alt":"Sourdough loaves on a wooden counter"}],"total":1,"hasMore":false}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.search_stock","x-kanorio-mcp-tool":"media_search_stock","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"post":{"operationId":"media_import_stock","summary":"media.import_stock","description":"Copy one stock photo from media.search_stock into the website's media library. Pass provider, id and downloadURL exactly as returned by the search. Returns the asset: put asset.url in sections (backgroundImage, images[].url) and keep asset.assetId to manage it. Write the imageAlt yourself in the site's content language, based on the photo's alt and the section's purpose. Errors: FORBIDDEN, UNKNOWN_PROVIDER, INVALID_STOCK_URL, STOCK_BUSY, INVALID_IMAGE_DATA, UPLOAD_FAILED, STORAGE_LIMIT_EXCEEDED.","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["pexels","pixabay"]},"id":{"type":"string","minLength":1,"maxLength":64,"description":"Stock photo id from the search result."},"downloadURL":{"type":"string","maxLength":2048,"format":"uri","description":"downloadURL from the search result."},"usage":{"description":"Bookkeeping hint: content (default), blog, product.","type":"string","maxLength":40}},"required":["provider","id","downloadURL"]},"example":{"provider":"pexels","id":"1234567","downloadURL":"https://images.pexels.com/photos/1234567/pexels-photo-1234567.jpeg"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false}},"required":["asset"],"additionalProperties":false},"example":{"asset":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"pexels-1234567.jpeg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":false,"createdAt":"2026-10-06T08:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.import_stock","x-kanorio-mcp-tool":"media_import_stock","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/media/page-images":{"get":{"operationId":"media_list_page_images","summary":"media.list_page_images","description":"List the images found on a public web page (its cover image, content images and logo) when the user points you to a site they own, such as their old website or a brand page. Nothing is downloaded; pick the ones you need and copy them with media.upload (url mode). Before copying, confirm with the user that the images are theirs or they have the right to use them; do not copy images from sites that are not the user's. Pages behind a login or anti-bot walls (Instagram, Facebook) fail with FETCH_FAILED: ask the user to use an upload link instead. Errors: FORBIDDEN, INVALID_URL (private or non-http address), FETCH_FAILED (details.status is the upstream status).","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website the images are for (scopes the token's access).","schema":{"type":"string"}},{"name":"url","in":"query","required":true,"schema":{"type":"string","maxLength":2048,"format":"uri"},"example":"https://old-site.example.com/"},{"name":"max","in":"query","required":false,"description":"Defaults to 12.","schema":{"description":"Defaults to 12.","type":"integer","minimum":1,"maximum":20},"example":5}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"pageUrl":{"type":"string"},"finalUrl":{"type":"string","description":"After redirects."},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"siteName":{"anyOf":[{"type":"string"},{"type":"null"}]},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"role":{"type":"string","enum":["cover","content","logo"]},"ownAsset":{"type":"boolean","description":"false when hosted on a website-builder CDN (likely a platform asset, not the brand's)."}},"required":["url","role","ownAsset"],"additionalProperties":false}}},"required":["pageUrl","finalUrl","title","siteName","images"],"additionalProperties":false},"example":{"pageUrl":"https://old-site.example.com/","finalUrl":"https://old-site.example.com/","title":"Sunny Bakery","siteName":"Sunny Bakery","images":[{"url":"https://old-site.example.com/images/og.jpg","role":"cover","ownAsset":true},{"url":"https://old-site.example.com/images/logo.png","role":"logo","ownAsset":true},{"url":"https://old-site.example.com/images/croissant.jpg","role":"content","ownAsset":true}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.list_page_images","x-kanorio-mcp-tool":"media_list_page_images","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/media/{assetId}":{"get":{"operationId":"media_get","summary":"media.get","description":"Get one file from the media library or the trash, with every place the site uses it (page sections, share images, brand, posts, products, emails). Errors: FORBIDDEN, ASSET_NOT_FOUND.","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"assetId","in":"path","required":true,"description":"Asset id from media.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false},"usages":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"pageSection, pageShare, siteContent, brand, favicon, watermark, post, blogTaxonomy, product, productContent, productCategory, collectionItem, floatingWidgets, messageTemplate or campaign."},"label":{"type":"string","description":"Where it is used, in words you can repeat to the user (page › section, post title, product name…)."}},"required":["kind","label"],"additionalProperties":false},"description":"Empty when no content uses the file."}},"required":["asset","usages"],"additionalProperties":false},"example":{"asset":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":1,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"sunny-bakery-hero.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":true,"createdAt":"2026-10-01T02:30:00.000Z"},"usages":[{"kind":"pageSection","label":"Home › Our story"},{"kind":"brand","label":"Brand logo"}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.get","x-kanorio-mcp-tool":"media_get","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"},"delete":{"operationId":"media_purge","summary":"media.purge","description":"Permanently delete a file that is already in the trash (call media.trash first) and free its storage. This cannot be undone. If the site still uses the file, the call fails with ASSET_IN_USE and details.usages: tell the user those places will stay empty, and only retry with confirm: true after they agree. Errors: FORBIDDEN, NOT_FOUND, NOT_IN_TRASH, PRODUCT_FILE_PROTECTED, ASSET_IN_USE, EXPORT_HOLD (details.until: an export keeps the file until then), DELETE_FAILED.","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"assetId","in":"path","required":true,"description":"Asset id from media.list.","schema":{"type":"string"}},{"name":"confirm","in":"query","required":false,"description":"Set true (REST: ?confirm=true) only after the user agreed that the places in ASSET_IN_USE details.usages will stay empty.","schema":{"description":"Set true (REST: ?confirm=true) only after the user agreed that the places in ASSET_IN_USE details.usages will stay empty.","anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"assetId":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["assetId","deleted"],"additionalProperties":false},"example":{"assetId":"asset_example01","deleted":true}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.purge","x-kanorio-mcp-tool":"media_purge","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/media/{assetId}/replace":{"post":{"operationId":"media_replace","summary":"media.replace","description":"Upload a new version of an image (exactly one of base64 or url). Every place that uses it switches to the new version and keeps the same assetId, so no content needs to be edited: the editor, brand logo, share images, products and blog posts right away; published pages after the next site.publish (awaitingPublish). When the aspect ratio changes, crops are re-centered per layout (aspectRatioChanged): tell the user to check the pages listed in usages. Tell the user before replacing a file that many places use. Only images; videos, audio, PDFs and documents are replaced in the dashboard media library. The older version stays until no published page uses it, then moves to the trash. Errors: FORBIDDEN, ASSET_NOT_FOUND (also for files in the trash), IMAGES_ONLY, REPLACE_NOT_AVAILABLE, VALIDATION, INVALID_IMAGE_DATA, UNSUPPORTED_IMAGE_TYPE, FILE_TOO_LARGE, FETCH_FAILED, STORAGE_LIMIT_EXCEEDED, SERVICE_UNAVAILABLE, UPLOAD_FAILED.","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"assetId","in":"path","required":true,"description":"Asset id from media.list.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"base64":{"description":"Image bytes as base64 (plain or data: URL). JPEG, PNG, WebP, GIF, SVG or HEIC, max 40 MB decoded; originals are stored as-is (only downscaled when over Cloudflare limits).","type":"string","minLength":1,"maxLength":55924118},"url":{"description":"Public https URL serving image/* under 40 MB. Private networks and redirects to them are rejected.","type":"string","maxLength":2048,"format":"uri"}}},"example":{"url":"https://example.com/photos/hero-2026.jpg"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false,"description":"The file after the replacement (version increased)."},"usages":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"pageSection, pageShare, siteContent, brand, favicon, watermark, post, blogTaxonomy, product, productContent, productCategory, collectionItem, floatingWidgets, messageTemplate or campaign."},"label":{"type":"string","description":"Where it is used, in words you can repeat to the user (page › section, post title, product name…)."}},"required":["kind","label"],"additionalProperties":false},"description":"Places that now show the new version."},"awaitingPublish":{"type":"boolean","description":"Published pages still show the older version until the site is published again."},"aspectRatioChanged":{"type":"boolean"}},"required":["asset","usages","awaitingPublish","aspectRatioChanged"],"additionalProperties":false},"example":{"asset":{"assetId":"asset_example01","kind":"image","status":"active","missing":false,"version":2,"url":"https://media.kanorio.com/example/sunny-bakery-hero.jpg","thumbnailUrl":null,"fileName":"sunny-bakery-hero.jpg","mimeType":"image/jpeg","bytes":482133,"width":2400,"height":1600,"durationSeconds":null,"pageCount":null,"source":"IMAGE_CONTENT","inUse":true,"createdAt":"2026-10-01T02:30:00.000Z"},"usages":[{"kind":"pageSection","label":"Home › Our story"}],"awaitingPublish":true,"aspectRatioChanged":false}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.replace","x-kanorio-mcp-tool":"media_replace","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/media/{assetId}/trash":{"post":{"operationId":"media_trash","summary":"media.trash","description":"Move a file to the trash. It stops showing on the site right away (places that use it show nothing), still counts toward storage, and is deleted permanently after 30 days unless restored with media.restore. The response lists where it was used so you can tell the user what will look empty. Product files cannot be trashed; remove them from the product instead. Errors: FORBIDDEN, NOT_FOUND, PRODUCT_FILE_PROTECTED.","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"assetId","in":"path","required":true,"description":"Asset id from media.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"assetId":{"type":"string"},"usages":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","description":"pageSection, pageShare, siteContent, brand, favicon, watermark, post, blogTaxonomy, product, productContent, productCategory, collectionItem, floatingWidgets, messageTemplate or campaign."},"label":{"type":"string","description":"Where it is used, in words you can repeat to the user (page › section, post title, product name…)."}},"required":["kind","label"],"additionalProperties":false},"description":"Places on the site that now show nothing; empty when the file was unused."},"deleteAfter":{"type":"string","description":"ISO time after which the file is deleted permanently."}},"required":["assetId","usages","deleteAfter"],"additionalProperties":false},"example":{"assetId":"asset_example01","usages":[{"kind":"pageSection","label":"Home › Our story"}],"deleteAfter":"2026-11-05T08:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.trash","x-kanorio-mcp-tool":"media_trash","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/media/{assetId}/restore":{"post":{"operationId":"media_restore","summary":"media.restore","description":"Restore a file from the trash; it shows on the site again right away. An older version left by replacing a file comes back as a separate file with a new assetId (returned); old content keeps showing the current version. Errors: FORBIDDEN, NOT_FOUND, PRODUCT_FILE_PROTECTED, RESTORE_FAILED.","tags":["media"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"assetId","in":"path","required":true,"description":"Asset id from media.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"assetId":{"type":"string"}},"required":["assetId"],"additionalProperties":false},"example":{"assetId":"asset_example01"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"media.restore","x-kanorio-mcp-tool":"media_restore","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/analytics/overview":{"get":{"operationId":"analytics_overview","summary":"analytics.overview","description":"Get website traffic overview for the selected period (default 30 days): pageviews, unique visitors, sessions, button clicks, form submissions, external link clicks, top traffic sources, UTM campaigns, and countries. Errors: FORBIDDEN.","tags":["analytics"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Number of days to aggregate (1 to 90, defaults to 30).","schema":{"description":"Number of days to aggregate (1 to 90, defaults to 30).","type":"integer","minimum":1,"maximum":90},"example":30}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totals":{"type":"object","properties":{"pageviews":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"uniqueVisitors":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sessions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clicks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"formSubmits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"socialClicks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["pageviews","uniqueVisitors","sessions","clicks","formSubmits","socialClicks"],"additionalProperties":false},"devices":{"type":"object","properties":{"mobile":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"desktop":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tablet":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["mobile","desktop","tablet"],"additionalProperties":false},"topSources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Channel, button, link, or country identifier."},"value":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Count in the selected period."}},"required":["name","value"],"additionalProperties":false}},"topUtm":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Channel, button, link, or country identifier."},"value":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Count in the selected period."}},"required":["name","value"],"additionalProperties":false}},"topButtons":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Channel, button, link, or country identifier."},"value":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Count in the selected period."}},"required":["name","value"],"additionalProperties":false}},"topCountries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Channel, button, link, or country identifier."},"value":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Count in the selected period."}},"required":["name","value"],"additionalProperties":false}}},"required":["days","totals","devices","topSources","topUtm","topButtons","topCountries"],"additionalProperties":false},"example":{"days":30,"totals":{"pageviews":4820,"uniqueVisitors":1940,"sessions":2310,"clicks":412,"formSubmits":38,"socialClicks":185},"devices":{"mobile":3120,"desktop":1580,"tablet":120},"topSources":[{"name":"google","value":980},{"name":"instagram","value":540},{"name":"chatgpt","value":112}],"topUtm":[{"name":"october_special","value":210}],"topButtons":[{"name":"Order Now","value":196}],"topCountries":[{"name":"TW","value":1620},{"name":"US","value":210}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"analytics.overview","x-kanorio-mcp-tool":"analytics_overview","x-kanorio-required-scope":"analytics:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/analytics/pages":{"get":{"operationId":"analytics_pages","summary":"analytics.pages","description":"Get per-page traffic, entry sessions, bounce rate, engagement duration, button clicks, and form submissions (excluding transient checkout pages). Errors: FORBIDDEN.","tags":["analytics"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Number of days to aggregate (1 to 90, defaults to 30).","schema":{"description":"Number of days to aggregate (1 to 90, defaults to 30).","type":"integer","minimum":1,"maximum":90},"example":30}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pages":{"type":"array","items":{"type":"object","properties":{"pageId":{"type":"string","description":"Stable page identifier (WebsitePage id or encoded PageRef)."},"kind":{"type":"string","description":"Content kind (page, blog-post, product, shop-index, etc.)."},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL path snapshot."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Page title snapshot."},"pageviews":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"uniqueVisitors":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"entrySessions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bounceRate":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Bounce percentage (0 to 100)."},"avgEngagementSec":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Average foreground engagement time in seconds, weighted by daily pageviews."},"ctaClicks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"formSubmits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["pageId","kind","path","title","pageviews","uniqueVisitors","entrySessions","bounceRate","avgEngagementSec","ctaClicks","formSubmits"],"additionalProperties":false}}},"required":["days","pages"],"additionalProperties":false},"example":{"days":30,"pages":[{"pageId":"pg_example456","kind":"page","path":"/","title":"Home","pageviews":2840,"uniqueVisitors":1420,"entrySessions":1280,"bounceRate":34,"avgEngagementSec":52,"ctaClicks":245,"formSubmits":22}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"analytics.pages","x-kanorio-mcp-tool":"analytics_pages","x-kanorio-required-scope":"analytics:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/analytics/bots":{"get":{"operationId":"analytics_bots","summary":"analytics.bots","description":"Get AI crawler and search bot activity summary (GPTBot, ClaudeBot, PerplexityBot, Googlebot, etc.) for the selected period. Errors: FORBIDDEN.","tags":["analytics"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Number of days to aggregate (1 to 90, defaults to 30).","schema":{"description":"Number of days to aggregate (1 to 90, defaults to 30).","type":"integer","minimum":1,"maximum":90},"example":30}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totals":{"type":"object","properties":{"totalHits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"blockedHits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"verifiedHits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"spoofedHits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["totalHits","blockedHits","verifiedHits","spoofedHits"],"additionalProperties":false},"bots":{"type":"array","items":{"type":"object","properties":{"botToken":{"type":"string"},"totalHits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"blockedHits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"verifiedHits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"spoofedHits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["botToken","totalHits","blockedHits","verifiedHits","spoofedHits"],"additionalProperties":false}}},"required":["days","totals","bots"],"additionalProperties":false},"example":{"days":30,"totals":{"totalHits":640,"blockedHits":0,"verifiedHits":590,"spoofedHits":12},"bots":[{"botToken":"GPTBot","totalHits":310,"blockedHits":0,"verifiedHits":302,"spoofedHits":2}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"analytics.bots","x-kanorio-mcp-tool":"analytics_bots","x-kanorio-required-scope":"analytics:view","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/revisions":{"get":{"operationId":"revisions_list","summary":"revisions.list","description":"List content revisions for a website draft (subject: WEBSITE, subjectId omitted or equal to websiteId) or a blog post (subject: BLOG_POST, subjectId: postId). Revisions are retained for 30 days and coalesced within 10-minute autosave windows. Optionally pass pageId when listing WEBSITE revisions to filter to edits that touched that page. Errors: FORBIDDEN.","tags":["revisions"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"subject","in":"query","required":false,"description":"Defaults to WEBSITE.","schema":{"description":"Defaults to WEBSITE.","type":"string","enum":["WEBSITE","BLOG_POST"]},"example":"WEBSITE"},{"name":"subjectId","in":"query","required":false,"description":"Required when subject is BLOG_POST (pass the postId); defaults to websiteId for WEBSITE.","schema":{"description":"Required when subject is BLOG_POST (pass the postId); defaults to websiteId for WEBSITE.","type":"string","minLength":1,"maxLength":64}},{"name":"pageId","in":"query","required":false,"description":"Optional filter for WEBSITE revisions: only revisions that modified this page or whole-site checkpoints.","schema":{"description":"Optional filter for WEBSITE revisions: only revisions that modified this page or whole-site checkpoints.","type":"string","minLength":1,"maxLength":64}},{"name":"limit","in":"query","required":false,"description":"Max revisions to return (1-200, default 50).","schema":{"description":"Max revisions to return (1-200, default 50).","type":"integer","minimum":1,"maximum":200},"example":20}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"revisions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"websiteId":{"type":"string"},"subject":{"type":"string","enum":["WEBSITE","BLOG_POST"],"description":"Subject type: WEBSITE for site-wide draft and page sections, BLOG_POST for a blog article."},"subjectId":{"type":"string"},"kind":{"type":"string","enum":["AUTO","PUBLISH","PRE_RESTORE","PRE_AI","MANUAL"],"description":"Why the revision was recorded."},"schemaVersion":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"contentHash":{"type":"string"},"summary":{"anyOf":[{"type":"object","properties":{"title":{"type":"string"},"editedPageIds":{"type":"array","items":{"type":"string"}},"editedPageTitles":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"editedScopes":{"type":"array","items":{"type":"string","enum":["sections","header","footer","siteSettings","theme","pages"]}}},"additionalProperties":false},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"actor":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"isAgent":{"type":"boolean","description":"True when the revision was written through an API token or MCP client."},"tokenName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","email","image","isAgent"],"additionalProperties":false},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","websiteId","subject","subjectId","kind","schemaVersion","contentHash","summary","label","actor","createdAt","updatedAt"],"additionalProperties":false}}},"required":["revisions"],"additionalProperties":false},"example":{"revisions":[{"id":"rev_example01","websiteId":"ws_example123","subject":"WEBSITE","subjectId":"ws_example123","kind":"AUTO","schemaVersion":1,"contentHash":"a1b2c3d4:1240","summary":{"editedPageIds":["pg_example456"],"editedPageTitles":{"pg_example456":"Home"},"editedScopes":["sections"]},"label":null,"actor":{"id":"usr_example01","name":"Sunny Lin","email":"sunny@example.com","image":null,"isAgent":true,"tokenName":"Cursor MCP"},"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"revisions.list","x-kanorio-mcp-tool":"revisions_list","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/revisions/{revisionId}":{"get":{"operationId":"revisions_get","summary":"revisions.get","description":"Get the full unpacked snapshot of a content revision by revisionId. Media references belonging to this site's library are presented as asset:<assetId> with display metadata in assets. Errors: FORBIDDEN, REVISION_NOT_FOUND.","tags":["revisions"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"revisionId","in":"path","required":true,"description":"Revision identifier from revisions.list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"object","properties":{"id":{"type":"string"},"websiteId":{"type":"string"},"subject":{"type":"string","enum":["WEBSITE","BLOG_POST"],"description":"Subject type: WEBSITE for site-wide draft and page sections, BLOG_POST for a blog article."},"subjectId":{"type":"string"},"kind":{"type":"string","enum":["AUTO","PUBLISH","PRE_RESTORE","PRE_AI","MANUAL"],"description":"Why the revision was recorded."},"schemaVersion":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"contentHash":{"type":"string"},"summary":{"anyOf":[{"type":"object","properties":{"title":{"type":"string"},"editedPageIds":{"type":"array","items":{"type":"string"}},"editedPageTitles":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"editedScopes":{"type":"array","items":{"type":"string","enum":["sections","header","footer","siteSettings","theme","pages"]}}},"additionalProperties":false},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"actor":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"isAgent":{"type":"boolean","description":"True when the revision was written through an API token or MCP client."},"tokenName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","email","image","isAgent"],"additionalProperties":false},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","websiteId","subject","subjectId","kind","schemaVersion","contentHash","summary","label","actor","createdAt","updatedAt"],"additionalProperties":false},"snapshot":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"assets":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"assetId":{"type":"string","description":"Stable id of the file. Reference files by this id; it stays the same when media.replace uploads a new version."},"kind":{"type":"string","enum":["image","video","audio","pdf","document","product"],"description":"product = a paid digital file (private, managed in Products)."},"status":{"type":"string","enum":["active","trash"],"description":"trash = in the trash: not shown on the site, restorable with media.restore."},"missing":{"type":"boolean","description":"true when the original no longer exists; places that use it show nothing."},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases each time media.replace uploads a new version."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display URL for showing the file to the user. It changes with each version, so never store it; null for product files."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"fileName":{"anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"type":"string"},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null while the size of an older file is still being calculated."},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"pageCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string","description":"Where it was uploaded (page module, blog, product, media library…)."},"inUse":{"type":"boolean","description":"Used by site content, products, emails or a published snapshot."},"createdAt":{"type":"string"}},"required":["assetId","kind","status","missing","version","url","thumbnailUrl","fileName","mimeType","bytes","width","height","durationSeconds","pageCount","source","inUse","createdAt"],"additionalProperties":false}}},"required":["revision","snapshot","assets"],"additionalProperties":false},"example":{"revision":{"id":"rev_example01","websiteId":"ws_example123","subject":"WEBSITE","subjectId":"ws_example123","kind":"AUTO","schemaVersion":1,"contentHash":"a1b2c3d4:1240","summary":{"editedPageIds":["pg_example456"],"editedPageTitles":{"pg_example456":"Home"},"editedScopes":["sections"]},"label":null,"actor":{"id":"usr_example01","name":"Sunny Lin","email":"sunny@example.com","image":null,"isAgent":true,"tokenName":"Cursor MCP"},"createdAt":"2026-10-01T02:30:00.000Z","updatedAt":"2026-10-06T08:00:00.000Z"},"snapshot":{"siteSettings":{},"globalSections":[],"themeSettings":{"sectionDensity":"standard","cornerRadius":"normal","colorScheme":"system"},"pages":[{"id":"pg_example456","slug":"/","title":"Home","isHomePage":true,"sections":[]}]},"assets":{}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"revisions.get","x-kanorio-mcp-tool":"revisions_get","x-kanorio-required-scope":"editor:enter","x-kanorio-read-only":true,"x-kanorio-rate-limit":"agent (120/minute per token)"}},"/sites/{id}/revisions/{revisionId}/restore":{"post":{"operationId":"revisions_restore","summary":"revisions.restore","description":"Restore a website draft or blog post working copy to a previous revision. Before writing, the current draft is automatically backed up as a PRE_RESTORE revision so the restore itself can be undone. Restoring writes only to the draft/working copy and never alters the live published site directly; call site.publish or posts.publish to publish. For WEBSITE revisions, pass mode: \"page\" with pageId to restore only a single page's sections, or mode: \"full\" (default) to restore the entire site draft and theme settings. Errors: FORBIDDEN, REVISION_NOT_FOUND, SUBJECT_NOT_FOUND, PAGE_NOT_FOUND_IN_REVISION, PAGE_NOT_FOUND_IN_SITE, VALIDATION_FAILED, WRITE_FROZEN.","tags":["revisions"],"x-kanorio-stability":"beta","parameters":[{"name":"id","in":"path","required":true,"description":"Website id. Get it from sites.list or from sites.create.","schema":{"type":"string"}},{"name":"revisionId","in":"path","required":true,"description":"Revision identifier from revisions.list.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"description":"Defaults to \"full\". Use \"page\" with pageId to restore only one page of a WEBSITE revision.","type":"string","enum":["full","page"]},"pageId":{"description":"Required when mode is \"page\".","type":"string","minLength":1,"maxLength":64}}},"example":{"mode":"page","pageId":"pg_example456"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"restored":{"type":"boolean","const":true},"subject":{"type":"string","enum":["WEBSITE","BLOG_POST"],"description":"Subject type: WEBSITE for site-wide draft and page sections, BLOG_POST for a blog article."},"subjectId":{"type":"string"},"revisionId":{"type":"string"},"preRestoreRevisionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"kind":{"type":"string","enum":["AUTO","PUBLISH","PRE_RESTORE","PRE_AI","MANUAL"],"description":"Why the revision was recorded."},"mode":{"type":"string","enum":["full","page"]},"pageId":{"description":"Resolved page id when mode is page.","type":"string"}},"required":["restored","subject","subjectId","revisionId","preRestoreRevisionId","kind","mode"],"additionalProperties":false},"example":{"restored":true,"subject":"WEBSITE","subjectId":"ws_example123","revisionId":"rev_example01","preRestoreRevisionId":"rev_backup01","kind":"AUTO","mode":"page"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"security":[{"personalAccessToken":[]}],"x-kanorio-capability":"revisions.restore","x-kanorio-mcp-tool":"revisions_restore","x-kanorio-required-scope":"content:edit","x-kanorio-read-only":false,"x-kanorio-rate-limit":"agent (120/minute per token)"}}},"components":{"securitySchemes":{"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"knr_pat_…","description":"Personal access token created at https://app.kanorio.com/account/api-access. Effective permission = token scopes ∩ the user's website member permissions."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 (PKCE S256, RFC 8707 resource = https://app.kanorio.com/api/mcp). Access tokens issued here are honoured by the MCP endpoint; REST accepts personal access tokens only.","flows":{"authorizationCode":{"authorizationUrl":"https://app.kanorio.com/oauth/authorize","tokenUrl":"https://app.kanorio.com/oauth/token","refreshUrl":"https://app.kanorio.com/oauth/token","scopes":{"console:view":"console:view","editor:enter":"editor:enter","analytics:view":"analytics:view","posts:view":"posts:view","store:view":"store:view","customers:view":"customers:view","marketing:view":"marketing:view","billing:view":"billing:view","orders:view":"orders:view","payments:view":"payments:view","collections:view":"collections:view","site:manage_settings":"site:manage_settings","site:lifecycle":"site:lifecycle","site:integrations":"site:integrations","messaging:settings":"messaging:settings","content:edit":"content:edit","blog:manage":"blog:manage","collections:manage":"collections:manage","commerce:manage":"commerce:manage","customers:manage":"customers:manage","marketing:manage":"marketing:manage","marketing:send":"marketing:send"}}}}},"schemas":{"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"English, one sentence, safe to show to the agent."},"details":{"description":"Structured details for the code (e.g. Zod issues, latest updatedAt, requiredScope)."}}}}},"ErrorCode":{"type":"string","description":"Stable error code. Codes not listed here follow the suffix rules: *_NOT_FOUND → 404, *_REQUIRED / *_FORBIDDEN / *_PLAN_REQUIRED / *_LIMIT → 403, otherwise 422.","enum":["EMPTY_SLUG","INVALID_BODY","INVALID_EDITED_PATH","INVALID_FORMAT","INVALID_ORDER","INVALID_SUBDOMAIN","UNSUPPORTED_EDITED_PATH","VALIDATION","UNAUTHENTICATED","UNAUTHORIZED","CUSTOM_DOMAIN_CHANGE_FORBIDDEN","CUSTOM_DOMAIN_LIMIT_REACHED","FORBIDDEN","FREE_VISIBLE_MODULE_LIMIT","FREE_VISIBLE_PAGE_LIMIT","LIMIT_REACHED","MODERATION_LOCKED","OWNER_REQUIRED","PLAN_CANNOT_PUBLISH","PRO_REQUIRED","PRODUCT_PAGES_PLAN_REQUIRED","REDIRECT_LIMIT","SUBDOMAIN_CHANGE_FORBIDDEN","TOKEN_WEBSITE_SCOPED","HEADER_NOT_FOUND","HOME_PAGE_NOT_FOUND","NOT_FOUND","OWNER_NOT_FOUND","PAGE_NOT_FOUND","PARENT_NOT_FOUND","PRODUCT_NOT_FOUND","WEBSITE_NOT_FOUND","METHOD_NOT_ALLOWED","CONFLICT","CUSTOM_DOMAIN_TAKEN","HAS_CHILDREN","HOSTNAME_CONFLICT","KEY_TAKEN","PRIMARY_HEADER_PROTECTED","READD_COOLDOWN","REDIRECT_CONFLICT","SLUG_TAKEN","SUBDOMAIN_TAKEN","TAKEN","BLOCKED","BREADCRUMB_PARENT_INVALID","CONTENT_VALIDATION_FAILED","CUSTOM_DOMAIN_BLOCKED","CUSTOM_DOMAIN_HIGH_RISK_TLD","CUSTOM_DOMAIN_TOO_LONG","DEPTH_EXCEEDED","DOMAIN_CHANGE_NOT_ALLOWED","EMPTY_CONTENT","FOREIGN_PAGE","HIGH_RISK_TLD","HOME_HAS_HIERARCHY","HOME_NOT_CREATABLE","HOME_NOT_DELETABLE","HOME_NOT_SORTABLE","HOME_SLUG_IMMUTABLE","LINK_IN_BIO_DEDICATED_ENTRY","LINK_IN_BIO_NOT_DUPLICABLE","PARENT_NOT_ALLOWED","RESERVED_SEGMENT","RESERVED_SLUG","RESERVED_SUBDOMAIN","SANITIZE_FAILED","SEGMENT_TOO_LONG","SUBDOMAIN_MISSING","TEMPLATE_PRODUCT_LOCKED","DAILY_LIMIT_REACHED","RATE_LIMITED","INTERNAL","SERVICE_UNAVAILABLE","WRITE_FROZEN"],"x-kanorio-http-status":{"EMPTY_SLUG":400,"INVALID_BODY":400,"INVALID_EDITED_PATH":400,"INVALID_FORMAT":400,"INVALID_ORDER":400,"INVALID_SUBDOMAIN":400,"UNSUPPORTED_EDITED_PATH":400,"VALIDATION":400,"UNAUTHENTICATED":401,"UNAUTHORIZED":401,"CUSTOM_DOMAIN_CHANGE_FORBIDDEN":403,"CUSTOM_DOMAIN_LIMIT_REACHED":403,"FORBIDDEN":403,"FREE_VISIBLE_MODULE_LIMIT":403,"FREE_VISIBLE_PAGE_LIMIT":403,"LIMIT_REACHED":403,"MODERATION_LOCKED":403,"OWNER_REQUIRED":403,"PLAN_CANNOT_PUBLISH":403,"PRO_REQUIRED":403,"PRODUCT_PAGES_PLAN_REQUIRED":403,"REDIRECT_LIMIT":403,"SUBDOMAIN_CHANGE_FORBIDDEN":403,"TOKEN_WEBSITE_SCOPED":403,"HEADER_NOT_FOUND":404,"HOME_PAGE_NOT_FOUND":404,"NOT_FOUND":404,"OWNER_NOT_FOUND":404,"PAGE_NOT_FOUND":404,"PARENT_NOT_FOUND":404,"PRODUCT_NOT_FOUND":404,"WEBSITE_NOT_FOUND":404,"METHOD_NOT_ALLOWED":405,"CONFLICT":409,"CUSTOM_DOMAIN_TAKEN":409,"HAS_CHILDREN":409,"HOSTNAME_CONFLICT":409,"KEY_TAKEN":409,"PRIMARY_HEADER_PROTECTED":409,"READD_COOLDOWN":409,"REDIRECT_CONFLICT":409,"SLUG_TAKEN":409,"SUBDOMAIN_TAKEN":409,"TAKEN":409,"BLOCKED":422,"BREADCRUMB_PARENT_INVALID":422,"CONTENT_VALIDATION_FAILED":422,"CUSTOM_DOMAIN_BLOCKED":422,"CUSTOM_DOMAIN_HIGH_RISK_TLD":422,"CUSTOM_DOMAIN_TOO_LONG":422,"DEPTH_EXCEEDED":422,"DOMAIN_CHANGE_NOT_ALLOWED":422,"EMPTY_CONTENT":422,"FOREIGN_PAGE":422,"HIGH_RISK_TLD":422,"HOME_HAS_HIERARCHY":422,"HOME_NOT_CREATABLE":422,"HOME_NOT_DELETABLE":422,"HOME_NOT_SORTABLE":422,"HOME_SLUG_IMMUTABLE":422,"LINK_IN_BIO_DEDICATED_ENTRY":422,"LINK_IN_BIO_NOT_DUPLICABLE":422,"PARENT_NOT_ALLOWED":422,"RESERVED_SEGMENT":422,"RESERVED_SLUG":422,"RESERVED_SUBDOMAIN":422,"SANITIZE_FAILED":422,"SEGMENT_TOO_LONG":422,"SUBDOMAIN_MISSING":422,"TEMPLATE_PRODUCT_LOCKED":422,"DAILY_LIMIT_REACHED":429,"RATE_LIMITED":429,"INTERNAL":500,"SERVICE_UNAVAILABLE":503,"WRITE_FROZEN":503}}},"responses":{"Error400":{"description":"Input failed validation or is malformed. Codes: EMPTY_SLUG, INVALID_BODY, INVALID_EDITED_PATH, INVALID_FORMAT, INVALID_ORDER, INVALID_SUBDOMAIN, UNSUPPORTED_EDITED_PATH, VALIDATION.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"VALIDATION","message":"Input does not match the capability schema.","details":[{"path":"sections.0.title","message":"Invalid input: expected string, received undefined","code":"invalid_type"}]}}}}},"Error401":{"description":"Missing or invalid bearer token. Codes: UNAUTHENTICATED, UNAUTHORIZED.","headers":{"WWW-Authenticate":{"description":"Bearer challenge; `resource_metadata` points at the RFC 9728 document.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"UNAUTHORIZED","message":"Missing or invalid bearer token."}}}}},"Error403":{"description":"The token lacks the scope, the user lacks the role, or the plan does not allow it. Codes: CUSTOM_DOMAIN_CHANGE_FORBIDDEN, CUSTOM_DOMAIN_LIMIT_REACHED, FORBIDDEN, FREE_VISIBLE_MODULE_LIMIT, FREE_VISIBLE_PAGE_LIMIT, LIMIT_REACHED, MODERATION_LOCKED, OWNER_REQUIRED, PLAN_CANNOT_PUBLISH, PRO_REQUIRED, PRODUCT_PAGES_PLAN_REQUIRED, REDIRECT_LIMIT, SUBDOMAIN_CHANGE_FORBIDDEN, TOKEN_WEBSITE_SCOPED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"FORBIDDEN","message":"This token lacks the \"content:edit\" scope.","details":{"requiredScope":"content:edit"}}}}}},"Error404":{"description":"Endpoint or resource not found. Codes: HEADER_NOT_FOUND, HOME_PAGE_NOT_FOUND, NOT_FOUND, OWNER_NOT_FOUND, PAGE_NOT_FOUND, PARENT_NOT_FOUND, PRODUCT_NOT_FOUND, WEBSITE_NOT_FOUND.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"PAGE_NOT_FOUND","message":"Page not found."}}}}},"Error405":{"description":"The path exists but not for this method. Codes: METHOD_NOT_ALLOWED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"METHOD_NOT_ALLOWED","message":"The path exists but not for this method."}}}}},"Error409":{"description":"Optimistic-lock conflict, slug/subdomain/hostname taken, or re-add cooldown. Codes: CONFLICT, CUSTOM_DOMAIN_TAKEN, HAS_CHILDREN, HOSTNAME_CONFLICT, KEY_TAKEN, PRIMARY_HEADER_PROTECTED, READD_COOLDOWN, REDIRECT_CONFLICT, SLUG_TAKEN, SUBDOMAIN_TAKEN, TAKEN.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"CONFLICT","message":"The resource changed since you read it; re-read it and retry with the new revision marker (updatedAt / contentUpdatedAt).","details":{"updatedAt":"2026-10-06T08:05:12.000Z"}}}}}},"Error422":{"description":"Business rule rejected the request. Codes: BLOCKED, BREADCRUMB_PARENT_INVALID, CONTENT_VALIDATION_FAILED, CUSTOM_DOMAIN_BLOCKED, CUSTOM_DOMAIN_HIGH_RISK_TLD, CUSTOM_DOMAIN_TOO_LONG, DEPTH_EXCEEDED, DOMAIN_CHANGE_NOT_ALLOWED, EMPTY_CONTENT, FOREIGN_PAGE, HIGH_RISK_TLD, HOME_HAS_HIERARCHY, HOME_NOT_CREATABLE, HOME_NOT_DELETABLE, HOME_NOT_SORTABLE, HOME_SLUG_IMMUTABLE, LINK_IN_BIO_DEDICATED_ENTRY, LINK_IN_BIO_NOT_DUPLICABLE, PARENT_NOT_ALLOWED, RESERVED_SEGMENT, RESERVED_SLUG, RESERVED_SUBDOMAIN, SANITIZE_FAILED, SEGMENT_TOO_LONG, SUBDOMAIN_MISSING, TEMPLATE_PRODUCT_LOCKED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"SITE_NOT_PUBLISHED","message":"Publish the website before publishing blog posts."}}}}},"Error429":{"description":"Rate limit exceeded; honour Retry-After. Codes: DAILY_LIMIT_REACHED, RATE_LIMITED.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded; retry after 30s.","details":{"retryAfter":30}}}}}},"Error500":{"description":"Unexpected server error (already reported). Codes: INTERNAL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"INTERNAL","message":"Unexpected server error."}}}}},"Error503":{"description":"Temporarily unavailable; retry shortly. Codes: SERVICE_UNAVAILABLE, WRITE_FROZEN.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"error":{"code":"WRITE_FROZEN","message":"Content writes are temporarily frozen for maintenance; retry later."}}}}}}},"security":[{"personalAccessToken":[]}],"x-kanorio-mcp":{"url":"https://app.kanorio.com/api/mcp","authorizationServer":"https://app.kanorio.com/.well-known/oauth-authorization-server","protectedResource":"https://app.kanorio.com/.well-known/oauth-protected-resource","serverJson":"https://app.kanorio.com/.well-known/mcp/server.json"}}