API Documentation - Twitter RSS API

Overview

Twitter RSS API is a service for monitoring Twitter/X accounts using Nitter RSS feeds. It supports multi-account monitoring, automatic collection, Discord notifications, and a web management interface.

Base URL

https://rss.test.luckyscan.app/api

Response Format

All API responses follow a unified JSON format:

// Success Response
{
  "success": true,
  "data": { ... } // or [ ... ]
}

// Error Response
{
  "success": false,
  "error": "Error message here"
}

Health Check

GET /health

Check service status and Nitter instance health.

Response:

{
  "success": true,
  "data": {
    "status": "ok",
    "uptime": 3600,
    "version": "1.0.0",
    "database": "ok",
    "timestamp": "2026-02-18T04:00:00.000Z",
    "nitterInstances": 5,
    "instanceHealth": { ... }
  }
}

Monitors Management

Manage Twitter accounts to monitor.

GET /monitors

Get all monitored accounts.

POST /monitors

Add a new monitor.

Request Body:

{
  "username": "vitalikbuterin",
  "displayName": "Vitalik Buterin",
  "nitterInstance": "https://nitter.privacyredirect.com",
  "discordChannels": ["123456789"]
}

PATCH /monitors/:id

Update a monitor configuration.

DELETE /monitors/:id

Delete a monitor and its tweets.

Tweets Query

Query collected tweets with filtering and pagination.

GET /tweets

Get tweets with pagination and filtering.

Query Parameters:

Parameter	Type	Description
`limit`	Number	Items per page (default: 20)
`offset`	Number	Pagination offset (default: 0)
`username`	String	Filter by username
`search`	String	Full-text search

GET /tweets/stats

Get tweet statistics.

Collection & Notifications

POST /collect

Trigger a collection task.

POST /notify

Send pending tweets to Discord.

Tools

POST /seed

Import sample data for demonstration.

POST /test-instance

Test Nitter instance connectivity.

GET /logs

Get collection logs.

Code Examples

Using cURL

# Get all monitors
curl https://rss.test.luckyscan.app/api/monitors

# Add a new monitor
curl -X POST https://rss.test.luckyscan.app/api/monitors \
  -H "Content-Type: application/json" \
  -d '{"username":"vitalikbuterin"}'

# Query tweets
curl "https://rss.test.luckyscan.app/api/tweets?limit=10"

Using JavaScript

// Get monitors
fetch('https://rss.test.luckyscan.app/api/monitors')
  .then(r => r.json())
  .then(data => console.log(data));

// Add monitor
fetch('https://rss.test.luckyscan.app/api/monitors', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({username: 'vitalikbuterin'})
})
  .then(r => r.json())
  .then(data => console.log(data));

Using Python

import requests

# Get monitors
r = requests.get('https://rss.test.luckyscan.app/api/monitors')
print(r.json())

# Add monitor
data = {'username': 'vitalikbuterin'}
r = requests.post('https://rss.test.luckyscan.app/api/monitors', json=data)
print(r.json())

Error Handling

API errors return appropriate HTTP status codes:

Status Code	Description
200	Request successful
201	Resource created
400	Invalid request parameters
404	Resource not found
500	Server error

About Nitter Instances

Due to Twitter/X API restrictions, Nitter public instances have varying availability. Current status:

Instance	Status	Notes
nitter.privacyredirect.com	Unstable	Occasionally blocked by Cloudflare
nitter.poast.org	PoW Challenge	Requires proof-of-work verification
xcancel.com	Whitelist	RSS requires whitelist approval
nitter.net	Unavailable	Often returns 403
nitter.catsarch.com	Unavailable	Connection timeout

For best stability, consider deploying your own Nitter instance.

Twitter RSS API Documentation