REST API

The Kanorio Management REST API allows your backend programs to read and write to your websites directly via HTTPS: create and configure websites, read and write page sections and blog posts, manage collections and digital products, upload media library images, query orders and contacts, as well as publish websites and manage custom domains.

Its underlying capabilities are identical to Connecting an AI Assistant (MCP); the difference lies in how they are invoked:

• Connecting an AI Assistant (MCP): Operated autonomously by AI such as ChatGPT, Claude, or Cursor based on the conversation context.
• Management REST API (this guide): Invoked proactively by your scheduled scripts, custom backends, CI/CD pipelines, or automation nodes using explicit code to call specific endpoints.
• Content Delivery API and Customer API: Public read and member login APIs hosted under your website's own domain (see and ).

Base URL: https://app.kanorio.com/api/v1

Complete Endpoints, Parameters, and Error Codes (SSOT): All endpoint paths, query parameters, Request/Response examples, rate limits, and error code tables are generated in real-time from the code contract on the public Management API Reference page (machine-readable spec: https://app.kanorio.com/api/v1/openapi.json). This guide focuses on authentication, concurrency safety, and deprecation policies.

Authentication and Permission Rules

The REST API only accepts starting with knr_pat_. Please include the Authorization header in every request:

Authorization: Bearer knr_pat_your_key

• How to create a key: Go to "Account Settings › API Access", click "Create Key", select "Other Tools", and check the websites and permission scopes you wish to enable.
• Actual Permission Calculation: $\text{Actual Permissions} = \text{Key Permissions} \cap \text{Your Member Role on the Site}$.
• OAuth tokens not accepted: Connection tokens obtained by clicking "Allow" via ChatGPT or Claude are limited to /api/mcp and cannot be used to call the REST API.

Security Warning: A knr_pat_ key is equivalent to your personal management identity. Always store it in server-side environment variables or a secret management service. Never hardcode keys into browser-side frontend code, mobile apps, or public Git repositories.

Core Writing Mechanism: Draft Boundaries and Optimistic Locking

1. How to get the Website ID (:id)

All site-level endpoint paths start with /sites/:id/.... You can copy the websiteId by going to "Site Settings › General" and scrolling to the bottom, or call GET /api/v1/sites to list all sites accessible by your key.

2. Drafts vs. Immediate Publishing

• Written to draft (requires POST /sites/:id/publish to update the live site): Page sections (PUT .../sections), headers and footers (PUT .../globals/header|footer), site-wide buttons and social links, and site appearance settings. Blog post additions and modifications also only update the working copy; you must call POST .../posts/:postId/publish to make them public.
• Published immediately by default: Collection items (items.* default to publish: true; pass publish: false to save as draft), store products, and digital products.

3. Anti-Overwrite Mechanism (Optimistic Locking ifUnmodifiedSince)

To prevent your scripts from overwriting changes made by team members (or another AI assistant) using the dashboard editor, we use Optimistic Concurrency Control when writing page sections and site-wide navigation:

• Updating page sections (PUT /sites/:id/pages/:pageId/sections): You must first read the page to get the updatedAt timestamp and include ifUnmodifiedSince: "<updatedAt>" in your request.
• Updating headers, footers, and site settings: You must first call GET /sites/:id/globals to get the contentUpdatedAt timestamp and include ifUnmodifiedSince: "<contentUpdatedAt>" in your request.
• If the resource has been modified by someone else since you last read it, the server will reject the write and return 409 CONFLICT (with the latest timestamp). Please re-read, merge, and resubmit.

Quick Start: Four Requests from Read to Publish

Set your key as an environment variable:

export KANORIO_TOKEN="knr_pat_your_key"

1. List sites and get the Website ID

curl -s https://app.kanorio.com/api/v1/sites \
  -H "Authorization: Bearer $KANORIO_TOKEN"

2. Read the page list to get the homepage id and updatedAt

curl -s https://app.kanorio.com/api/v1/sites/ws_example123/pages \
  -H "Authorization: Bearer $KANORIO_TOKEN"

3. Update page section draft with ifUnmodifiedSince

curl -s -X PUT https://app.kanorio.com/api/v1/sites/ws_example123/pages/pg_example456/sections \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ifUnmodifiedSince": "2026-10-15T08:00:00.000Z",
    "sections": [
      {
        "id": "sec_hero_1",
        "type": "page-main-visual",
        "title": "Artisan Bakery",
        "description": "Handcrafted sourdough bread and French pastries, baked fresh every morning."
      }
    ]
  }'

4. Publish the site

curl -s -X POST https://app.kanorio.com/api/v1/sites/ws_example123/publish \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Rate Limits and Deprecation Policy

• Rate Limits: Calculated independently per key—120 requests per minute for general endpoints, 30 requests per hour for publish/unpublish endpoints. Exceeding these returns 429 RATE_LIMITED with a Retry-After header.
• Version and Changelog: All additions and changes are documented in the public API Changelog.
• Deprecation Period: When an endpoint needs to be removed or undergo breaking changes, we follow a minimum 6-month deprecation period for the Stable version. Responses will automatically include standard Deprecation, Sunset, and Link headers, and we will proactively notify owners of keys that have called the endpoint within the last 30 days.

Related Documentation