Publishing and sharing

KiwiFS has three ways to let people read pages without an API key:

Mechanism	Scope	Set by	Read at
Publishing	One page	`published: true` frontmatter	`/p/{path}`
Public visibility	One page	`visibility: public` frontmatter	`/p/{path}` and `/api/kiwi/public/...`
Share link	One page, optional password and expiry	`POST /api/kiwi/share`	`/api/kiwi/public/{token}`

Space visibility is separate: it opens read endpoints for the whole space. See Publishing for when to use each.

Publish a page

Set published: true in the page’s frontmatter, and published_at if the page has never been published.

POST /api/kiwi/publish

string

Git commit author attribution.

string

required

Page path.

curl -X POST 'http://localhost:3333/api/kiwi/publish' \
  -H "Content-Type: application/json" \
  -H "X-Actor: agent:publisher" \
  -d '{"path": "concepts/auth.md"}'

Returns 404 if the page does not exist and 409 if it changed during the request.

string

Page path.

boolean

Always true.

string

First publish time (RFC 3339). Republishing keeps the original value.

string

Relative URL of the published page.

{
  "path": "concepts/auth.md",
  "published": true,
  "published_at": "2026-10-02T14:30:00Z",
  "public_url": "/p/concepts/auth.md"
}

Unpublish a page

Set published: false. The published_at field stays for history.

POST /api/kiwi/unpublish

string

Git commit author attribution.

string

required

Page path.

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

Returns 404 if the page does not exist and 409 if it changed during the request.

{ "path": "concepts/auth.md", "published": false }

Bulk publish or unpublish

Publish or unpublish many pages in a single git commit. Both endpoints take the same body and return the same shape.

POST /api/kiwi/publish/bulk
POST /api/kiwi/unpublish/bulk

string

Git commit author attribution.

string[]

required

Page paths. Duplicates are ignored, and a leading / is stripped.

curl -X POST 'http://localhost:3333/api/kiwi/publish/bulk' \
  -H "Content-Type: application/json" \
  -H "X-Actor: agent:publisher" \
  -d '{"paths": ["concepts/auth.md", "concepts/billing.md", "concepts/missing.md"]}'

Returns 400 if paths is empty or contains an empty string. Pages that are missing or fail to update are reported in errors rather than failing the whole request.

boolean

true for publish, false for unpublish.

integer

Number of paths in the request.

integer

Pages whose frontmatter changed.

integer

Unique paths that needed no change or failed.

object[]

One entry per page that is now in the requested state, with path, published, published_at, and public_url as in Publish a page.

object[]

Pages that could not be updated, each with path and error. Omitted when empty.

{
  "published": true,
  "requested": 3,
  "changed": 1,
  "skipped": 2,
  "paths": [
    { "path": "concepts/auth.md", "published": true, "published_at": "2026-10-02T14:30:00Z", "public_url": "/p/concepts/auth.md" },
    { "path": "concepts/billing.md", "published": true, "published_at": "2026-10-19T09:00:00Z", "public_url": "/p/concepts/billing.md" }
  ],
  "errors": [
    { "path": "concepts/missing.md", "error": "code=404, message=file not found" }
  ]
}

Get publish status

Return whether one page is published.

GET /api/kiwi/publish/status

string

required

Page path.

curl 'http://localhost:3333/api/kiwi/publish/status?path=concepts/auth.md'

Returns 404 if the page does not exist.

string

Page path.

boolean

Whether the page is published.

string

First publish time, if the page was ever published.

string

Relative public URL. Only present while published.

integer

Views of the published page since the server started counting. 0 when view tracking is off.

{
  "path": "concepts/auth.md",
  "published": true,
  "published_at": "2026-10-02T14:30:00Z",
  "public_url": "/p/concepts/auth.md",
  "view_count": 42
}

List published pages

Return every published markdown page, newest first.

GET /api/kiwi/publish/list

curl 'http://localhost:3333/api/kiwi/publish/list'

integer

Number of published pages.

object[]

Published pages, sorted by published_at descending.

Show properties

string

Page path.

string

First publish time, if set.

string

Relative public URL.

{
  "count": 2,
  "pages": [
    { "path": "concepts/billing.md", "published_at": "2026-10-19T09:00:00Z", "public_url": "/p/concepts/billing.md" },
    { "path": "concepts/auth.md", "published_at": "2026-10-02T14:30:00Z", "public_url": "/p/concepts/auth.md" }
  ]
}

Read a published page

Render a published or visibility: public page. This route sits outside /api/kiwi and never requires authentication.

GET /p/{path}

string

required

Page path. .md is appended if the path has no extension.

string

default:"text/html"

text/html for a themed reader page, text/markdown for the raw file, or application/json for frontmatter plus rendered HTML.

curl 'http://localhost:3333/p/concepts/auth'

curl 'http://localhost:3333/p/concepts/auth.md' -H "Accept: application/json"

curl 'http://localhost:3333/p/concepts/auth.md' -H "Accept: text/markdown"

Returns 404 for pages that aren’t published or public, so private pages don’t leak their existence, and 406 for an Accept header with no supported type. Images and other non-markdown files are served when a markdown page in the same folder or a parent folder is published or public. Responses carry Cache-Control: public, max-age=60. With Accept: application/json:

object

Page frontmatter.

string

Rendered body HTML, with heading IDs.

string

Page body without frontmatter.

{
  "frontmatter": { "title": "Authentication", "published": true, "published_at": "2026-10-02T14:30:00Z" },
  "html": "<h2 id=\"overview\">Overview</h2>\n<p>OAuth2 and JWT...</p>\n",
  "markdown": "## Overview\n\nOAuth2 and JWT...\n"
}

Read public files

Fetch one public or published file without authentication. Use this when you want raw bytes instead of the rendered reader page.

GET /api/kiwi/public/file

string

required

File path.

curl 'http://localhost:3333/api/kiwi/public/file?path=concepts/open.md'

Returns the raw file with a content type based on its extension. Returns 400 for a missing or escaping path and 404 for files that aren’t public. Non-markdown files follow the same folder rule as /p/.

Browse the public tree

Return the directory tree, filtered to public and published pages.

GET /api/kiwi/public/tree

string

default:"/"

Folder to start from.

string

Set to published to include only published pages and skip visibility: public pages.

curl 'http://localhost:3333/api/kiwi/public/tree?filter=published'

Folders with no visible pages are omitted. Returns 404 if path does not exist.

{
  "path": "",
  "name": "/",
  "isDir": true,
  "children": [
    {
      "path": "concepts",
      "name": "concepts",
      "isDir": true,
      "children": [
        { "path": "concepts/auth.md", "name": "auth.md", "isDir": false, "size": 1420 }
      ]
    }
  ]
}

Create a token that grants read access to one file, with an optional expiry and password. The page does not need to be published.

POST /api/kiwi/share

string

Recorded as createdBy.

string

required

File path. Returns 404 if it does not exist.

string

Go duration such as 168h. Omit for a link that never expires.

string

Password readers must supply. Stored as a bcrypt hash and never returned.

curl -X POST 'http://localhost:3333/api/kiwi/share' \
  -H "Content-Type: application/json" \
  -H "X-Actor: agent:sharer" \
  -d '{"path": "concepts/auth.md", "expiresIn": "168h", "password": "s3cret"}'

Returns 400 for an invalid expiresIn and 501 if share links are disabled on this server.

string

Link ID, used to revoke it.

string

Shared file path.

string

Secret token for the public URL.

string

Expiry time (RFC 3339). A zero time (0001-01-01T00:00:00Z) means no expiry.

string

Actor that created the link.

string

Creation time.

integer

Times the link has been opened.

{
  "id": "9f8e7d6c5b4a3921",
  "path": "concepts/auth.md",
  "token": "3c1f0a9e8d7b6c5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a",
  "expiresAt": "2026-10-26T14:30:00Z",
  "createdBy": "agent:sharer",
  "createdAt": "2026-10-19T14:30:00Z",
  "viewCount": 0
}

Return the share links for one file.

GET /api/kiwi/share

string

required

File path.

curl 'http://localhost:3333/api/kiwi/share?path=concepts/auth.md'

Returns a JSON array of share links with the fields shown in Create a share link. Returns 501 if share links are disabled. Delete a share link by its id (not its token).

DELETE /api/kiwi/share/:id

string

required

Link ID.

curl -X DELETE 'http://localhost:3333/api/kiwi/share/9f8e7d6c5b4a3921'

Returns 404 if the link does not exist.

{ "revoked": "9f8e7d6c5b4a3921" }

Return the raw shared file. This route needs no API key.

GET /api/kiwi/public/:token

string

required

Share token.

string

Password for a protected link.

Alternative to the password query parameter.

curl 'http://localhost:3333/api/kiwi/public/3c1f0a9e8d7b6c5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a' \
  -H "X-Share-Password: s3cret"

Returns 401 with a WWW-Authenticate header when the password is missing or wrong, and 404 when the token is unknown or expired.

Get space visibility

Return the current space’s visibility and root directory.

GET /api/kiwi/space/info

curl 'http://localhost:3333/api/kiwi/space/info'

string

private, unlisted, or public. Defaults to private.

string

Absolute path of the knowledge root on the server.

{ "visibility": "private", "root": "/data/knowledge" }

Set space visibility

Change who can read the space without an API key. The value is saved to [space] visibility in .kiwi/config.toml and applies immediately.

PUT /api/kiwi/space/visibility

string

required

private: every request needs auth (when auth is configured).
unlisted: GET requests to /file, /peek, and /section with a path are open; listing, tree, and search still need auth.
public: every GET and HEAD request under /api/kiwi is open.

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

Returns 400 for any other value.

{ "visibility": "unlisted" }

Space visibility only relaxes reads. Writes always need auth when auth is configured.

Publishing concepts

When to publish, share, or open a space.

Web UI

The publish toggle in the page header.

REST API

CLI

Publish a page

Unpublish a page

Bulk publish or unpublish

Get publish status

List published pages

Read a published page

Read public files

Browse the public tree

Get space visibility

Set space visibility

Publishing concepts

Web UI

​Publish a page

​Unpublish a page

​Bulk publish or unpublish

​Get publish status

​List published pages

​Read a published page

​Read public files

​Browse the public tree

​Create a share link

​List share links

​Revoke a share link

​Open a share link

​Get space visibility

​Set space visibility

​Related

Publishing concepts

Web UI

Publish a page

Unpublish a page

Bulk publish or unpublish

Get publish status

List published pages

Read a published page

Read public files

Browse the public tree

Create a share link

List share links

Revoke a share link

Open a share link

Get space visibility

Set space visibility

Related