---
title: "publica.la operating guide"
description: "How to call the publica.la MCP server, the anonymous site API and the keyed website API, in that order, with examples."
canonical: "https://publica.la/guide.md"
last-updated: "2026-08-27"
---

# Operating guide

Three ways in, in the order worth trying: the MCP server, the anonymous JSON API,
and the keyed website API. The first two need no credentials at all.

## 1. The MCP server (start here)

- Endpoint: `https://publica.la/mcp` (alias: `https://publica.la/.well-known/mcp`)
- Transport: Streamable HTTP, JSON-RPC 2.0. Responses are `application/json`; no
  SSE stream is opened.
- Protocol version: `2025-06-18` (`2025-03-26` and `2024-11-05` are accepted).
- Authentication: **none**. It is read-only and anonymous.
- Sessions: none. No `Mcp-Session-Id` is required or issued. `DELETE` answers 204,
  `GET` answers 405 with `Allow: POST, DELETE`.
- Limit: 60 requests per minute per IP.
- Client config, ready to paste: `https://publica.la/mcp.json`
- Manifest: `https://publica.la/.well-known/mcp.json` — server card:
  `https://publica.la/.well-known/mcp/server-card.json`

Initialise, then list, then call:

```
curl -sS https://publica.la/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"my-agent","version":"1.0.0"}}}'

curl -sS https://publica.la/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

curl -sS https://publica.la/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"get_platform_overview","arguments":{}}}'
```

### Tools

- `search_site_content` — Search publica.la's published blog posts and changelog entries by keyword, optionally narrowed to one blog category.
- `get_blog_post` — Fetch one published blog post by slug, including its body as plain text.
- `list_changelog_entries` — List the most recent platform changelog entries, newest first.
- `get_pricing_plans` — Return publica.la's own subscription plans with monthly and annual prices, in USD.
- `get_platform_overview` — Explain what publica.la is, when to use it, what it is not for, and where its machine-readable entry points are.

`get_platform_overview` is the one to call first: it answers "what is this and
should I be here at all" in a single round trip.

### Resources

`resources/list` and `resources/read` serve the same documents the HTTP routes do,
so a client that prefers resources over tools needs no second base URL:

- `https://publica.la/llms.txt` (text/plain)
- `https://publica.la/llms-full.txt` (text/plain)
- `https://publica.la/pricing.md` (text/markdown)
- `https://publica.la/guide.md` (text/markdown — this document)

## 2. The anonymous JSON API

Same data, no MCP client needed, no credentials:

```
curl -sS https://publica.la/api/v1/site/overview
curl -sS https://publica.la/api/v1/site/pricing
curl -sS 'https://publica.la/api/v1/site/posts?q=audiobook&limit=5'
curl -sS https://publica.la/api/v1/site/posts/{slug}
curl -sS https://publica.la/api/v1/site/changelog
```

- Envelope: `{"data": …, "meta": {"locale": "en", "generated_at": "…"}}`
- Optional `?locale=` for en, es, pt, fr, de, it, pl. `?q=`, `?category=` and
  `?limit=` (max 50) narrow the post list.
- Cacheable: `Cache-Control: public, max-age=300, s-maxage=3600`.
- Limit: 300 requests per minute per IP, reported in `RateLimit-Policy` and
  `RateLimit`.
- Errors are JSON: a top-level `message` plus the RFC 9457 members `type`,
  `title`, `status`, `detail`, `code`, `hint` and `docs`. Branch on `code`.

These five routes are the whole anonymous surface. Everything else under
`/api/v1` needs a key.

## 3. The keyed website API

For writing to this website — publishing a blog post, managing newsletter
campaigns, pushing subscribers. Keys are issued by a person at publica.la; there
is no OAuth and no self-serve endpoint. The full walkthrough, including what each
status means, is https://publica.la/auth.md, and the operations are described in
https://publica.la/openapi.json.

Writes accept an `Idempotency-Key` header. Send one, reuse it on a retry of the
*same* logical operation, and a replayed response comes back with
`Idempotency-Replayed: true`.

## 4. Somebody else's catalog

A publisher's own books, orders, readers and entitlements are **not** on this
site. They live in that publisher's own store, behind the per-store REST API v3
documented at https://docs.publica.la/ — with a sandbox at
https://docs.publica.la/rest-api-v3/content/content-v3-sandbox and its own
documentation MCP server at https://docs.publica.la/mcp. See
https://publica.la/api.md for which API answers which question.

## Conventions that apply everywhere

- Any HTML page can be fetched as Markdown with `Accept: text/markdown`; those
  responses carry `Vary: Accept`.
- Every successful GET carries RFC 8288 `Link` headers: `llms-txt`, `sitemap`,
  `service-desc`, `api-catalog`, `ard`.
- Read-only and idempotent everywhere an agent can reach without a key, so a
  retry is always safe.
- `publica.la` is written in lowercase.