How to Use Ghost APIs & Swagger

The Ghost Blog REST API runs on port 3500 inside the container and manages the syncing, listing, and uploading of markdown documentation files dynamically.

🔒 Security & Swagger UI Access

For security reasons, access to Swagger UI (/api-docs) and the raw Swagger JSON specification (/api-docs.json) is restricted to localhost connections only. Trying to access them publicly via the Traefik router (e.g., https://blog-api.fabrixly.com/api-docs) will return a 403 Forbidden response.

To access the interactive Swagger documentation, you must set up an SSH Port Forwarding Tunnel.

Step 1: Open an SSH Tunnel

Run the following command in your local terminal:

ssh -i /path/to/vps_ssh_key -L 3500:localhost:3500 deploy@95.111.231.166

This binds port 3500 on your local machine to port 3500 (localhost) of the remote VPS.

Step 2: Open Swagger in Your Browser

Once the SSH connection is established, open your web browser and go to:

👉 http://localhost:3500/api-docs

You will now be able to view, search, and interactively test all the Ghost management and documentation APIs.

🔑 Authentication

All modification and sync endpoints require the x-api-key header to be sent with the request:

• Header name: x-api-key
• Token value: ZeroBlogAPI@Fabrixly2026Secret

🔌 API Endpoints Summary

1. Document Operations

• Sync All local docs (POST /api/docs/sync)
  • URL: http://localhost:3500/api/docs/sync (or publicly via Traefik: https://blog-api.fabrixly.com/api/docs/sync)
  • Description: Scans the VPS /app/docs directory and publishes/updates all markdown files to Ghost.
• Upload Single Markdown File (POST /api/docs/upload)
  • URL: http://localhost:3500/api/docs/upload
  • Content-Type: multipart/form-data
  • Payload: Form field file containing the .md file.
  • Description: Saves the markdown file to the /docs folder and syncs it.
• Upload Multiple Markdown Files (POST /api/docs/upload-many)
  • URL: http://localhost:3500/api/docs/upload-many
  • Content-Type: multipart/form-data
  • Payload: Form field files containing multiple .md files.
• Sync Raw Markdown Text (POST /api/docs/from-markdown)
  • URL: http://localhost:3500/api/docs/from-markdown
  • Content-Type: application/json

Body:

{
  "filename": "my-guide.md",
  "content": "---\ntitle: \"My Guide\"\nslug: \"my-guide\"\n---\n# Content"
}

2. Manifest & List Operations

• List Files (GET /api/docs/list)
  • URL: http://localhost:3500/api/docs/list
  • Description: Lists all local markdown files and their parsed frontmatter status.
• View Manifest (GET /api/docs/manifest)
  • URL: http://localhost:3500/api/docs/manifest
  • Description: Displays the raw .ghost-manifest.json file showing filename-to-GhostID mapping.
• Cleanup Orphans (POST /api/docs/cleanup)
  • URL: http://localhost:3500/api/docs/cleanup
  • Payload: { "dry_run": false }
  • Description: Deletes posts from Ghost that are no longer present in the local manifest.