Publish Markdown to Medium on a schedule

1. On the Medium homepage, click Write to open a new draft and paste the text from your Markdown file.
2. Rebuild the formatting in the Medium editor: select a line and click the large T for a header or the small T for a subheader, and type * or 1. plus Space to start a list.
3. Upload each image again: on a new line, click the button on the left to expand the menu, then click Image. The Medium editor accepts JPG, JPEG, GIF and PNG files up to 25MB.
4. Click Publish, type up to five topics, then click Schedule for later, enter the date and time and click Schedule to publish.
5. Do it again for every post. Third-level headings, tables and footnotes have no direct match in the Medium editor, so each post needs the same manual fixes.

Turn posts/shipping-small.md into a Medium draft with the topics Python, Programming and Software Engineering, put it behind the paywall, and schedule it for Tuesday 8:00 my time.

1. 01

   Map the Markdown to Medium's formats

   The agent turns the first heading into the title and an optional lead line into the subtitle. H2 becomes a Medium header and H3 or deeper becomes a subheader, because the editor offers only two sizes. Footnotes become superscript numbers with a notes list at the end, since Medium has no footnotes.

2. 02

   Decide what has no Medium match

   A table or a LaTeX formula cannot be rendered in a Medium story. The agent asks whether to turn each one into a list, a code block or an image you provide, and does not drop it silently.

3. 03

   Create the draft with its settings

   create_draft gets the body, up to five topics, the canonical link if the post lives elsewhere too, and the paywall choice. Local image paths are a stop: images must be public URLs, so the agent lists the missing ones and waits.

4. 04

   Read the draft back before scheduling

   get_story returns what Medium stored. The agent compares heading count, image count and code blocks with the source file and reports any difference before going further.

5. 05

   Schedule in your time zone

   schedule_story gets the slot with your time zone spelled out, so 8:00 means 8:00 where you live. If another story is already scheduled within an hour of that slot, the agent asks before stacking them.

shipping-small.md: draft created, 1,840 words.
Title and subtitle from the first two lines; 4 headers, 2 subheaders (were H3).
3 footnotes turned into superscript and a Notes section.
1 table converted to a list after your OK.
Topics: Python, Programming, Software Engineering. Paywall on.
Scheduled Tue 20 Oct 8:00 (Europe/Berlin).

• The Medium editor has two heading sizes: the large T makes a header and the small T a subheader, and a header on the first line of a story becomes its title.
• Medium does not support footnotes or math in stories; its help center suggests manual superscript notes and an embed such as embed.fun for LaTeX.
• Medium publishes a scheduled story within five minutes of the time you set, and publish times use your local time zone.
• Edits to a scheduled Medium story go out with it at the publish time, and editing does not cancel or move the schedule.
• Medium shows every image placement option only for images at least 1192px wide.

schedule_story asks for your OK by default. To run it weekly without you, switch confirmation off for that tool in your dashboard.

Sources: Medium Help: Using the story editor · Medium Help: Schedule to publish · Medium Help: Using images · Medium API documentation (archived)

curl https://cotlet.dev/api/v1/medium/create_draft \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Shipping small","subtitle":"Why small releases win","body_markdown":"Small releases beat big ones.\n\n## Here is why","tags":["Python","Programming","Software Engineering"],"paywalled":true}'

{
  "story_id": "3f9a1c27b84e",
  "status": "draft",
  "url": "https://medium.com/p/3f9a1c27b84e/edit"
}

MCP: add https://cotlet.dev/mcp/v1 with the same key; the tool is medium_create_draft. Example data.

• Cross-post blog articles to Medium with a canonical link
• Get a weekly Medium stats and earnings report
• Update old Medium stories in bulk
• Medium API and MCP server: every tool
• All use cases