Skip to main content
This page documents all HTTP endpoints exposed by the Markdown-OS server. Use these endpoints to interact with the editor programmatically from your client applications.

​
Base URL

When running locally: 
http://localhost:8000
When running in a cloud VM: 
http://0.0.0.0:8000
The server auto-increments the port if 8000 is occupied. Check the CLI output for the actual URL.

​
Editor Interface

​
GET /

Serves the main editor web application HTML page. Response: HTML document with the editor interface Example: 
curl http://localhost:8000/

​
GET /favicon.ico

Redirects to the SVG favicon at /static/favicon.svg. Response: 302 redirect

​
Mode Information

​
GET /api/mode

Returns the current server mode (“file” or “folder”). Response:
​
mode
string
required
Either “file” (single file editing) or “folder” (directory workspace)
Example: 
curl http://localhost:8000/api/mode
Sample Response: 
{
  "mode": "folder"
}

​
File Tree

​
GET /api/file-tree

Returns the markdown file tree structure for folder mode.
This endpoint is only available when the server is running in folder mode. Returns a 400 error in file mode.
Response:
​
root
object
Nested structure representing the directory tree with folders and markdown files
Example: 
curl http://localhost:8000/api/file-tree
Sample Response: 
{
  "name": "docs",
  "type": "directory",
  "children": [
    {
      "name": "getting-started",
      "type": "directory",
      "children": [
        {
          "name": "installation.md",
          "type": "file",
          "path": "getting-started/installation.md"
        }
      ]
    },
    {
      "name": "README.md",
      "type": "file",
      "path": "README.md"
    }
  ]
}

​
Content Management

​
GET /api/content

Retrieve markdown content and metadata for a file. Query Parameters:
​
file
string
Relative file path (required in folder mode, ignored in file mode)
Response:
​
content
string
required
Raw markdown content of the file
​
metadata
object
required
File metadata including size, timestamps, and path information
​
size
integer
File size in bytes
​
modified
string
Last modified timestamp (ISO 8601 format)
​
relative_path
string
Relative path from workspace root (folder mode only)
Example: 
curl http://localhost:8000/api/content
Sample Response: 
{
  "content": "# Installation\n\nInstall Markdown-OS using pip...\n",
  "metadata": {
    "size": 1024,
    "modified": "2026-02-28T10:30:00Z",
    "relative_path": "getting-started/installation.md"
  }
}
Error Responses:
  • 400: Missing file parameter in folder mode or invalid file path
  • 404: File not found
  • 500: File read error

​
POST /api/save

Save markdown content to disk with atomic file replacement. Request Body:
​
content
string
required
Markdown content to save
​
file
string
Relative file path (required in folder mode, ignored in file mode)
Response:
​
status
string
required
Always “saved” on success
​
metadata
object
required
Updated file metadata after save
​
size
integer
New file size in bytes
​
modified
string
Updated timestamp (ISO 8601 format)
​
relative_path
string
Relative path from workspace root (folder mode only)
Example: 
curl -X POST http://localhost:8000/api/save \
  -H "Content-Type: application/json" \
  -d '{"content": "# Updated Content\n\nNew text here."}'
Sample Response: 
{
  "status": "saved",
  "metadata": {
    "size": 1156,
    "modified": "2026-02-28T10:35:00Z",
    "relative_path": "getting-started/installation.md"
  }
}
Error Responses:
  • 400: Missing file parameter in folder mode or invalid file path
  • 404: File not found (folder mode)
  • 500: File write error
Saving triggers a file watcher event, but the server ignores events from its own writes for 500ms to prevent infinite loops.

​
Image Management

​
POST /api/images

Upload an image to the workspace images directory. Request: multipart/form-data with file upload
​
file
file
required
Image file to upload
Supported Formats:
  • .png
  • .jpg, .jpeg
  • .gif
  • .webp
  • .svg
  • .bmp
  • .ico
Constraints:
  • Maximum file size: 10 MB
  • File must not be empty
  • Extension must be in the allowed list
Response:
​
path
string
required
Relative path to use in markdown (e.g., images/screenshot-20260228-103000-123456.png)
​
filename
string
required
Generated unique filename with timestamp
Example: 
curl -X POST http://localhost:8000/api/images \
  -F "file=@screenshot.png"
Sample Response: 
{
  "path": "images/screenshot-20260228-103000-123456.png",
  "filename": "screenshot-20260228-103000-123456.png"
}
Error Responses:
  • 400: Unsupported format, empty file, or file too large
Filenames are sanitized and timestamped to prevent collisions. The original filename is preserved in the stem (e.g., screenshot.png becomes screenshot-20260228-103000-123456.png).

​
GET /images/{filename}

Serve an uploaded image from the workspace images directory. Path Parameters:
​
filename
string
required
Image filename (can include subdirectories)
Response: Image file with appropriate content type Example: 
curl http://localhost:8000/images/screenshot-20260228-103000-123456.png \
  -o downloaded.png
Error Responses:
  • 400: Invalid path (contains .. or starts with /)
  • 404: Image not found
Security:
Path traversal attempts are blocked. The server validates that resolved paths stay within the images directory.

​
Static Assets

​
GET /static/{path}

Serves static frontend assets (JavaScript, CSS, fonts, icons). Example: 
GET /static/favicon.svg
GET /static/main.js
GET /static/styles.css
Static files are served from the markdown_os/static/ directory in the package.

Build docs developers (and LLMs) love

Get started for freeTalk to us