# 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`.