# ReadingList.live

> ReadingList.live turns articles you want to read into a private podcast feed. Save a URL, and our workers fetch the article, strip distractions, and convert it to audio for listening on your podcast player.

## Getting Started

- [Sign in](https://readinglist.live/sign_in)
- [View your profile](https://readinglist.live/u/[your-username]/profile)
- [Access your RSS feed](https://readinglist.live/u/[your-username]/rss)

## API Documentation

- [Simple API](#simple-api): Save articles with Bearer token authentication
- [MCP Server](#mcp-server): OAuth 2.0 endpoints for AI assistants and automation
- [OAuth Scopes](#oauth-scopes): Permission levels for API access

## Simple API

Save an article by sending a POST request to `/api/to_read`:

```
POST https://readinglist.live/api/to_read
Authorization: Bearer <your-token>
Content-Type: text/plain

https://example.com/article
```

Get your API token from your profile page at `https://readinglist.live/u/[your-username]/profile`

## MCP Server

ReadingList.live provides MCP (Model Context Protocol) endpoints for programmatic feed management.

### Authentication

Create an OAuth client on your profile page and obtain an access token:

```
POST https://readinglist.live/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client-id>&client_secret=<client-secret>&scope=feed:read feed:write feed:search
```

### Endpoints

**Get Feed Info** - Returns feed metadata
```
GET https://readinglist.live/api/mcp/v1/feed?action=get_feed_info&feedId=<feed-id>
Authorization: Bearer <access-token>
```

**Add URL** - Add article to reading list (idempotent)
```
POST https://readinglist.live/api/mcp/v1/feed
Authorization: Bearer <access-token>
Content-Type: application/json

{"action": "add_url", "userId": <user-id>, "url": "https://example.com/article"}
```

**Search Feed** - Search articles with pagination
```
POST https://readinglist.live/api/mcp/v1/feed
Authorization: Bearer <access-token>
Content-Type: application/json

{"action": "search_feed", "userId": <user-id>, "query": "search terms", "limit": 20}
```

### OAuth Scopes

- `feed:read` - Read feed metadata and items
- `feed:write` - Add URLs to reading list
- `feed:search` - Search feed items
- `profile:read` - Read user profile information

## Documentation

- [Full Documentation](https://readinglist.live/llms-full.txt) - Complete API reference

## Optional

### Key Features

- Save articles via web, mobile app, or bookmarklet
- Auto-generate readable versions by stripping ads and navigation
- Convert articles to speech using Amazon Polly
- Organize with auto-generated tags
- Weekly episode summaries with LLM-generated descriptions
- Private RSS feed for podcast players
- Full-text search across saved articles

### Privacy

User-agent: *
Disallow: /

This site's content is not available for AI training. Articles saved by users are private and not publicly accessible.