substack-api

Substack API Skill

You can drive Substack programmatically using their internal cookie-authenticated API. There is no public API key program — auth is the session cookie a normal browser uses.

When to use this skill

Trigger phrases (not exhaustive):

• "post to Substack" / "send via Substack"
• "create a draft in [my Substack]"
• "publish to {publication}.substack.com"
• "import my Substack subscribers"
• "read my Substack posts"
• "schedule a Substack send"

Before you do anything

You need TWO pieces of state from the user:

1. Session cookie — connect.sid value (or substack.sid on older accounts). See AUTH.md for how to obtain.
2. Publication subdomain — e.g. yournewsletter (NOT the full URL). Get this from /api/v1/user/profile/self if not supplied.

Always confirm both before making mutating calls. If the user supplied a URL like https://yournewsletter.substack.com, parse out the subdomain.

Canonical request shape

Cookie: connect.sid=<value>; substack.sid=<value>
User-Agent: Mozilla/5.0

Mozilla/5.0 is enough — default Node/Python User-Agents get 403'd.

The five operations you'll actually do

1. Validate a cookie + discover the user's publications

GET https://substack.com/api/v1/user/profile/self

Returns {id, handle, publicationUsers: [{publication: {id, name, subdomain}, role, is_primary}]}.

• Any 200 = cookie valid
• 401 = cookie expired or wrong
• Pick the publication via subdomain — show user a picker if multiple exist

2. Create a draft (no send)

POST https://{subdomain}.substack.com/api/v1/drafts
Content-Type: application/json

{
  "draft_title": "Subject line",
  "draft_subtitle": "Optional preheader",
  "draft_body": "<p>HTML body</p>",
  "type": "newsletter"
}

draft_body accepts HTML. Substack will normalize. Returns the draft object with id and slug.

3. Update an existing draft (Replace flow)

PUT https://{subdomain}.substack.com/api/v1/drafts/{id}
Content-Type: application/json

{ "draft_title": "...", "draft_subtitle": "...", "draft_body": "..." }