← Back to Help

API v1 User Guide

RSSFlux provides a REST API for programmatic access to feeds, link drops, and fluxions. You can create, list, and delete resources from any headless server, AI agent, or automation script.

---

Quick Start

1. Create an account at [rssflux.io](https://rssflux.io)

2. Generate an API key — go to Settings → API Keys, type a name, click Generate

3. Copy the key (shown once — rss_a1b2c3...)

4. Make your first API call:

`bash

curl -H "Authorization: Bearer rss_YOUR_KEY" https://rssflux.io/api/v1/feeds

`

That's it. The API is ready to use from any application.

---

Authentication

Every request requires an API key. There are two ways to send it:

Method 1: Authorization Header (recommended)

`http

Authorization: Bearer rss_YOUR_API_KEY

`

Method 2: Query Parameter (browser-friendly)

`

https://rssflux.io/api/v1/feeds?key=rss_YOUR_API_KEY

`

This is useful for quick tests in a browser or simple scripts where setting headers is inconvenient.

Unauthenticated Response

Without a valid key you get:

`json

HTTP 401

{

"detail": "Missing API key. Use Authorization: Bearer or ?key="

}

`

---

Base URL

All endpoints are under:

`

https://rssflux.io/api/v1

`

---

Endpoint Overview

| Method | Endpoint | Description |

|--------|----------|-------------|

| POST | /feeds | Create a new RSS feed |

| GET | /feeds | List all your feeds |

| GET | /feeds/{id} | Get a single feed |

| DELETE | /feeds/{id} | Delete a feed |

| GET | /feeds/{id}/items | Get feed items |

| POST | /linkdrop | Save a URL to Link Drop |

| POST | /fluxions | Create a fluxion |

| GET | /fluxions | List all fluxions |

| DELETE | /fluxions/{id} | Delete a fluxion |

| SEARCH | | |

| GET | /v1/search | Search feed items (full-text across all feeds) |

---

Feeds

Create a Feed

Turns a web page or RSS URL into a monitored feed. RSSFlux scrapes the URL automatically and populates the feed with items.

`

POST /feeds

`

Request Body:

`json

{

"url": "https://feeds.feedburner.com/TechCrunch",

"title": "TechCrunch",

"description": "Latest tech news"

}

`

| Field | Type | Required | Description |

|-------|------|----------|-------------|

| url | string | yes | The web page or RSS URL to monitor |

| title | string | yes | A name for the feed |

| description | string | no | Optional description |

Success Response (201):

`json

{

"id": 1,

"url": "https://feeds.feedburner.com/TechCrunch",

"title": "TechCrunch",

"description": "Latest tech news",

"is_active": true,

"feed_token": "abc123def456",

"item_count": 0

}

`

The feed is created and queued for its first scrape. Items will populate on the next refresh cycle (typically within 5 minutes).

Error Responses:

`json

HTTP 409

{

"detail": "Feed with this URL already exists"

}

`

`json

HTTP 402

{

"detail": "Feed limit reached for your plan. Upgrade to add more feeds."

}

`

---

List All Feeds

Returns all feeds for your account, ordered by newest first.

`

GET /feeds?limit=50

`

| Param | Type | Default | Max | Description |

|-------|------|---------|-----|-------------|

| limit | integer | 50 | 500 | Number of feeds to return |

Success Response (200):

`json

[

{

"id": 1,

"url": "https://feeds.feedburner.com/TechCrunch",

"title": "TechCrunch",

"description": "Latest tech news",

"is_active": true,

"last_scraped": "2026-05-28 20:12:36+00:00",

"feed_token": "abc123def456",

"item_count": 10

}

]

`

---

Get a Single Feed

Returns details for a specific feed.

`

GET /feeds/{id}

`

Success Response (200):

`json

{

"id": 1,

"url": "https://feeds.feedburner.com/TechCrunch",

"title": "TechCrunch",

"description": null,

"is_active": true,

"last_scraped": "2026-05-28 20:12:36+00:00",

"feed_token": "abc123def456",

"item_count": 10

}

`

Error Response:

`json

HTTP 404

{

"detail": "Feed not found"

}

`

---

Delete a Feed

Permanently removes a feed and all its items.

`

DELETE /feeds/{id}

`

Success Response (200):

`json

{

"ok": true

}

`

---

Get Feed Items

Returns the latest items from a feed, ordered by publish date descending.

`

GET /feeds/{id}/items?limit=50

`

| Param | Type | Default | Max | Description |

|-------|------|---------|-----|-------------|

| limit | integer | 50 | 500 | Number of items to return |

Success Response (200):

`json

[

{

"id": 1,

"title": "AI Startup Raises $500M in Series C",

"link": "https://techcrunch.com/2026/05/28/ai-startup",

"pub_date": "2026-05-28 14:30:00+00:00",

"description": "The company plans to use the funding to expand its AI platform...",

"thumbnail": "https://example.com/image.jpg"

}

]

`

If the feed has no items yet (awaiting first scrape):

`json

HTTP 200

[]

`

---

Link Drop

Save a URL to Link Drop

Saves any URL to your Link Drop list. URLs are scraped for metadata (title, description, thumbnail) automatically.

`

POST /linkdrop

`

Request Body:

`json

{

"url": "https://example.com/article",

"title": "Optional title override",

"description": "Optional description",

"list": "LD"

}

`

| Field | Type | Required | Default | Description |

|-------|------|----------|---------|-------------|

| url | string | yes | — | The URL to save |

| title | string | no | auto-detected | Override the scraped title |

| description | string | no | auto-detected | Override the scraped description |

| list | string | no | "LD" | 2-letter list code (LD, MS, RV, etc.) |

Success Response (200):

`json

{

"status": "saved",

"url": "https://example.com/article",

"title": "Article Title",

"list_code": "LD",

"feed_token": "xyz789"

}

`

Already Saved Response:

`json

{

"status": "exists",

"url": "https://example.com/article",

"title": "Article Title",

"list_code": "LD",

"feed_token": "xyz789"

}

`

Error Response:

`json

HTTP 400

{

"detail": "Invalid URL"

}

`

---

Fluxions

A fluxion combines multiple feeds into a single RSS feed. It's useful for creating curated collections from different sources.

Create a Fluxion

`

POST /fluxions

`

Request Body:

`json

{

"title": "Morning Scan",

"description": "Daily tech briefing",

"feed_ids": [1, 2, 3]

}

`

| Field | Type | Required | Description |

|-------|------|----------|-------------|

| title | string | yes | A name for the fluxion |

| description | string | no | Optional description |

| feed_ids | array | yes | Array of feed IDs from GET /feeds |

Success Response (201):

`json

{

"id": 1,

"title": "Morning Scan",

"description": "Daily tech briefing",

"feed_token": "def456ghi789",

"source_count": 3,

"sources": [

{

"id": 1,

"feed_id": 1,

"feed_title": "TechCrunch",

"feed_url": "https://feeds.feedburner.com/TechCrunch"

},

{

"id": 2,

"feed_id": 2,

"feed_title": "Ars Technica",

"feed_url": "https://feeds.feedburner.com/ArsTechnica"

}

]

}

`

The feed_token can be used to access the combined RSS feed:

`

https://rssflux.io/api/rss/def456ghi789.xml

`

---

List All Fluxions

`

GET /fluxions?limit=50

`

| Param | Type | Default | Max | Description |

|-------|------|---------|-----|-------------|

| limit | integer | 50 | 500 | Number of fluxions to return |

Success Response (200):

`json

[

{

"id": 1,

"title": "Morning Scan",

"description": null,

"feed_token": "def456ghi789",

"source_count": 3,

"sources": [...]

}

]

`

---

Delete a Fluxion

`

DELETE /fluxions/{id}

`

Success Response (200):

`json

{

"ok": true

}

`

Error Response:

`json

HTTP 404

{

"detail": "Fluxion not found"

}

`

---

Rate Limiting

API keys are limited to 60 requests per minute per key. Rate limit information is included in response headers:

| Header | Description |

|--------|-------------|

| X-RateLimit-Limit | Max requests per minute (60) |

| X-RateLimit-Remaining | Requests remaining in current window |

| X-RateLimit-Reset | Unix timestamp when the window resets |

Rate Limited Response (429):

`json

HTTP 429

{

"detail": "Rate limit exceeded. Try again in X seconds."

}

`

---

Error Responses

| Status | Meaning | Typical Cause |

|--------|---------|---------------|

| 400 | Bad request | Missing required field or invalid value |

| 401 | Unauthorized | Missing, invalid, or revoked API key |

| 404 | Not found | Feed or fluxion ID doesn't exist |

| 409 | Conflict | Duplicate feed URL for your account |

| 402 | Payment required | Tier limit reached (max feeds/items for plan) |

| 429 | Too many requests | Rate limit exceeded |

---

Code Examples

Python

`python

import httpx

key = "rss_YOUR_KEY"

headers = {"Authorization": f"Bearer {key}"}

List feeds

r = httpx.get("https://rssflux.io/api/v1/feeds", headers=headers)

print(r.json())

Create a feed

r = httpx.post(

"https://rssflux.io/api/v1/feeds",

headers=headers,

json={"url": "https://example.com/rss", "title": "My Feed"},

)

print(r.json())

`

JavaScript (fetch)

`javascript

const key = "rss_YOUR_KEY";

const headers = { Authorization: Bearer ${key} };

// List feeds

const feeds = await fetch("https://rssflux.io/api/v1/feeds", { headers }).then(r => r.json());

// Create a feed

const feed = await fetch("https://rssflux.io/api/v1/feeds", {

method: "POST",

headers: { ...headers, "Content-Type": "application/json" },

body: JSON.stringify({ url: "https://example.com/rss", title: "My Feed" }),

}).then(r => r.json());

`

curl

`bash

Create a feed

curl -X POST https://rssflux.io/api/v1/feeds \

-H "Authorization: Bearer rss_YOUR_KEY" \

-H "Content-Type: application/json" \

-d '{"url": "https://feeds.feedburner.com/TechCrunch", "title": "TechCrunch"}'

List all feeds

curl -H "Authorization: Bearer rss_YOUR_KEY" \

https://rssflux.io/api/v1/feeds

Get feed items

curl -H "Authorization: Bearer rss_YOUR_KEY" \

"https://rssflux.io/api/v1/feeds/1/items?limit=10"

Save a link to Link Drop

curl -X POST https://rssflux.io/api/v1/linkdrop \

-H "Authorization: Bearer rss_YOUR_KEY" \

-H "Content-Type: application/json" \

-d '{"url": "https://example.com/article"}'

Create a fluxion

curl -X POST https://rssflux.io/api/v1/fluxions \

-H "Authorization: Bearer rss_YOUR_KEY" \

-H "Content-Type: application/json" \

-d '{"title": "Daily Reads", "feed_ids": [1, 2, 3]}'

Delete a feed

curl -X DELETE https://rssflux.io/api/v1/feeds/1 \

-H "Authorization: Bearer rss_YOUR_KEY"

Browser-friendly: list feeds

curl "https://rssflux.io/api/v1/feeds?key=rss_YOUR_KEY"

Search feed items

curl "https://rssflux.io/api/v1/search?q=archaix" \

-H "Authorization: Bearer rss_YOUR_KEY"

`

---

Search

Search across all your feed items using PostgreSQL full-text search. Supports stemming ("running" matches "run") and ranks results by relevance.

| Item | Detail |

|------|--------|

| Method | GET |

| Endpoint | https://rssflux.io/api/v1/search |

| Auth | API key (Bearer token or ?key= query param) |

Query Parameters

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| q | string | Yes | — | Search query (min 2 characters) |

| limit | integer | No | 20 | Max results (1–50) |

Response

`json

{

"query": "archaix",

"results": [

{

"feed_id": 2,

"feed_title": "Archaix",

"item_id": 1517,

"title": "Archaix Mystery Machine Is On It!",

"link": "https://www.youtube.com/watch?v=beWtC8f9l5I",

"description": "...",

"pub_date": "2026-05-28"

}

],

"total": 11

}

`

Errors

| Status | Meaning |

|--------|---------|

| 422 | Query q is missing or less than 2 characters |

| 401 | Missing or invalid API key |

---

Glossary

| Term | Description |

|------|-------------|

| feed_token | A unique token identifying a feed or fluxion. Used in RSS URLs: /api/rss/{token}.xml |

| feed_ids | Numeric IDs of feeds, obtained from GET /feeds. Used when creating fluxions |

| list_code | A 2-letter code identifying a Link Drop list (e.g. LD, MS, RV) |

| Fluxion | A combined feed that aggregates items from multiple source feeds |

| Link Drop | A bookmarklet-based URL saving system. Each list has its own RSS feed |

| last_scraped | Timestamp of the last successful feed refresh. null means the feed hasn't been scraped yet |

| item_count | Number of items currently stored for a feed. Helps understand feed freshness |

---

Support

  • Documentation: Visit /help on the dashboard for guides on all features
  • API Issues: Generate a new key from Settings → API Keys if your key is compromised
  • Account Issues: Check your plan limits at Settings → Pricing & Billing