Content Delivery API

The Content Delivery API is a public HTTP API designed for external frontends and mobile apps, mounted directly under your website's own domain. Once you publish content in Collections, Blog, Pages, or Online Forms, any frontend framework (Next.js, Astro, Remix, Nuxt, SvelteKit) can call it directly. There is no need to store API keys on the frontend, and you get millisecond response times powered by global edge caching.

Full Endpoints, Parameters, and Error Codes (SSOT): All endpoint paths, query parameters, response structures, rate-limiting headers, and error codes are automatically generated from the OpenAPI 3.1 specification on the Content Delivery API Reference page (you can also download https://{your-site}/api/v1/openapi.json directly from your site). This article focuses on the platform-level design concepts.

Division of Labor: The Three APIs

Two-Layer URLs: Why We Recommend Using Permanent System URLs

Your website has two types of URLs that can call the Content Delivery API:

1. Permanent System URL (https://s-xxxxxxxxxxxx.kanorio.com/api/v1): Assigned at creation and permanent. Even if you haven't published a Kanorio-hosted page (only enabled "Enable API service when site is unpublished" in "Site Settings › Developer"), or if you point your custom domain DNS to Vercel/Cloudflare Pages in the future, this system URL will always remain valid.
2. Public Subdomain or Custom Domain (https://your-subdomain.kanorio.com/api/v1): Can be used for calls once the hosted site is published.

Search Engine Protection: All /api/v1/* responses automatically include the X-Robots-Tag: noindex header to prevent search engines from indexing JSON endpoints as web pages, which would dilute your site's SEO authority.

Why We Use a Top-Level assets Mapping Table

In many traditional CMSs, if an image field only stores an ID, the frontend must make a second request to fetch the URL. If the image URL is hardcoded into the field, it becomes invalid when the site owner replaces the image or updates the alt text in the media library.

Therefore, Kanorio provides a unified assets mapping table at the top level of responses for /collections/{key}/items, /pages/{slug}, and /globals/*:

• Clean Field Values: image and file fields store only the assetId string (or assetId[] for gallery).
• Resolve All Media at Once: The top-level assets[assetId] automatically includes the latest public CDN URL (url), original dimensions (width, height), alt text, file type, and a 16px WebP blurred placeholder (Data URL).
• Responsive Images Without Setup: Public image URLs can be appended with /w=400, /w=800, /w=1200, /w=1600, or /w=1920 to fetch optimized images. Combined with the placeholder, you can achieve zero-CLS loading in Next.js using <Image blurDataURL={...} />.

CORS and Preview Tokens (knr_pv_)

1. Allowed Origins (CORS Whitelist)

• If you call the API from a Next.js Server Component, Astro build phase, or backend server, these are server-to-server requests and do not require CORS configuration.
• If you fetch directly from the browser side of an external site (e.g., for real-time search or form submission), please go to "Site Settings › Developer" and add your external frontend's Origin (e.g., https://www.example.com) to the "Allowed Origins". Local development http://localhost:* is always allowed by default.
• Important Concept: The CORS whitelist only controls whether the browser allows cross-origin reads; it is not an authorization boundary. Unpublished drafts are completely isolated at the database query layer.

2. Securely Previewing Drafts on Custom Frontends (X-Kanorio-Preview)

When an editor modifies a draft article or page and wants to preview it on an external frontend before publishing:

• Go to "Site Settings › Developer" to create a read-only preview token starting with knr_pv_ (or call site.create_preview_token via AI).
• On your external frontend's server side (e.g., Next.js Draft Mode), include the header X-Kanorio-Preview: knr_pv_your-preview-token (or use the previewToken option in @kanorio/sdk).
• Preview requests are HMAC-verified at the edge, bypass all public caches (Cache-Control: private, no-store), and return the latest draft content.

Version Key Edge Caching and X-Kanorio-Cache-Tags

The Content Delivery API has no monthly read limits and no API bandwidth fees. The key lies in our two-layer version key caching and cache tag design:

1. Automatic Version Promotion: Whenever you publish content in the dashboard or via AI, the site's publicVersion automatically increments. Edge caches switch to the new version within seconds, supporting weak ETags and If-None-Match (returning 304 Not Modified when content hasn't changed).
2. Precise Cache Tags (X-Kanorio-Cache-Tags): Every response includes structured tags (e.g., site:{siteId}, collection:blog, item:{itemId}, pages, globals, redirects). These align perfectly with the data.cacheTags in payloads, allowing you to implement on-demand revalidation in Next.js with a single line of code.

Related Documentation