Substack API Key: Publisher API and Developer API (2026)

Searching for a "Substack API key" usually ends in forum threads, because Substack has no developer portal and no public sign-up page for keys. There are two kinds of key as of October 2026, though, and they do very different things. This guide covers what each one returns, how to tell whether you have access, and what the terms say. For the full map of Substack's developer surfaces, start with our Substack API guide.

newsletterapi is an independent project, not affiliated with Substack. Nothing below depends on newsletterapi.

The problem

You want your own numbers in your own tools: a reporting dashboard, a spreadsheet, a board update. One operator on X asked simply for "easy api access for internal reporting tools" (@johnpgarrett). Another wrote on LinkedIn: "There's no API that exposes your Substack revenue." (LinkedIn). And a long-time writer summed up the mood: "The analytics never really improved, and there's still no API." (@rishikeshshari).

The confusion is understandable. Substack does issue keys, but one of them is undocumented in public and the other is a narrow lookup tool whose help page has been taken down.

Which Substack API keys exist?

	Publisher API key	Developer API token
What it reads	Your own publication: posts, post stats, subscriber counts, single-email lookup	Public creator profiles, looked up by LinkedIn handle
Write access	None	None
How you get it	Generated in your publication's dashboard, where enabled	Apply, wait for approval, then create a token in Settings
Scope	One publication per key	Your account
Public docs	Behind the key	Archived copy only
Terms	Not public	Developer API Terms, January 8, 2026

If you want your own publication's data, the Publisher API is the one that matters. The Developer API is for discovering other creators.

What does the Substack Publisher API return?

Substack has not published public documentation for the Publisher API. Its base URL is https://publisher-api.substack.com/v1; without a key, /v1/posts answers 401 and the docs page at /v1/docs/ answers 403 (checked 2026-10-22). The best public description is the open-source substack-publisher-mcp wrapper. Everything in this table comes from that wrapper's README and code, so treat it as self-reported by its author, not confirmed by Substack:

Endpoint	What it returns (per the wrapper)
GET /posts	post_id, title, subtitle, audience, postDate, urlSlug, coverImage, plus a next cursor for paging; filters for dates, type and sort
GET /posts/search?query=	Posts matching a full-text query
GET /posts/{urlSlug}	One post, with its body as a ProseMirror JSON document
GET /posts/{urlSlug}/stats	recipients, opens, clicks, views, new_free_subscriptions, new_paid_subscriptions, estimated_revenue_increase
GET /subscribers/counts	Daily rows of total_email_subscribers, paid_subscribers, free_trial_subscribers, comp_subscribers, gift_subscribers, lifetime_subscribers, founding_subscribers
GET /subscribers/{email}	One subscriber's membership type, expiry, payment dates and bounce flag; 404 if the email isn't subscribed

According to the wrapper's API client code, the raw key goes in an authorization header with no Bearer prefix, and the client handles a 429 "rate limited" response. The actual rate limits are not public.

What it does not do matters just as much:

• It is read-only. No publishing, no drafts, no Notes, no adding subscribers.
• It cannot list your subscribers. You can check an email you already have, but not page through the list. For that, use the subscriber CSV export (help).
• Keys are per publication. If you run three newsletters, you need three keys.
• There are no webhooks. You poll it; it never calls you. See Substack webhooks for what exists instead.

How do I check whether the Publisher API is enabled for me?

1. Look in your dashboard. The wrapper's README says to generate the key from your publication's dashboard and adds: "If you don't see a Publisher API option there, it may not be enabled for your publication yet." We found no Substack help-centre article that explains eligibility, so there is no official list of who gets it.
2. Test the key from a terminal if you have one. A 200 means it works; a 401 means the key is wrong or revoked:

export SUBSTACK_PUBLISHER_API_KEY="paste-your-key-here"
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "authorization: $SUBSTACK_PUBLISHER_API_KEY" \
  "https://publisher-api.substack.com/v1/posts?maxResults=1"

3. Keep the key server-side. It can look up whether any email is a paying subscriber, so treat it like a password: environment variables or a secrets manager, never a public repo or a browser script.

For working Python, including paging through every post and pulling stats, see our Substack API Python tutorial. To use the key from an AI assistant, the same wrapper runs as an MCP server; see Substack MCP server: official vs open source.

What is the Substack Developer API?

It is a single lookup endpoint for public creator profiles. The help article, now only available as a Wayback Machine copy from May 2026, said the API "allows Substack users who have agreed to the API's Terms of Use to retrieve public information on Substack profiles by querying a creator's public LinkedIn handle."

What the archived doc describes:

• Endpoint: GET https://substack.com/profile/search/linkedin/{linkedin-handle}.
• Fields: identityHandle, profileUrl, leaderboard status, bestsellerTier, roughNumFreeSubscribers and followerCount.
• Access: apply through a form, wait for approval (the April 2026 version said 7-10 business days), then create a token in Settings.
• No write access.

As of 2026-10-22 the help article returns a 404 from Substack's help centre, although the terms still link to it. It cannot read your own posts or stats, so it is not a route to your own data.

What do the Substack API terms allow?

The Developer API Terms of Use (last updated January 8, 2026) are the only published API terms. They say you "may cache Authorized Data only as reasonably necessary", must not "redistribute Authorized Data as a standalone product or dataset", and must not "replicate, substitute for, or materially compete with core features of the Substack platform". Use is "subject to rate limits, quotas, and other technical restrictions as determined by Substack in its sole discretion", and you agree "not to circumvent or attempt to bypass such restrictions."

Separate terms for the Publisher API are not public as of October 2026. The general Terms of Use still apply to everything, including the ban on letting "someone else log into Substack as you". An official key is the safe alternative to tools that ask for your password or session.

What can I use if I don't have a key?

You want	Use this	Notes
Recent public posts	Your RSS feed	See the Substack RSS feed guide
Full archive, including paid posts	Settings, Exports (help)	A zip of posts, subscriber list and statistics
Stats in an AI assistant	Substack's official MCP server	Admins of Bestseller publications only (help)
Growth and engagement analysis	Your export, analysed	Subscriber analytics from your export
Your archive as JSON	The newsletterapi Posts API	Built on your feed and your export

Our analytics API turns the export you already have into growth, cohort and engagement data, with no Substack key and no login. To get access, see pricing or email hello@newsletterapi.io.