Markdown Blog Developer Portal

Markdown Blog Developer Resources & API Documentation

The central reference for integrating with Markdown Blog (markdownblog.dev): REST API v1 endpoints, official CLI tool, OpenAPI 3.1 specification, rate limiting, and RFC 9110 content negotiation.

Markdown Blog REST API Reference (v1)

All REST API endpoints are versioned under https://markdownblog.dev/api/v1/. Authenticated requests use standard JSON request and response bodies with RFC RateLimit headers and typed errors.

POST/api/v1/blogs/posts

Create a new research-backed Markdown article draft with frontmatter and citations.

Create Post
GET/api/v1/posts

Retrieve posts belonging to your workspace, with optional id, blogId, status, and limit filters.

List Posts

Markdown Blog Authentication & API Keys

Authenticate API requests by passing your workspace API key in the x-api-key header or as a Bearer token in the Authorization header:

Authentication Header

API keys are generated and scoped in your workspace settings under Dashboard > Settings > API Keys.

Structured JSON Error Responses (RFC 9457)

All API errors return structured JSON objects (with application/json and application/problem+json content types). AI agents and programmatic clients never receive HTML error pages:

Structured Error Format

Markdown Blog API Versioning and Deprecation Policy

Markdown Blog uses explicit URL path versioning (currently /api/v1/). Every API response includes the X-API-Version and Deprecation headers.

  • Stability Guarantee: Breaking changes are never introduced within an active version.
  • Sunset Timeline: Deprecated versions receive a minimum of 90 days advance notice before retirement.
  • Deprecation Signaling: Approaching deprecations are signaled via RFC 8594 Deprecation, Sunset, and Link: rel="deprecation" response headers.

Markdown Blog Rate Limiting & RFC Headers

The API enforces application-level rate limits (60 requests per minute per API key). Every response provides standard RFC rate limiting headers allowing automated agents to self-throttle in real time:

  • RateLimit-Limit: 60
  • RateLimit-Remaining: 59
  • RateLimit-Reset: 60
  • RateLimit-Policy: 60;w=60
  • Retry-After: 60 (sent on HTTP 429 responses)

Markdown Blog Official CLI Tool

The official Markdown Blog CLI (markdownblog) enables developers and agents to script publishing, convert content, and audit frontmatter directly from the command line:

CLI Installation & Quickstart
markdownblog whoami

Verify API key connectivity and account privileges.

markdownblog posts list

List posts belonging to your workspace.

markdownblog posts get <id> -o ./post.md

Pull post Markdown and frontmatter into local Git repo.

markdownblog audit <file.md>

Audit frontmatter, reading time, and heading hierarchy.

markdownblog convert <file.html>

Convert HTML or stdin to clean Markdown with tables.

Markdown Blog OpenAPI 3.1 Specification

Our full OpenAPI 3.1.0 specification with complete schemas, typed error contracts, and function calling definitions is available at predictable URLs:

Download /api/openapi.jsonEndpoint /api/openapi

Markdown Blog RFC 9110 Content Negotiation

Every public page on markdownblog.dev supports RFC 9110 content negotiation. Passing Accept: text/markdown returns pure Markdown:

Content Negotiation Request

Markdown Blog Model Context Protocol (MCP) Integration

Markdown Blog exposes an MCP-compatible surface for Anthropic Claude, Cursor, and custom AI agents. Connect via the official CLI with your API key to access real-time post creation, citation retrieval, and blog management tools.

Agent Discovery Files

  • /llms.txt: Machine-readable agent capabilities and usage guidelines.
  • /llms-full.txt: Extended catalog of utilities, endpoints, and tool definitions.
  • /sitemap.xml: URL directory for automated crawlers and search indexers.
Plans and pricingDeveloper supportView llms.txt