AnthonyDavidAdams/substack-api-reference

# Substack API 参考（非官方） [](LICENSE)   这是一份实用且经过验证的 Substack 未公开内部 API 参考。这里的每个端点都经过了针对线上 API 的测试。专为人类**和** AI 代理设计（参见 [`SKILL.md`](SKILL.md)）。 ## 为什么会有这个项目 Substack 的 Web 应用通过 `https://substack.com/api/v1/*` 以及各个出版物的子域名 `https://.substack.com/api/v1/*` 与 JSON API 进行通信。Web 应用的一切操作都依赖于它：阅读文章、创建草稿、发布、管理订阅者、发送聊天会话、配置推荐。只要有 session cookie，你就可以在任何脚本中调用同样的 API。 现有的社区项目涵盖了部分功能： - [NHagar/substack_api](https://github.com/NHagar/substack_api) — Python，专注于读取 - [ma2za/python-substack](https://github.com/ma2za/python-substack) — Python，完整的 CRUD - [jakub-k-slys/substack-api](https://github.com/jakub-k-slys/substack-api) — TypeScript（已归档） - [JPres-Projects/Substack-API](https://github.com/JPres-Projects/Substack-API) — Python，草稿 + 发布 本仓库旨在成为这些客户端共同依赖的**权威端点参考**。如果你发现了任何新内容，欢迎提交 PR。 ## 快速开始 ``` # 1. 获取你的 session cookie（有关 browser-extension 和 DevTools 路径，请参见 AUTH.md） COOKIE='s%3A...your.connect.sid.value...' # 2. 验证其是否有效 — 返回你的个人资料 + 你可以编辑的每一个 publication curl -H "Cookie: connect.sid=$COOKIE; substack.sid=$COOKIE" \ https://substack.com/api/v1/user/profile/self | jq .handle # 3. 在你 admin 的 publication 上创建草稿 curl -X POST \ -H "Cookie: connect.sid=$COOKIE; substack.sid=$COOKIE" \ -H "Content-Type: application/json" \ -d '{"draft_title":"Hello","draft_subtitle":"From the API","draft_body":"

Hi.

","type":"newsletter"}' \ https://yourname.substack.com/api/v1/drafts ``` ## 目录 - [`ENDPOINTS.md`](ENDPOINTS.md) — 所有已验证的端点，包含请求体结构、查询参数和示例响应 - [`AUTH.md`](AUTH.md) — 获取 cookie、格式、轮换，以及如何从服务端代码中发送 - [`SKILL.md`](SKILL.md) — Claude Agent SDK 技能清单 - [`examples/curl/`](examples/curl) — 开箱即用的 curl 脚本 - [`examples/typescript/`](examples/typescript) — 极简的强类型客户端 ## 覆盖范围 **读取端（被动 — 仅需 cookie 即可工作）：** - 身份验证、账号发现、公开资料、被屏蔽的用户 - 出版物 CRUD（读取）、设置、分区、标签、推荐、Stripe 状态、捐赠层级 - 草稿、定时发布的文章、已发布的文章、文章管理统计数 - 单篇文章的统计（包含打开率、CTR、每日明细、来源等 31 个互动字段） - 出版物级别的分析（订阅者、ARR、网络归因、增长来源/事件时间序列） - 订阅者列表（过滤/排序/分页）、私信/消息收件箱、活动流 - 读者收件箱（`/inbox/top`）、Notes 流 + 标签页、全局搜索、搜索模块 - 分类、响应目录、评论审核枚举、单篇文章的静音设置 **写入端（通过 Chrome 驱动 UI 捕获）：** - `PUT /publication` — 单字段保存（`name`、`hero_text`、`language`、`welcome_email_content` 等） - `PUT /publication_settings` — 布尔值开关（高清视频、拒绝 AI 训练、允许转发等） - 草稿：创建、更新、删除、发布、定时发布、scheduled_release - Notes：创建（`POST /comment/feed`）、删除、标记为已读 - 读者评论：创建、删除；**文章响应**（字面 emoji + `surface`） - **推荐**：添加（`PUT /recommendations`）、移除（`DELETE /recommendations/` — 注意末尾的斜杠）、搜索、建议 - **音频/播客上传** — 完整的 S3 预签名 multipart 流程（init → S3 PUT → transcode → poll） - **Substack Chat**：启用/禁用（`/publication_threads_settings`）、发送会话（客户端生成的 UUID）、删除会话 - 合著者邀请、订阅者添加/移除、文章标签附加/分离、图片上传 - 通用用户设置（`PUT /user-setting`） **已知的限制（已记录但此处不作破解）：** - `POST /publication` — 设计上受 captcha 拦截 - 自定义域名配置 — 需一次性支付 50 美元 + 设置 DNS - Magic-link 验证 — 位于 `/sign-in?token=...`，不在 `/api/v1/*` 下 - 带有原因的审核删除 — 需要借助其他用户的评论才能触发 ## 已验证 vs. 推测 [`ENDPOINTS.md`](ENDPOINTS.md) 中的每个端点都标有： - ✅ **已验证** — 亲自针对线上 API 进行过测试 - 🟡 **已报告** — 由其他客户端/博客文章记录，但未进行独立重测 - ❓ **推测** — 根据相关端点进行模式匹配，未观察到成功调用 - ❌ **已失效** — 经测试确认返回 404，记录在此以节省你的时间 - 🔒 **受限** — 存在，但从普通的 curl 调用会返回 403（通常在真实的浏览器中可以正常工作；参见 `ENDPOINTS.md` 中关于“双主机技巧”和“浏览器与 curl 的差异”的说明） 欢迎提交 PR，将状态从 ❓ 升级为 🟡 再到 ✅。 ## 构建方式 本参考文档是在 14 个渐进式的捕获轮次中构建完成的，并以 `Round N` 提交的形式记录。方法论技术栈包括： 1. 针对读取端点的 **Curl 探测** + 基于经验性错误的字段发现（通过发送故意无效的 POST，借助 Substack 的错误信息暴露出必填字段——`trigger_at` 以及其他几十个字段就是这样被发现的） 2. **Playwright headless 捕获** — 利用 session cookie 驱动 Chromium 访问后台 SPA，记录触发的每一个 `api/v1` 请求 3. **Chrome 扩展实时捕获**（[Claude in Chrome](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn)）— 通过由 `localStorage` 支持的日志机制对 `window.fetch` 和 `XMLHttpRequest.send` 进行 monkey-patching，确保请求体在 React 驱动的页面重载后依然留存；然后对真实出版物的操作执行“添加后还原”的循环，以此捕获那些无法被动获取的写入端请求体 为什么要同时使用这三种方法：被动观察可以让你“免费”获得读取端点和大量 POST 请求体。当错误信息具有描述性时（Substack 的错误信息正是如此），经验性探测可以填补这些空白。而实时驱动 UI 则能捕获那些请求体结构不那么直观的情况（比如字面意义上的 emoji 响应值、用于发送会话的客户端生成的 UUID、字符串化的 ProseMirror 欢迎邮件内容），以及那些通过 curl 调用会返回 403 但在真实浏览器 session 中却能返回 200 的端点（推荐设置就是一个典型的例子）。 ## 构建者 本参考文档由 [Anthony David Adams](https://substack.com/@anthonydavidadams) 和 [**EarthPilot.ai Lab**](https://earthpilot.ai) 整理编写 —— 这是一个小型的应用 AI 实验室，致力于为“太空船地球”构建任务支持系统：用于行星尺度的感知、决策和协调的工具与协议。我们在开发 Substack 相关的基础设施（简报平台、AI 编辑流水线、增长工具）时，被迫绘制了这套接口映射；将其回馈给社区是理所当然的事。 ### 奇点游乐场 (Singularity Playground) 如果你正处于 AI × 意义 × 基础设施的边缘工作——或者你想投身于此——欢迎来 **[Singularity Playground](https://earthpilot.co/play)** 逛逛。这是我们为致力于探索未来的构建者、研究人员和作家建立的开放社区。免费加入，无需商业计划书。 ## 许可证 MIT。详见 [`LICENSE`](LICENSE)。

标签：API文档, Substack, TypeScript, 安全插件, 接口逆向, 特征检测, 非官方API