Substack API

A modern, type-safe TypeScript client for the Substack API. Build newsletter automation, content management tools, and subscriber analytics with ease.

QuickStart

pnpm add substack-api

import { SubstackClient } from 'substack-api';

const client = new SubstackClient({
  token: '<your-bearer-token>',      // see "Authentication" below
  publicationUrl: 'https://yoursite.substack.com'
});

// Get your profile and iterate through posts
const profile = await client.ownProfile();
for await (const post of profile.posts({ limit: 5 })) {
  console.log(`"${post.title}" - ${post.publishedAt?.toLocaleDateString()}`);
}

// Test connectivity
const isConnected = await client.testConnectivity();

Authentication

All requests are proxied through the substack-gateway and authenticated with a Bearer token that encodes two Substack session cookies.

Step 1 — Obtain your session cookies

1. Log in to substack.com in your browser.
2. Open DevTools → Application → Cookies → substack.com.
3. Copy the values of substack.sid and connect.sid.

Step 2 — Build the token

The token is a base64-encoded JSON object containing both cookies:

const token = btoa(JSON.stringify({
  substack_sid: '<value of substack.sid cookie>',
  connect_sid:  '<value of connect.sid cookie>'
}));

In Node.js you can also use Buffer:

const token = Buffer.from(JSON.stringify({
  substack_sid: '<value of substack.sid cookie>',
  connect_sid:  '<value of connect.sid cookie>'
})).toString('base64');

Step 3 — Pass the token to the client

const client = new SubstackClient({
  token,
  publicationUrl: 'https://yoursite.substack.com'
});

Documentation

📚 Complete Documentation →

• Installation Guide - Setup and requirements
• QuickStart Tutorial - Get started in minutes
• API Reference - Complete method documentation
• Entity Model - Modern object-oriented API
• Examples - Real-world usage patterns

License

MIT