API

The Reblog API

How the Reblog API works end to end: the two programmable surfaces, the two ways to authenticate, and the complete list of what a connection can do to a project.

Reblog exposes its content and its editorial machinery through two surfaces that share one authentication story. Which one you want depends on who is calling: your website, or an AI agent.

	Content API	MCP server
Endpoint	`GET /api/external/articles`	`POST /api/mcp`
Protocol	REST, JSON	JSON-RPC 2.0 (Model Context Protocol)
Caller	Your site, your build step, your CDN	Claude, Claude Code, Cursor, your own agent
Can read	Published articles only	Drafts, ideas, assets, jobs, agents, history
Can write	Nothing	Everything the granted permissions allow
Auth	Project API key	OAuth 2.1 token, or project API key
Reference	Content API	MCP overview

One base URL

Everything lives at https://reblog.so. The API routes and the OAuth discovery documents sit at the domain root, never under /app -- that prefix is the dashboard UI and it redirects, which breaks integrations that do not follow redirects.

The Content API#

A single read endpoint, built for the one job a blog front end has: turn a URL into an article. It is deliberately small. It answers in four modes, selected by the query parameters you send.

One article -- ?handle=guides/getting-started or ?article_id=<id>. Returns the full document: markdown body, cover, SEO fields, language mirrors, recommendations and structured metadata.
A category feed -- ?category=guides&lang=EN&page=0&limit=10. Paginated, newest first, with a has_more flag.
The sitemap -- ?sitemap=true. Every published handle with its dates, for generating sitemap.xml.
Scheduled posts stay hidden -- every mode filters on status: published AND a publication date that has already passed, so a future-dated article never leaks.

Fetch one article

curl -H "Authorization: Bearer $REBLOG_API_KEY" \
  "https://reblog.so/api/external/articles?handle=guides/getting-started"

Full parameter tables, response shapes and framework examples: Content API reference and the article object.

The MCP server#

MCP (Model Context Protocol) is the open standard that lets an AI client call your tools. Reblog ships an MCP server, so instead of writing glue code you point Claude, Claude Code, Cursor or your own agent at one URL and it can operate the blog directly: research a topic, write the draft, illustrate it, translate it into every language the project runs, and schedule it.

Endpoint	`POST https://reblog.so/api/mcp`
Transport	Streamable HTTP, stateless JSON-RPC over POST
Protocol version	`2025-06-18`
Server	`reblog-mcp` 1.0.0
Tools	54, across 11 permission groups
Discovery	`/.well-known/oauth-protected-resource`

Nothing to register by hand

Sign-in uses OAuth 2.1 with dynamic client registration and PKCE. A client discovers the endpoints, registers itself, and opens a Reblog consent screen in your browser. You pick the access level. See Connect a client.

What a connection can do#

Everything below is reachable through the MCP server. Each row names the permission that unlocks it -- that is the same string the consent screen shows you, and the same one a tool declares in code.

Capability	Permission	What it covers
Discovery	`account.projects.read`	List the projects and workspaces a connection can reach, and ask which of them is overdue for an article.
Read content	`articles.read`	Articles with their markdown, categories, revision history, the images inside a post, the publishing calendar, content gaps, and which articles have gone stale.
Create content	`articles.create`	Write a finished article yourself, or file a topic in the ideas backlog.
Edit and publish	`articles.edit`	Update fields, apply targeted find-and-replace edits, roll back to an earlier revision, add or swap the pictures in a post, set the cover, publish now, schedule for a date, unpublish, approve from the review queue.
Delete	`articles.delete`	Delete an article for good.
Run AI agents	`agents.run`	Generate an article from a topic, translate one article or every missing language, generate images, rebuild internal recommendations, cancel a running job, and configure the project agents that decide how all of that sounds. Spends AI credits.
See AI agents	`agents.read`	Inspect the configured agents, the idea backlog, the job queue, and the image models the account can reach.
Assets	`assets.read` / `assets.create` / `assets.delete`	Browse the project media library, upload a file into the project CDN, and delete one (refused while published articles still point at it, unless forced).
Automation routines	`automation.manage`	List, run and pause the scheduled autopilot pipelines. Sensitive: a routine publishes on its own and spends credits on a schedule.

The complete catalogue, tool by tool with every argument, is on the tool reference page.

Authentication in one paragraph#

A project API key is a long-lived secret bound to exactly one project, created in the dashboard, and sent as Authorization: Bearer <key>. It works on both surfaces and carries one of two levels: read-only, or read and write. An OAuth 2.1 token is what an MCP client obtains for you when you approve its consent screen; it can cover several projects, it expires and refreshes, and you can revoke it at any time from the connected-apps page. Details, including the deprecated query-parameter form: Authentication.

The permission model#

This is the part worth reading before you build anything on top. Reblog checks two independent things on every MCP call, and a call needs both to pass.

1
What the app was allowed to ask for
The grant's scopes. A connection approved as read-only is never offered a tool that writes -- those tools do not appear in its catalogue at all.
2
What you are allowed to do
Your own role on the target project, re-read live on every call. A connection can never do more than the person behind it: an app you granted full access still cannot delete an article in a project where you are only a contributor.

Demotion takes effect immediately

Because the role is resolved per call, removing someone from a project shrinks every connection they authorized, with no token to revoke and no cache to wait out.

Every scope, every consent preset, and the exact tool-to-role matrix: Permissions and scopes.

Limits and timeouts#

	Value	Notes
MCP rate limit	5 requests / second	Per grant (OAuth) or per key (API key). Exceeding it returns a JSON-RPC error, and the attempt is recorded.
MCP request timeout	300 seconds	Tool calls are answered on the same request. Image generation and article writing routinely take 90 to 120 seconds.
Content API page size	30 items	`limit` is capped server-side.
Access token lifetime	60 minutes	Refresh tokens last 60 days and rotate on every use.
Authorization code lifetime	60 seconds	PKCE, single use.

You can see every call#

Every MCP request is written to an activity log against your account: which app called, which tool, on which project, with which arguments, and what it was told -- including the calls that were refused by a permission or a rate limit. It is in the dashboard under Settings -> MCP activity. Refused credentials are attributed too, when the token is recognizable, so a revoked app that keeps knocking is visible rather than silent.

Where to go next#

Authentication

Keys, headers, OAuth, and what not to do with a private key.

Content API

The four modes of the read endpoint, with parameters and examples.

Article object

Every field on the document you get back.

Cache revalidation

Stop serving deleted or renamed articles: let Reblog purge them from your site cache.

Errors

Status codes, JSON-RPC codes, and the deprecation headers.

MCP tools

All 56 tools with their arguments.

MCP protocol

The JSON-RPC methods, project routing, and the setup_required handshake.