Skip to content
microfeed by Listen Notesmicrofeed by Listen Notesmicrofeed docs

API overview

Software can read microfeed content in two ways:

  • The public JSON Feed at /json/ lets readers and software consume published channel content without a credential.
  • The optional authenticated API under /api/v1/ lets integrations read, create, update, and delete content, update the primary channel, and prepare item images and media-attachment uploads.

With explicit webhook enablement, software can also receive signed, Queue-backed notifications when content changes. Webhooks announce a change; they do not grant API access. Start with Webhooks and integrations when building a persistent service or deployed AI agent, and use the Content automation overview for practical automation examples.

New installations keep API access and public API docs off until the instance owner enables them in the dashboard.

Explore the current contract in microfeed.org’s interactive API documentation. It includes request and response schemas, authentication requirements, and examples for API operations and webhook events.

If you want a coding agent to publish content, start with the official microfeed CLI guide instead of creating and sharing an API key. Build directly against the REST API when you are integrating another application or service.

For interactive draft editing, a compatible browser agent can instead discover microfeed’s experimental WebMCP site tools after it opens the signed-in, protected dashboard. WebMCP is separate from this remote API: API documentation can tell an agent that the capability exists, but the tools themselves are available only from the active dashboard page.

What the API can do

Section titled “What the API can do”

The authenticated API covers these capability groups:

Capability Typical operations
Channel Read or update the primary channel identity and settings exposed by the contract.
Items List, search, validate, create, read, update, and delete feed items.
Pages List, search, create, read, update, delete, and reorder standalone website Pages.
Site Files List, read, create, update, preview, publish, reset, and delete root-level text files.
Search Search item and Page titles or stored plain-text content with filters and cursor pagination.
Media Prepare same-origin uploads for item images, attachments, channel images, and standalone media.

The generated OpenAPI document is the exact operation inventory for the installed microfeed version. It defines every path, method, field, permission, response, and compatibility rule; this overview deliberately does not maintain a second endpoint list.

For retry-safe writes, use the idempotency behavior documented by the selected operation. Generate one key per logical action and reuse it with the same payload for every retry. When a webhook-triggered integration writes back, also propagate the event’s correlation ID and use the triggering event ID as the causation ID so the receiver can recognize its own effects.

The microfeed API Explorer showing parameters, JavaScript fetch code, and the response schema for fetching a feed

Every direct integration request requires an mf_… API key sent as a Bearer credential. A named key can allow reads, writes, or both; write permission does not need to be granted to read-only indexing, export, or notification services. Dashboard login credentials are never sent to content API routes. Create a separate least-privilege key for each integration so it can be rotated or revoked without interrupting other clients.

Documentation formats on each instance

Section titled “Documentation formats on each instance”

When API access and Publish API docs are both enabled, replace <site-url> with that microfeed site’s public URL. The URLs below link to the always-public microfeed.org demo:

Resource URL
Interactive API docs <site-url>/api/v1/
OpenAPI JSON <site-url>/api/v1/openapi.json
OpenAPI YAML <site-url>/api/v1/openapi.yaml
Compact agent reference <site-url>/api/v1/llms.txt
Self-contained agent reference <site-url>/api/v1/llms-full.txt

Public docs do not reveal API keys. The interactive public page describes the contract but does not persist authentication. Older /json/openapi.html and /json/openapi.yaml links redirect to the new locations only while public API docs are enabled.

Ask a coding agent to read the API contract

Section titled “Ask a coding agent to read the API contract”

The public demo’s self-contained llms-full.txt reference combines the API guide and complete generated OpenAPI contract in one text file. Give a coding agent this prompt before it designs or changes an integration:

Read https://www.microfeed.org/api/v1/llms-full.txt before writing code. Use
the generated OpenAPI contract in that file as the source of truth for paths,
methods, request and response fields, Bearer authentication, permissions,
pagination, idempotency, and errors.


I want to <describe the integration or API task>. First identify the smallest
set of operations and least-privilege API permissions it needs. Then explain
the data flow and implement it without guessing undocumented fields or routes.
Keep API credentials in environment variables, never print them, and do not
deploy or make destructive requests without my approval.

For an integration targeting a particular self-hosted site, replace the public URL in the prompt with <site-url>/api/v1/llms-full.txt. That instance file matches its installed microfeed version exactly.

The top-level OpenAPI webhook operation contains exact schemas and a named example for every supported event. Inspect those events in Admin → Webhooks → Event explorer and use Build webhook endpoints for receiver code and local signed testing.

Choose your next step

Section titled “Choose your next step”

This documentation page is the stable central overview. The generated per-instance files remain the source of truth for the exact microfeed release an integration is calling; the docs site does not keep a duplicate OpenAPI specification.