API Documentation

Create a share

POST /api/share with a JSON body. expiry is one of 1d, 7d, 30d (default), or never.

curl -X POST https://docs-md.com/api/share \
  -H "Content-Type: application/json" \
  -d '{"content": "# Hello", "filename": "hello.md", "expiry": "never"}'

# Response
{
  "success": true,
  "id": "misty-fox-a1b2c",
  "url": "https://docs-md.com/misty-fox-a1b2c",
  "rawUrl": "https://docs-md.com/raw/misty-fox-a1b2c",
  "editToken": "…",
  "expiresAt": 0
}

Save the editToken — it is shown once and is the only way to update or delete the share. expiresAt is a Unix timestamp in milliseconds, or 0 for permanent links.

Read raw markdown

Every share has a raw endpoint that returns plain text/markdown — handy for scripts, CI, and piping into other tools.

curl https://docs-md.com/raw/misty-fox-a1b2c

Update a share

PATCH /api/share/:id with the edit token in the x-edit-token header. The share URL stays the same.

curl -X PATCH https://docs-md.com/api/share/misty-fox-a1b2c \
  -H "Content-Type: application/json" \
  -H "x-edit-token: YOUR_EDIT_TOKEN" \
  -d '{"content": "# Updated content"}'

Delete a share

curl -X DELETE https://docs-md.com/api/share/misty-fox-a1b2c \
  -H "x-edit-token: YOUR_EDIT_TOKEN"

Publish a markdown report from GitHub Actions

GitHub already renders a job summary inside the Actions run. Use Docs MD when the report needs its own reading link for someone outside the run — a collaborator without repo access, a release thread, a Slack channel — or its own lifetime. This recipe publishes a generated markdown file with a 7-day expiry, prints the reading URL, fails the step on an API error, and keeps the edit token out of the log.

If you would rather not maintain the script, the same steps are packaged as a reusable GitHub Action: uses: invisible-hand/share-markdown-action@v1 with file and expiry inputs and a url output.

#!/usr/bin/env bash
# scripts/publish-report.sh — usage: publish-report.sh report.md [expiry]
set -euo pipefail
file="${1:?markdown file}"; expiry="${2:-7d}"
payload=$(jq -Rs --arg f "$(basename "$file")" --arg e "$expiry"   '{content: ., filename: $f, expiry: $e}' "$file")
resp=$(curl -sS --fail-with-body -X POST https://docs-md.com/api/share   -H "Content-Type: application/json" --data "$payload") || { echo "::error::publish failed: $resp"; exit 1; }
token=$(jq -r .editToken <<<"$resp")
[ -n "${GITHUB_ACTIONS:-}" ] && echo "::add-mask::$token"   # never print the token in CI logs
url=$(jq -r .url <<<"$resp")
echo "Report: $url"
[ -n "${GITHUB_OUTPUT:-}" ] && echo "url=$url" >> "$GITHUB_OUTPUT"

And the workflow step that uses it after a bundle-size comparison has written its table:

# .github/workflows/bundle-report.yml (excerpt)
- name: Write bundle-size report
  run: |
    {
      echo "# Bundle size — PR #${{ github.event.number }}"
      echo
      echo "| Chunk | main | this PR | Δ |"
      echo "| --- | ---: | ---: | ---: |"
      echo "| app.js | 412.3 KB | 398.1 KB | −14.2 KB |"
      echo "| vendor.js | 1.02 MB | 1.02 MB | 0 |"
    } > bundle-report.md
- name: Publish report
  id: publish
  run: bash scripts/publish-report.sh bundle-report.md 7d
- name: Link it from the job summary
  run: echo "Readable report: ${{ steps.publish.outputs.url }}" >> "$GITHUB_STEP_SUMMARY"

The published page is public to anyone with the link, so keep secrets and private hostnames out of the report. If you want to update the same URL on every run instead of creating a new one, store the id and edit token as repository secrets and call PATCH as shown above.

Limits

• Markdown content up to 120,000 characters per share.
• Rate limit: 20 share operations per minute per IP (30/min for MCP).
• Expired shares and their files are deleted automatically; the URL then returns 404. Expiry does not recall copies already downloaded.
• Shares are public URLs. The edit token controls changes, not reading.

MCP server

The same operations are available to AI assistants through our MCP server at https://docs-md.com/api/mcp with tools share_markdown, update_share, and delete_share. See the setup guide for per-editor configuration, and the agent handoff walkthrough for a script-and-MCP example end to end.