FlowFerry API

The FlowFerry API lets you add articles to your library programmatically. It powers the official Raycast extension, and you can use it from your own scripts and tools.

Authentication

Every request is authenticated with a personal API key, sent as a bearer token:

Authorization: Bearer ff_your_api_key

To get a key, go to flowferry.app/account and click Generate API Key under the API Key section. The key is shown only once — store it somewhere safe.

An API key can only add articles to your library. It cannot read, modify, or delete anything. If a key leaks, rotate it from the same page — the old key stops working immediately.

Save an Article

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

Request body

Field	Type	Required	Description
`title`	string	Yes	The article title.
`content`	string	Yes	The article body, as HTML or Markdown. Start it with the title as an h1 heading (e.g. `# Title`) — the FlowFerry reader renders the body as-is and expects the heading.
`url`	string	Yes	The canonical URL of the article. Must be a valid URL.
`description`	string	No	A short excerpt shown in the library list.
`cover`	string	No	URL of a cover image.

Example

curl -X POST https://flowferry.app/api/v1/articles \
  -H "Authorization: Bearer ff_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "An Interesting Article",
    "content": "# An Interesting Article\n\n<p>The article body…</p>",
    "url": "https://example.com/article",
    "description": "A short excerpt.",
    "cover": "https://example.com/cover.jpg"
  }'

A successful request returns:

{ "ok": true }

The article appears in your FlowFerry app after the next sync.

Errors

Status	Meaning
`400`	The body is not valid JSON, a required field is missing, or `url` is not a valid URL.
`401`	The `Authorization` header is missing, malformed, or the API key is invalid.
`500`	Something went wrong on our side. Try again later.

Error responses carry a JSON body with a human-readable message:

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

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, even if you haven't synced it to your library.

Dernière modification: 10 juin 2026