---
title: "publica.la APIs"
description: "This website's JSON API and the per-store platform REST API v3: which answers which question, with errors, limits and idempotency."
canonical: "https://publica.la/api.md"
last-updated: "2026-08-27"
---

# APIs

Two different APIs carry the publica.la name, and conflating them is the commonest
mistake an agent makes here.

| | This website's API | The platform REST API v3 |
|---|---|---|
| Base URL | https://publica.la/api/v1 | one per store, e.g. `https://{store}/api/v3` |
| Described by | https://publica.la/openapi.json | https://docs.publica.la/ |
| Owns | the marketing site: blog posts, changelog, plans, newsletter, subscribers | a publisher's catalog, orders, entitlements, readers |
| Anonymous part | `GET /api/v1/site/*` | none |
| Credential | bearer key issued by publica.la (`rnd_…`) | per-store credentials held by that store |
| Sandbox | none — the anonymous routes are safe to call | https://docs.publica.la/rest-api-v3/content/content-v3-sandbox |
| MCP server | https://publica.la/mcp | https://docs.publica.la/mcp (documentation) |

If the question is "what does publica.la do, what does it cost, what has it
shipped" — this website's API. If the question is "what books does this store
have, what did this reader buy" — the platform API, on that store's own hostname.

## This website's API

### Anonymous, no credentials

```
GET https://publica.la/api/v1/site/overview
GET https://publica.la/api/v1/site/pricing
GET https://publica.la/api/v1/site/posts?q=&category=&limit=&locale=
GET https://publica.la/api/v1/site/posts/{slug}
GET https://publica.la/api/v1/site/changelog?limit=&locale=
```

Envelope `{"data": …, "meta": {"locale", "generated_at"}}`. `limit` caps at 50.
`locale` is one of en, es, pt, fr, de, it, pl. Cacheable
(`public, max-age=300, s-maxage=3600`). This is the same data the MCP server's
tools return.

### Keyed

Everything else under `/api/v1`, gated by a bearer key and a scope per route:
blog posts (`content.read`, `content.write`), newsletter campaigns and stats
(`newsletter.read`, `newsletter.write`, `newsletter.send`), subscribers
(`subscribers.write`), suppressions (`suppressions.write`), booking pages. The
authoritative list is https://publica.la/openapi.json; the credential story is
https://publica.la/auth.md.

### Discovery

- `GET https://publica.la/api` and `GET https://publica.la/api/v1` — JSON
  describing what this API answers, its anonymous endpoints, the MCP server, the
  idempotency contract and every agent document.
- `GET https://publica.la/.well-known/api-catalog` — RFC 9727 linkset.
- `GET https://publica.la/openapi.json` / `.yaml` — OpenAPI 3.1, with
  `operationId` on every operation and one `Error` schema referenced by every
  4xx and 5xx.

### Conventions

- **Errors**: JSON always, `application/json` (not `problem+json`, so existing
  consumers keep working), carrying `message` plus RFC 9457 `type`, `title`,
  `status`, `detail`, `code`, `hint`, `docs`. Branch on `code`.
- **Rate limits**: 300/min per key or IP on `/api/v1`, 60/min on the MCP server.
  `RateLimit-Policy` and `RateLimit` on every response, `Retry-After` on a 429.
- **Idempotency**: an `Idempotency-Key` header on any write, replayed for 24 hours
  with `Idempotency-Replayed: true`; same key with a different body is a 422
  `idempotency_key_reused`.
- **Content negotiation**: `Accept: text/markdown` on any HTML page returns
  Markdown, with `Vary: Accept`.
- **Versioning**: the path carries it (`/api/v1`). Nothing is removed or renamed
  inside a version.

## The platform REST API v3

Documented at https://docs.publica.la/ — one API per store, with its own
credentials, and the one to use for anything about books:

- Content API v3 — a store's catalog, metadata and assets:
  https://docs.publica.la/rest-api-v3/content/content-v3-overview
- Sandbox for it:
  https://docs.publica.la/rest-api-v3/content/content-v3-sandbox
- Orders API v3 — orders, entitlements, purchase history:
  https://docs.publica.la/rest-api-v3/orders/orders-v3-overview
- Auth token / SSO — sign a reader in from an existing system:
  https://docs.publica.la/auth-integrations/auth-token
- Webhooks and IPNs — purchases, subscriptions, user activity:
  https://docs.publica.la/notifications/webhooks-int
- ONIX 3.0 intake — ingest a catalog from ONIX feeds:
  https://docs.publica.la/content-publishing/onix-intake

The documentation site runs its own MCP server at https://docs.publica.la/mcp.
It is not this repository's, and it answers questions about the platform API
rather than about this website.

## What does not exist

- No OAuth server, no dynamic client registration, no device flow.
- No CLI: there is no `publicala` package on npm or PyPI.
- No checkout, cart or payment endpoint on this website.
- No per-book prices anywhere on this website.
- No A2A agent card. The machine surfaces are the MCP server, the OpenAPI
  description and the documents linked from https://publica.la/index.md.

Human contact: https://publica.la/en/developers, hello@publica.la,
support@publica.la, security@publica.la. Status: https://status.publica.la/