94 lines
2.2 KiB
Markdown
94 lines
2.2 KiB
Markdown
# API Reference
|
||
|
||
> Status: the public read API (`/api/volumen`) and the admin (`/admin`) are
|
||
> implemented. The admin is server-rendered HTML, not part of the JSON API.
|
||
|
||
Base path: `/api/volumen`. All responses are JSON unless noted. Read endpoints
|
||
send `Access-Control-Allow-Origin: *`.
|
||
|
||
## `GET /api/volumen/site`
|
||
|
||
Returns site metadata from the configuration.
|
||
|
||
```json
|
||
{
|
||
"title": "My Blog",
|
||
"description": "A blog powered by volumen.",
|
||
"base_url": "https://example.com",
|
||
"language": "en",
|
||
"author": "Anonymous"
|
||
}
|
||
```
|
||
|
||
## `GET /api/volumen/posts`
|
||
|
||
Paginated list of published posts (drafts are excluded), newest first.
|
||
Posts with `all_langs = true` in their frontmatter match every `lang` filter.
|
||
|
||
| Name | Type | Default | Description |
|
||
|-------|--------|---------|--------------------|
|
||
| lang | string | — | Filter by language |
|
||
| tag | string | — | Filter by tag |
|
||
| page | int | 1 | Page number |
|
||
| limit | int | 20 | Per page (1–100) |
|
||
|
||
```json
|
||
{
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"total": 1,
|
||
"posts": [
|
||
{
|
||
"slug": "hello",
|
||
"title": "Hello",
|
||
"excerpt": "Hello world.",
|
||
"date": "2026-01-15",
|
||
"lang": "en",
|
||
"tags": ["intro"],
|
||
"author": null,
|
||
"cover": null,
|
||
"reading_time": 1,
|
||
"translations": {},
|
||
"url": "/api/volumen/posts/hello"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## `GET /api/volumen/posts/{slug}`
|
||
|
||
Single post including the raw Markdown body and rendered HTML. Optional
|
||
`?lang=` selects a translation. Returns `404` with `{"error":"not_found"}` if
|
||
no match.
|
||
|
||
```json
|
||
{
|
||
"slug": "hello",
|
||
"title": "Hello",
|
||
"excerpt": "Hello world.",
|
||
"date": "2026-01-15",
|
||
"lang": "en",
|
||
"tags": ["intro"],
|
||
"author": null,
|
||
"cover": null,
|
||
"reading_time": 1,
|
||
"translations": {},
|
||
"url": "/api/volumen/posts/hello",
|
||
"body": "Hello **world**.",
|
||
"html": "<p>Hello <strong>world</strong>.</p>\n"
|
||
}
|
||
```
|
||
|
||
## `GET /api/volumen/tags`
|
||
|
||
Tag cloud with counts (published posts only), most frequent first.
|
||
|
||
```json
|
||
{ "tags": [{ "name": "intro", "count": 1 }] }
|
||
```
|
||
|
||
## `GET /api/volumen/feed.xml`, `GET /api/volumen/sitemap.xml`
|
||
|
||
RSS 2.0 feed (latest 20 posts) and a sitemap of post URLs, built from
|
||
`site.base_url`.
|