API

The FlowFerry API adds articles to your library programmatically. One POST request saves one article. It is the same endpoint the Raycast extension and the browser extension use.

Quick Start

Replace the key and run it:

curl -X POST https://flowferry.app/api/v1/articles -H "Authorization: Bearer ff_YOUR_KEY" -H "Content-Type: application/json" -d '{"title":"Hello","content":"# Hello\n\nThe article body.","url":"https://example.com/hello"}'

{ "ok": true }

That's the whole flow. The article appears in your library after the app's next sync.

Get an API Key

Go to flowferry.app/account, sign in, and click Generate API Key under API Key. The key starts with ff_ and is shown once, so store it when you create it.

A key can only add articles. It cannot read, change, or delete anything in your library. If it leaks, click Rotate on the same page and the old key stops working immediately.

Request

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

Field	Type	Required	Description
`title`	string	Yes	The article title.
`content`	string	Yes	The article body, as Markdown or HTML. Begin it with the title as an h1 (`# Title`) — the reader renders the body as-is and expects that heading.
`url`	string	Yes	Canonical URL of the article. Must parse as a URL.
`description`	string	No	Short excerpt shown in the library list.
`cover`	string	No	URL of a cover image.

Every request saves exactly one article. There is no batch form — send one request per article.

Responses

200 returns { "ok": true }. Errors return a JSON body with a human-readable message:

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

Status	Meaning
`400`	Body is not valid JSON, a required field is missing or empty, or `url` does not parse.
`401`	`Authorization` header missing or malformed, or the key is invalid.
`500`	Something failed on our side. Retry later.

A 400 will not succeed on retry — fix the body first. A 401 means the key itself is wrong; rotating or re-copying it is the fix, not retrying.

What This API Does Not Do

It does not fetch URLs. Passing a url alone saves nothing readable — you must supply content yourself. If you are saving a web page, fetch and extract it on your side first, then send the result. url is stored as the canonical link, not as an instruction to crawl.

It is write-only. There is no endpoint to list, search, update, or delete articles. Use the app for that.

About Your Data

Articles saved through the API pass through our server, the same way browser extension clips do. All content sent to our server is permanently deleted after 7 days, whether or not you have synced it to your library.

Last modified: Aug 15, 2026