Publish

Publishing marks a page with published: true and published_at in frontmatter. Published pages are readable at /p/{path} without API authentication.

Publish a page

POST /api/kiwi/publish
Content-Type: application/json

string

required

File path to publish.

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

Response

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

published_at is set only on first publish. Later republish calls preserve the original timestamp.

Bulk publish

Publish multiple pages in a single request.

POST /api/kiwi/publish/bulk
Content-Type: application/json

string[]

required

Array of file paths to publish.

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/users.md"]}'

Response

{
  "published": 3,
  "results": [
    {"path": "concepts/auth.md", "published": true},
    {"path": "concepts/billing.md", "published": true},
    {"path": "concepts/users.md", "published": true}
  ]
}

Unpublish

POST /api/kiwi/unpublish
Content-Type: application/json

string

required

File path to unpublish.

Sets published: false but keeps published_at for history.

Bulk unpublish

POST /api/kiwi/unpublish/bulk
Content-Type: application/json

string[]

required

Array of file paths to unpublish.

List published pages

GET /api/kiwi/publish/list

Returns all currently published pages.

Response

{
  "pages": [
    {"path": "concepts/auth.md", "published_at": "2026-05-02T14:30:00Z", "public_url": "/p/concepts/auth.md"},
    {"path": "guides/quickstart.md", "published_at": "2026-05-01T10:00:00Z", "public_url": "/p/guides/quickstart.md"}
  ]
}

Publish status

GET /api/kiwi/publish/status?path=concepts/auth.md

string

required

File path to check.

Response

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

integer

Included when publish metrics tracking is enabled on the server.

Read published pages

No API key required:

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

Public visibility (alternative model)

Separate from per-page publish flags, mark pages with visibility: public in frontmatter:

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

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

Non-public pages return 404 to avoid leaking existence.

Web UI

Publish toggle in the page header.

Utilities API

Share links and public routes.

REST API

CLI

Publish a page

Bulk publish

Unpublish

Bulk unpublish

List published pages

Publish status

Read published pages

Public visibility (alternative model)

Web UI

Utilities API

​Publish a page

​Bulk publish

​Unpublish

​Bulk unpublish

​List published pages

​Publish status

​Read published pages

​Public visibility (alternative model)

​Related documentation

Web UI

Utilities API

Publish a page

Bulk publish

Unpublish

Bulk unpublish

List published pages

Publish status

Read published pages

Public visibility (alternative model)

Related documentation