Publishing and sharing

Open pages to readers without an API key through published permalinks, share links, or space visibility.

KiwiFS has three ways to let people read content without an API key. Pick by scope and lifetime:

Model	Scope	Lifetime	Stored in
Published pages	One page, plus its assets	Until you unpublish	published: true in frontmatter
Share links	One file	Until it expires or you revoke it	.kiwi/state/sharelinks.json
Space visibility	The whole space	Until you change it	[space] visibility in config.toml

These only matter when authentication is on. Without auth, every route is already open.

Published pages

A page with published: true in its frontmatter is served as a rendered HTML page at /p/{path}, with no authentication. Use it for docs, guides, and anything that should stay public.

guides/onboarding.md

---
title: Onboarding
description: First week checklist for new engineers
published: true
published_at: 2026-10-19T09:00:00Z
---

The permalink works with or without the .md extension:

http://localhost:3333/p/guides/onboarding

Send Accept: text/markdown to get the raw markdown, or Accept: application/json for a JSON payload, instead of HTML. Pages that are not published return 404, so readers cannot probe for pages that exist.

Publish a page

Web UI

Click Publish in the page header. Once published, the same menu offers Copy public link, View published page, and Unpublish. In the file tree, right-click a page to Publish it, or a folder to Publish folder or Unpublish folder in one step.

REST

Terminal

curl -X POST 'http://localhost:3333/api/kiwi/publish' \
  -H 'Content-Type: application/json' \
  -d '{"path": "guides/onboarding.md"}'

Response

{
  "path": "guides/onboarding.md",
  "published": true,
  "published_at": "2026-10-19T09:00:00Z",
  "public_url": "/p/guides/onboarding.md"
}

MCP

Call kiwi_patch_frontmatter to set published: true on the page.

Publishing sets published: true and stamps published_at the first time. Republishing later keeps the original date. Unpublishing sets published: false. Each change is a normal frontmatter write, so it is committed to git and appears in history.

• POST /api/kiwi/publish/bulk and /unpublish/bulk change many pages in one commit and report how many changed or were skipped.
• GET /api/kiwi/publish/list lists published pages, newest first.
• GET /api/kiwi/publish/status?path=... returns the publish state and a view_count of permalink visits.

Images and attachments

Non-markdown files such as images and PDFs are public when a markdown page in the same folder, or in any parent folder, is published or has visibility: public. Relative image links in a published page therefore keep working at /p/....

Publishing a page also exposes every other non-markdown file in its folder and in the folders below it. Keep private attachments out of folders that contain published pages.

Share links

A share link gives one file to someone who has no account, without publishing it. Each link has a long random token, an optional expiry, and an optional password.

Terminal

curl -X POST 'http://localhost:3333/api/kiwi/share' \
  -H 'Content-Type: application/json' \
  -d '{"path": "reviews/q4-plan.md", "expiresIn": "168h", "password": "hunter2"}'

Response

{
  "id": "9c1e4b7a2f3d5e60",
  "path": "reviews/q4-plan.md",
  "token": "3b7f...e91a",
  "expiresAt": "2026-10-26T09:00:00Z",
  "createdBy": "alice",
  "createdAt": "2026-10-19T09:00:00Z",
  "viewCount": 0
}

The recipient fetches the file at /api/kiwi/public/{token}. It returns the raw file, not rendered HTML. For a password-protected link, pass ?password=... or an X-Share-Password header; a wrong or missing password returns 401.

Terminal

curl 'http://localhost:3333/api/kiwi/public/3b7f...e91a' \
  -H 'X-Share-Password: hunter2'

• Omit expiresIn for a link that never expires. It takes a duration such as 24h or 30m.
• Every successful fetch increments viewCount.
• GET /api/kiwi/share?path=... lists a file’s links. Revoke one with DELETE /api/kiwi/share/{id}, using the short id, not the token.

Space visibility

[space] visibility decides how much of the API is open to readers with no credentials. It never opens writes.

.kiwi/config.toml

[space]
visibility = "unlisted"

Value	Unauthenticated GET requests
private (default)	Rejected. Only /p/..., share links, and the public routes below work.
unlisted	Direct reads with a path, such as /api/kiwi/file?path=..., /peek, and /section, are open. Tree, search, and listings still need auth.
public	Every GET under /api/kiwi is open, including tree and search.

Unauthenticated requests are recorded with the actor anonymous. Change visibility at runtime without a restart:

Terminal

curl -X PUT 'http://localhost:3333/api/kiwi/space/visibility' \
  -H 'Content-Type: application/json' \
  -d '{"visibility": "unlisted"}'

This updates [space] visibility in .kiwi/config.toml and takes effect immediately. GET /api/kiwi/space/info returns the current value.

Public pages in a private space

Two read-only routes serve individual pages that opt in with visibility: public or published: true in frontmatter, whatever the space visibility:

Terminal

curl 'http://localhost:3333/api/kiwi/public/file?path=guides/onboarding.md'
curl 'http://localhost:3333/api/kiwi/public/tree?path=/'

/public/tree lists only those pages and hides empty folders. Add filter=published to list published pages only. Pages that do not opt in return 404. Pages with visibility: public are also served at /p/{path}.

Choose a model

Publish content that should stay public, such as docs and guides. Use share links for temporary or restricted access, such as a review draft. Use unlisted or public visibility to open a whole space for reading.

Related

Publish API

Publish, unpublish, bulk, list, and status.

Share links API

Create, list, and revoke share links.

Configuration

The [space] section.

Authentication

API keys, per-space keys, and OIDC.