Fetching Pages, Blog Posts, and Collections

When building your own frontend, all public content can be fetched keylessly directly from your site URL https://{your-site}/api/v1/* (or the permanent system URL https://s-xxx.kanorio.com/api/v1/*).

Full Endpoint & Parameter Specs (SSOT): All query parameters, field types, filter operators, and JSON response examples are generated in real-time from the OpenAPI spec on the Content Delivery API reference page. This guide focuses on architectural decisions and common patterns for frontend integration.

What this guide helps you achieve:

• Fetch site shells (header navigation, footer, site settings, and redirect rules) in one go.
• Query custom collections with cross-reference expansion (expand) and parse assets images with blur placeholders (placeholder).
• Read blog posts with multiple content formats (formats), structured segments (segments), and auto-generated tables of contents (toc).
• Integrate a keyless site search box on your frontend (/api/v1/search).
• Automatically generate full-site TypeScript types with a single command (npx @kanorio/cli types).

1. Fetching Site Shells, Pages, and Redirects

If your external frontend needs to use the navigation menus, footer links, or page SEO settings configured in the Kanorio dashboard, you can fetch them in your shared Layout:

• Site Info (GET /api/v1/site): Get site name, default language, timezone, currency, and the current public content version publicVersion.
• Header & Footer (GET /api/v1/globals/headers/primary, GET /api/v1/globals/footer): Get navigation trees, CTA buttons, social links, and logos (with a top-level assets media map).
• Page Tree & Single Pages (GET /api/v1/pages, GET /api/v1/pages/{slug}): Get page hierarchy, breadcrumbs, SEO fields (title, description, ogImage, canonicalUrl, noindex), and page module data. Call /api/v1/pages/home for the homepage.
• Redirect Rules (GET /api/v1/redirects): Get the redirects configured in the dashboard, plus the 301 redirect list automatically generated when pages are renamed. Add these to your Next.js Middleware or edge routes to preserve your SEO.

2. Querying Collections and Cross-References (/api/v1/collections/{key}/items)

Whether you are using custom collections created in (e.g., teachers, courses) or system-synced blog collections (blog, blog_categories, blog_tags, blog_authors), the query syntax remains the same:

const res = await fetch(
  "https://s-k4m9x2p7q8w3.kanorio.com/api/v1/collections/courses/items?filter[level]=beginner&sort=-publishedAt&expand=teacher&limit=20"
);
const { items, nextCursor, assets } = await res.json();

Four Practical Tips for Integration

1. Use expand to resolve references: If a collection has reference or multi_reference fields (e.g., teacher for courses, authors,categories,tags for blogs), adding ?expand=teacher attaches item.expanded.teacher (containing the full fieldData) to each item. Images from expanded items are also included in the top-level assets map, eliminating the need for a second request.
2. Use has_slug / eq_slug for category or tag filtering: When building category pages (e.g., /blog/category/recipes), you don't need to fetch the category ID first. Just write ?filter[categories][has_slug]=recipes (use eq_slug for single-select references), and the server will perform the match in a single query.
3. Feed assets[id].placeholder to image components: The top-level assets map includes url, width, height, alt, and placeholder (16px WebP Base64 data URL) for every bitmap. Use it directly in Next.js <Image placeholder="blur" blurDataURL={asset.placeholder} /> for smooth, progressive loading without extra requests.
4. Use to reduce payload size: For list pages where you don't need the full content, add to have the server return only the specified fields.

3. Reading Blog Posts, TOC, and In-Article CTAs

When querying /api/v1/collections/blog/items or a single item via /api/v1/collections/blog/items/{slug}, you can control the content format via ?formats=:

• Default (no formats): fieldData.content returns clean Markdown, while the item provides a structured segments array and a toc array (H2/H3 id, text, level) at the top level.
• Need pre-rendered HTML or plaintext: Add ?formats=html,plaintext (or markdown,html,plaintext), and fieldData will include contentHtml and contentPlaintext.
• Rendering In-Article CTAs: The segments array splits the article into { type: "markdown", markdown } and { type: "cta", presetId, title, description, buttonText, buttonUrl } objects, allowing you to render promotional cards using your own React/Astro components.

4. Integrating Site Search (/api/v1/search)

To add a site-wide search box to your frontend, call this directly from your browser or server:

const res = await fetch(
  `https://s-k4m9x2p7q8w3.kanorio.com/api/v1/search?q=${encodeURIComponent(keyword)}&kind=post,page,product&limit=10`
);
const { results } = await res.json();

• The search index is rebuilt automatically whenever you publish a page, post, or product.
• kind filters by page, post, product, or category (comma-separated).
• Each result includes title, snippet, url, and type, perfect for real-time dropdown search menus or Command-K search panels.

5. Automatically Generate TypeScript Types (kanorio types)

No need to manually write TypeScript interface definitions for your collection fields. Run this in your project root:

npx @kanorio/cli types --site https://s-k4m9x2p7q8w3.kanorio.com --out src/kanorio.d.ts

The CLI reads the public /api/v1/collections self-describing structure (including virtual fields like segments, toc, and counts) to generate complete FieldData, Expanded, Item types, plus definitions for /pages, /globals, and /site. You can also subscribe to the collections.schema.changed to update types automatically when fields change.

Related Guides