> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#published-pages) | One page, plus its assets | Until you unpublish | `published: true` in frontmatter |
| [Share links](#share-links) | One file | Until it expires or you revoke it | `.kiwi/state/sharelinks.json` |
| [Space visibility](#space-visibility) | The whole space | Until you change it | `[space] visibility` in `config.toml` |

These only matter when [authentication](https://docs.kiwifs.com/guides/auth-tokens.md) 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.

```markdown guides/onboarding.md theme={null}
---
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:

```text theme={null}
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

> [tab] 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.

> [tab] REST
>
> ```bash Terminal theme={null}
> curl -X POST 'http://localhost:3333/api/kiwi/publish' \
>   -H 'Content-Type: application/json' \
>   -d '{"path": "guides/onboarding.md"}'
> ```
>
> ```json Response theme={null}
> {
>   "path": "guides/onboarding.md",
>   "published": true,
>   "published_at": "2026-10-19T09:00:00Z",
>   "public_url": "/p/guides/onboarding.md"
> }
> ```

> [tab] 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/...`.

> [!WARNING]
>
> 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.

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

```json Response theme={null}
{
  "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`.

```bash Terminal theme={null}
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.

```toml .kiwi/config.toml theme={null}
[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:

```bash Terminal theme={null}
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:

```bash Terminal theme={null}
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

> [!TIP]
>
> 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

> [card] [Publish API](https://docs.kiwifs.com/api/publish.md)
>
> Publish, unpublish, bulk, list, and status.

> [card] [Share links API](https://docs.kiwifs.com/api/publish.md#create-a-share-link)
>
> Create, list, and revoke share links.

> [card] [Configuration](https://docs.kiwifs.com/configuration.md#space-visibility)
>
> The `[space]` section.

> [card] [Authentication](https://docs.kiwifs.com/guides/auth-tokens.md)
>
> API keys, per-space keys, and OIDC.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.