API reference

PullMD is self-hosted, so every request goes to your own instance. Replace http://localhost:3000 with your PUBLIC_URL.

Conversion endpoints return Markdown (text/markdown) by default. Add format=json for a JSON envelope or format=text for plain text.

The MCP server is at /mcp. Its tools are described on MCP tools.

Base URL

http://localhost:3000

Authentication

• bearerAuth: send Authorization: Bearer <token>. Needed only when the instance has sign-in enabled (PULLMD_AUTH_MODE is single-admin or multi-user). Send Bearer pmd_<key> with an API key created at /settings. In single-admin mode, the legacy PULLMD_AUTH_TOKEN is also accepted as a bearer token. OAuth access tokens work only on /mcp. Browser sessions use the pullmd_session cookie instead. Each endpoint's page says whether it needs this.

OpenAPI specification

Download the full spec to import into Postman or Insomnia, generate a client, or give to an AI tool: openapi.yaml.

Endpoints

Convert

Turn a URL, an HTML document or an uploaded file into Markdown.

	Endpoint
GET	/api	Convert a URL
POST	/api/html	Convert HTML
POST	/api/file	Convert a file
GET	/api/stream	Convert a URL with progress
GET	/share	Open a link in the web app

Share links

Read a cached conversion by its share id.

	Endpoint
GET	/s/{id}	Get a shared conversion

History and cache

List and delete cached conversions.

	Endpoint
GET	/api/history	List recent conversions
GET	/api/archive	Page through all conversions
DELETE	/api/cache/{id}	Delete a conversion
DELETE	/api/cache	Delete all conversions

Instance

Health, configuration and usage of the instance. These endpoints never require sign-in.

	Endpoint
GET	/api/status	Check sidecar health
GET	/api/config	Get enabled features
GET	/api/recipes/status	Check site recipes
GET	/api/stats	Get extraction stats
GET	/api/storage	Get cache size

Account

The signed-in user.

	Endpoint
GET	/api/me	Get the current user
POST	/api/keys	Create an API key
POST	/api/keys/{id}/revoke	Revoke an API key