API

FlowFerry API 用于以编程方式向你的文章库添加文章。一次 POST 请求保存一篇文章。Raycast 扩展和浏览器插件用的也是这个接口。

快速开始

替换成你的密钥，直接运行：

curl -X POST https://flowferry.app/api/v1/articles -H "Authorization: Bearer ff_YOUR_KEY" -H "Content-Type: application/json" -d '{"title":"你好","content":"# 你好\n\n正文内容。","url":"https://example.com/hello"}'

{ "ok": true }

整个流程就是这样。文章会在 App 下一次同步后出现在你的文章库中。

获取 API 密钥

打开 flowferry.app/account 登录，在 API 密钥一栏点击生成 API 密钥。密钥以 ff_ 开头，且只会显示一次，请在生成时妥善保存。

密钥只能添加文章，无法读取、修改或删除文章库中的任何内容。如果密钥泄露，在同一页面点击轮换即可，旧密钥会立即失效。

请求

POST https://flowferry.app/api/v1/articles
Authorization: Bearer ff_YOUR_KEY
Content-Type: application/json

字段	类型	必填	说明
`title`	string	是	文章标题。
`content`	string	是	文章正文，Markdown 或 HTML 均可。开头请写成一级标题（`# 标题`）：阅读器会原样渲染正文，并预期这个标题存在。
`url`	string	是	文章的原始链接，必须是合法的 URL。
`description`	string	否	简短摘要，显示在文章库列表中。
`cover`	string	否	封面图片的链接。

每次请求保存一篇文章。接口不支持批量提交，多篇文章请分多次请求。

响应

成功返回 200 和 { "ok": true }。出错时返回带可读信息的 JSON：

{ "error": "Invalid API key." }

状态码	含义
`400`	请求体不是合法 JSON、缺少必填字段，或 `url` 无法解析。
`401`	缺少或格式错误的 `Authorization` 头，或密钥无效。
`500`	我们这边出了问题，请稍后重试。

400 重试也不会成功，需要先修正请求体。401 说明密钥本身有问题，应重新复制或轮换密钥，而不是重试。

这个 API 不做什么

它不会抓取网页。 只传 url 不会保存出可阅读的内容，content 必须由你提供。如果你要保存的是一个网页，请先自行抓取并提取正文，再把结果发过来。url 只作为文章的原始链接保存，不会触发抓取。

它只写不读。 没有用于列出、搜索、修改或删除文章的接口，这些操作请在 App 内完成。

关于你的数据

通过 API 保存的文章会经过我们的服务器，和浏览器插件的剪藏一样。所有发送到服务器的内容都会在 7 天后被永久删除，无论你是否已经同步到文章库。

最后修改: 2026年8月15日