Documentation — BloggyBox

Start here

Overview

The mental model is small: one publication, many articles, and a few ways to create and consume them.

A publication is your project. It has a public home, a set of articles, a newsletter audience, and its own credentials. You can create one publication per account unless your account allows more.

An article moves through three states: draft, published, or archived. Drafts are private. Published articles appear on your public site and in the feed. Archived articles disappear from both without being deleted.

Write

Create articles in the editor yourself, with titles, descriptions, and tags.

Delegate

Connect Claude Code, Cursor, Codex, or any MCP client to draft for you.

Publish

Review the draft, publish it, and let your site or newsletter consume it.

Humans publish. Agents draft.

An agent connection can create review-ready drafts, but it cannot publish, archive, or delete anything. Publishing always stays with you.

Start here

Quickstart

From an empty workspace to a live article in four steps.

Create a publication

From the workspace, create a publication and give it a name. That name shapes the public identity and URL.

Write your first article

Open Articles and choose New article. Add a title and body. The cover image is generated for you.

Publish it

Review the draft and publish. The article is now available on your public site and in the public JSON feed.

Connect what comes next

Add an MCP connection for agent drafts, create a Reader API key for a site, or invite readers to the newsletter.

Go to workspace Or connect an agent first →

Create

Articles

Every piece starts as a private draft in the Articles library.

The Articles page is the source of truth for everything you have written. Search the archive, filter by state or source, open a draft, or start a new one. Agent drafts are labelled so you can tell them apart from your own work.

Each article has a title, URL slug, description, Markdown body, and keywords. Those fields feed the public page, SEO metadata, the public feed, and every agent or API consumer. The cover is generated automatically from the title and publication; you do not need to upload an image.

DRAFTPrivateOnly you and your agents can see it.

PUBLISHEDPublicVisible on your site and available in the feed.

ARCHIVEDHiddenRemoved from public views without deleting the article.

Content types are inferred, not configured.

Articles, announcements, changelogs, docs, tutorials, release notes, and essays all live in the same editor. Write the shape the content needs. Agents read the same guidance before drafting.

Create

Publishing

Publishing is the moment a draft becomes part of your public surface.

Open a draft, make the final review pass, and publish. The article appears at/<publication>/<article-slug>on your public site and immediately enters the public feed.

Every published article gets a generated social card and a 1200×630 cover image at/<publication>/<article-slug>/banner. Use the page URL for readers and the Reader API for structured content.

What publishing does

Adds the article to your public index and feed.
Enables the public page and generated cover.
Makes the full article available through the APIs.

What publishing does not do

It does not send your newsletter.
It does not let an agent publish for you.
It does not push to third-party integrations automatically.

Create

Collect readers, track subscribers, and give people a way out.

The Newsletter page lists every subscriber, shows active and unsubscribed totals, supports manual additions, and exports the audience as CSV. Subscribers can arrive from your public site, a form you build, or your own API integration.

Add a subscriber

curl -X POST 'https://api.bloggybox.ppussh.com/public/my-publication/subscribe' \
  -H 'Content-Type: application/json' \
  -d '{"email":"reader@example.com"}'

Unsubscribe with the reader's token

curl -X POST 'https://api.bloggybox.ppussh.com/public/my-publication/unsubscribe' \
  -H 'Content-Type: application/json' \
  -d '{"token":"<unsubscribe-token>"}'

POST/public/{publication}/subscribe

Public, rate-limited

POST/public/{publication}/unsubscribe

Requires subscriber token

Server-side forms can skip the public throttle.

A project key with the subscribers:write scope can be sent as X-API-Key. Unauthenticated public requests are rate-limited by IP.

Connect

MCP for agents

Give a coding agent a scoped way to turn shipped work into a review-ready draft.

BloggyBox exposes a Streamable HTTP MCP server at https://api.bloggybox.ppussh.com/mcp. A connection is tied to one publication and one credential. The credential carries only the draft:create scope.

Create the connection from the MCP page in your publication. Copy the endpoint and the one-time key into your client, then ask the agent to write a draft. The agent reads the built-in writing guide, creates the article, and returns a review link.

Open MCP

Choose the publication and open MCP in the sidebar.

Create a key

Generate a connection with the draft:create scope.

Connect

Paste the endpoint and Bearer key into your client.

Terminal

claude mcp add --transport http bloggybox \
  https://api.bloggybox.ppussh.com/mcp \
  --header "Authorization: Bearer bbkx_..."

Verify the server and list tools

curl -s -X POST 'https://api.bloggybox.ppussh.com/mcp' \
  -H 'Authorization: Bearer bbkx_...' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The agent has a writing guide.

Before drafting, agents read bloggybox://write_article for structure, metadata, and the critique checklist. You do not need to paste a writing system prompt into every client.

Connect

Public feed

A cacheable JSON surface for published articles. No key required.

Use the public feed when your website or build step needs your published articles. It exposes only published content and never requires a credential. Lists include a plain-text preview; the single-article endpoint includes the full Markdown body.

GET/public

All public publications

GET/public/{publication}

Publication details

GET/public/{publication}/posts

Published list, paginated

GET/public/{publication}/posts/{article}

Full published article

List published articles

curl 'https://api.bloggybox.ppussh.com/public/my-publication/posts?page=1&per_page=20'

Read one article with full Markdown

curl 'https://api.bloggybox.ppussh.com/public/my-publication/posts/my-article-slug'

List response

{
  "data": [
    {
      "title": "Ship the feature, then ship the story",
      "slug": "ship-the-story",
      "description": "A short summary of the article.",
      "content_preview": "The first 250 characters of plain text…",
      "keywords": "product, engineering",
      "reading_time": 4,
      "banner_image": null,
      "published_at": "2026-09-18T00:00:00Z",
      "updated_at": "2026-09-18T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Covers and social cards are generated.

Do not upload or invent a banner URL. The generated 1200×630 image is available at /<publication>/<article>/banner on your public site.

Connect

Reader API

Authenticated, structured access to the same published content.

The Reader API is for integrations that want an explicit project credential, predictable scopes, and usage tracking. Create a reader key on the Feed page. The key can only read published articles and cannot write, publish, or manage your publication.

GET/v1/posts

Requires X-API-Key

GET/v1/posts/{article}

Requires X-API-Key

List published articles

curl 'https://api.bloggybox.ppussh.com/v1/posts?page=1&per_page=20' \
  -H 'X-API-Key: bbkx_...'

Read one article

curl 'https://api.bloggybox.ppussh.com/v1/posts/my-article-slug' \
  -H 'X-API-Key: bbkx_...'

Authentication

Send X-API-Key: bbkx_... on every request. The key is scoped to one publication.

Pagination

Use page and per_page (1–100).

Manage

Publication settings

The small set of controls that apply to the publication itself.

Settings keeps only the essentials: the publication name and description. Both are used across the workspace, the public site, and feed metadata. Save changes when you are done, or discard them before leaving.

Deleting a publication permanently removes every article, subscriber, connection, and key attached to it. There is no undo, so the delete dialog asks you to type the publication slug first.

Deletion is permanent.

Export anything you need before deleting a publication. The public site and all API credentials stop working immediately.

Manage

Keys & security

Use one credential per job and keep the blast radius small.

draft:createMCP connections and agent draftsCreate drafts only

articles:readReader API and websitesRead published articles

subscribers:writeServer-side newsletter formsAdd subscribers

Copy a new key when it is created — the full value is shown once.
Rotate a key immediately if it leaks. Rotation revokes the old key first.
Use separate keys for separate integrations, and revoke what you stop using.
Never expose an API key in browser code. Server-side or edge runtimes only.

Manage

Troubleshooting

The problems people hit first, and what actually fixes them.

My draft is not in the feed.

Only published articles are exposed. Open the article, confirm its state is Published, then reload the feed. Archived articles disappear from public output.

The API returns 401 Invalid API key.

Check that the key belongs to this publication, has the required scope, and has not been revoked or rotated. Reader calls need articles:read; newsletter calls need subscribers:write.

My MCP client sees no tools.

Verify the URL ends in /mcp, the transport is Streamable HTTP, and the Authorization header is Bearer bbkx_... . Run the tools/list curl from the MCP section to confirm the credential before changing your client config.

A published article returns 404.

Check the publication and article slugs. The article must still be Published — archiving it hides both the page and the API record.

Newsletter signups return 429.

The public subscribe endpoint is rate-limited per IP. Move the call server-side and authenticate it with a key that has subscribers:write.

The public feed is empty.

Publish at least one article in that publication. The feed only lists PUBLISHED posts and never includes drafts.

Keep building

Ready when you are.

Open the workspace to write, publish, or connect an agent. Every credential and endpoint in this guide lives inside the publication you create.

Open workspace Agent integrations

Everything you need to ship the story.

Overview

Quickstart

Articles

Publishing

Newsletter

MCP for agents

Public feed

Reader API

Publication settings

Keys & security

Troubleshooting

Ready when you are.