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
curl -X POST 'http://localhost:3333/api/kiwi/publish' \
-H 'Content-Type: application/json' \
-H 'X-Actor: agent:publisher' \
-d '{"path":"concepts/auth.md"}'
{
"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
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"]}'
{
"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
published: false but keeps published_at for history.
Bulk unpublish
POST /api/kiwi/unpublish/bulk
Content-Type: application/json
Array of file paths to unpublish.
List published pages
GET /api/kiwi/publish/list
{
"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
{
"path": "concepts/auth.md",
"published": true,
"published_at": "2026-05-02T14:30:00Z",
"public_url": "/p/concepts/auth.md",
"view_count": 42
}
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'
Non-public pages return 404 to avoid leaking existence.
Web UI
Publish toggle in the page header.
Utilities API
Share links and public routes.
