HTTP Endpoints

REST API reference for Markdown-OS client applications

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

curl http://localhost:8000/

import httpx

response = httpx.get("http://localhost:8000/")
html = response.text

const response = await fetch('http://localhost:8000/');
const html = await response.text();

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

curl http://localhost:8000/api/mode

import httpx

response = httpx.get("http://localhost:8000/api/mode")
data = response.json()
print(data["mode"])  # "file" or "folder"

const response = await fetch('http://localhost:8000/api/mode');
const data = await response.json();
console.log(data.mode);  // "file" or "folder"

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

curl http://localhost:8000/api/file-tree

import httpx

response = httpx.get("http://localhost:8000/api/file-tree")
tree = response.json()

const response = await fetch('http://localhost:8000/api/file-tree');
const tree = await response.json();

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 (file mode)

curl http://localhost:8000/api/content

curl "http://localhost:8000/api/content?file=getting-started/installation.md"

import httpx

# Folder mode
response = httpx.get(
    "http://localhost:8000/api/content",
    params={"file": "getting-started/installation.md"}
)
data = response.json()
print(data["content"])

// Folder mode
const params = new URLSearchParams({ file: 'getting-started/installation.md' });
const response = await fetch(`http://localhost:8000/api/content?${params}`);
const data = await response.json();
console.log(data.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 (file mode)

curl -X POST http://localhost:8000/api/save \
  -H "Content-Type: application/json" \
  -d '{"content": "# Updated Content\n\nNew text here."}'

curl -X POST http://localhost:8000/api/save \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Updated Content\n\nNew text here.",
    "file": "getting-started/installation.md"
  }'

import httpx

# Folder mode
response = httpx.post(
    "http://localhost:8000/api/save",
    json={
        "content": "# Updated Content\n\nNew text here.",
        "file": "getting-started/installation.md"
    }
)
data = response.json()
print(data["status"])  # "saved"

// Folder mode
const response = await fetch('http://localhost:8000/api/save', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    content: '# Updated Content\n\nNew text here.',
    file: 'getting-started/installation.md'
  })
});
const data = await response.json();
console.log(data.status);  // "saved"

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

curl -X POST http://localhost:8000/api/images \
  -F "file=@screenshot.png"

import httpx

with open("screenshot.png", "rb") as f:
    response = httpx.post(
        "http://localhost:8000/api/images",
        files={"file": ("screenshot.png", f, "image/png")}
    )
data = response.json()
print(f"![Screenshot]({data['path']})")

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('http://localhost:8000/api/images', {
  method: 'POST',
  body: formData
});
const data = await response.json();
console.log(`![Image](${data.path})`);

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

curl http://localhost:8000/images/screenshot-20260228-103000-123456.png \
  -o downloaded.png

import httpx

response = httpx.get(
    "http://localhost:8000/images/screenshot-20260228-103000-123456.png"
)
with open("downloaded.png", "wb") as f:
    f.write(response.content)

![Screenshot](http://localhost:8000/images/screenshot-20260228-103000-123456.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.