# Toopost API Documentation for LLMs

## What is Toopost?

Toopost is a comprehensive content aggregation and publishing platform that brings together your favorite RSS feeds, articles, and posts in one unified interface. It's designed for content enthusiasts, developers, researchers, and professionals who want to stay informed, organize information efficiently, and share curated content.

### Core Features

- **Feed Aggregation:** Subscribe to unlimited RSS feeds from news outlets, blogs, podcasts, and custom sources
- **Article Curation:** Save, organize, and manage articles with tags, folders, and custom categorization
- **Content Publishing:** Create and publish your own articles and posts with full markdown support
- **Smart Recommendations:** Personalized content suggestions based on your reading habits and preferences
- **Read Later:** Build a reading queue with save-for-later and bookmark functionality
- **Social Features:** Like, share, and comment on content; follow other users and creators
- **Multi-Platform Sync:** Seamless synchronization across web, mobile, and desktop applications

## Platform Overview

### Web Application
The Toopost web application provides a full-featured interface for managing your feeds, articles, and account. Access it at:
```
https://go.toopost.us
```

**Features:**
- Rich feed reader with customizable layouts
- Advanced search and filtering
- Article editor with live preview
- Dashboard with statistics and analytics
- Account settings and preferences
- API integration management

### Mobile Application (iOS)
The Toopost iOS app delivers the full platform experience on your iPhone and iPad, optimized for mobile reading and on-the-go content discovery.

**Platforms:** iOS 14+

**Available on:** App Store

**Features:**
- Offline reading mode
- Push notifications for saved articles
- Dark mode support
- Gesture-based navigation
- One-handed reading interface
- iCloud sync across devices

### MCP (Model Context Protocol) Server

Toopost is available as an MCP server for AI assistants and LLMs, enabling seamless integration with tools like Claude, ChatGPT, and other AI platforms.

**MCP Features:**
- Access your feeds and content through AI assistants
- Get AI-powered summaries of your articles
- Use AI to tag, categorize, and organize content
- Ask your AI assistant to search through your saved articles
- Generate insights from your reading patterns
- Automate content discovery with AI

**Use Cases:**
- Research assistant: Ask AI to summarize your feeds and articles
- Content discovery: Let AI find the most relevant content for your interests
- Writing assistant: Use AI to help draft and edit your articles
- Knowledge management: Build a searchable knowledge base with AI
- Automation: Create workflows to auto-tag and organize content

**Getting Started with MCP:**
The Toopost MCP server can be configured in your Claude desktop app or other MCP-compatible clients. Premium subscriptions include MCP access.

## Overview

The Toopost API provides programmatic access to user posts, feeds, articles, and account information. All endpoints require authentication via API token.

## Authentication

All API requests require authentication using your API token. Include your token in requests using one of these methods:

### Authorization Header (Recommended)
```
Authorization: Bearer YOUR_API_TOKEN
```

#### Example:
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://go.toopost.us/api/user/info
```

### Query Parameter
```
?token=YOUR_API_TOKEN
```

#### Example:
```bash
curl "https://go.toopost.us/api/user/info?token=YOUR_API_TOKEN"
```

## Base URL
```
https://go.toopost.us/api/user
```

## API Endpoints

### User Posts

#### GET /api/user/posts
Get all user posts.

**Requirements:** Premium or MCP access required

**Response:** List of user posts

**Example:**
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://go.toopost.us/api/user/posts
```

**Response Body:**
```json
{
  "success": true,
  "data": [
    {
      "id": "post-123",
      "title": "My First Post",
      "content": "This is the post content...",
      "createdAt": "2026-03-01T10:30:00Z",
      "updatedAt": "2026-03-01T10:30:00Z",
      "views": 245,
      "likes": 42,
      "shares": 8,
      "tags": ["tech", "api"],
      "status": "published"
    },
    {
      "id": "post-124",
      "title": "Second Post",
      "content": "More content here...",
      "createdAt": "2026-02-28T14:15:00Z",
      "updatedAt": "2026-02-28T14:15:00Z",
      "views": 189,
      "likes": 31,
      "shares": 5,
      "tags": ["tutorial"],
      "status": "published"
    }
  ],
  "pagination": {
    "total": 125,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}
```

---

#### GET /api/user/posts/{id}
Get a specific post by ID.

**Parameters:**
- `id` (string, required) - Post ID

**Requirements:** Premium or MCP access required

**Response:** Post details

**Example:**
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://go.toopost.us/api/user/posts/post-123
```

**Response Body:**
```json
{
  "success": true,
  "data": {
    "id": "post-123",
    "title": "My First Post",
    "content": "This is the detailed post content with full markdown support...",
    "htmlContent": "<p>This is the detailed post content...</p>",
    "createdAt": "2026-03-01T10:30:00Z",
    "updatedAt": "2026-03-01T10:30:00Z",
    "authorId": "user-456",
    "views": 245,
    "likes": 42,
    "shares": 8,
    "comments": 12,
    "tags": ["tech", "api"],
    "status": "published",
    "language": "en",
    "readTime": 5,
    "featured": false
  }
}
```

---

### User Feeds

#### GET /api/user/feeds
Get all user subscribed feeds.

**Response:** List of user feeds with metadata

**Example:**
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://go.toopost.us/api/user/feeds
```

**Response Body:**
```json
{
  "success": true,
  "data": [
    {
      "id": "feed-001",
      "title": "TechCrunch",
      "url": "https://techcrunch.com/feed/",
      "description": "Technology news and analysis",
      "category": "Technology",
      "lastUpdated": "2026-03-03T08:45:00Z",
      "itemCount": 2847,
      "unreadCount": 23,
      "language": "en",
      "subscriptionsCount": 12500
    },
    {
      "id": "feed-002",
      "title": "Hacker News",
      "url": "https://news.ycombinator.com/rss",
      "description": "The latest and greatest news in technology and startups",
      "category": "Startups",
      "lastUpdated": "2026-03-03T09:12:00Z",
      "itemCount": 1523,
      "unreadCount": 45,
      "language": "en",
      "subscriptionsCount": 8900
    }
  ],
  "pagination": {
    "total": 87,
    "page": 1,
    "limit": 50
  }
}
```

---

### Saved and Liked Posts

#### GET /api/user/saved-posts
Get all saved posts.

**Response:** List of saved posts

**Example:**
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://go.toopost.us/api/user/saved-posts
```

**Response Body:**
```json
{
  "success": true,
  "data": [
    {
      "id": "saved-001",
      "postId": "post-456",
      "title": "Understanding REST APIs",
      "source": "TechCrunch",
      "author": "John Doe",
      "url": "https://example.com/article/rest-apis",
      "savedAt": "2026-03-02T15:20:00Z",
      "readingStatus": "unread",
      "folder": "Learning",
      "summary": "A comprehensive guide to building REST APIs..."
    }
  ],
  "pagination": {
    "total": 342,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}
```

---

#### GET /api/user/liked-posts
Get all liked posts.

**Response:** List of liked posts

**Example:**
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://go.toopost.us/api/user/liked-posts
```

**Response Body:**
```json
{
  "success": true,
  "data": [
    {
      "id": "liked-001",
      "postId": "post-789",
      "title": "Best JavaScript Tips",
      "author": "Jane Smith",
      "source": "Dev.to",
      "likedAt": "2026-03-01T12:30:00Z",
      "content": "10 amazing JavaScript tips you didn't know...",
      "likes": 1250,
      "comments": 89
    }
  ],
  "pagination": {
    "total": 156,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}
```

---

### Articles

#### GET /api/user/articles/{id}
Get complete article information by ID.

**Parameters:**
- `id` (string, required) - Article ID

**Response:** Complete article details including content, metadata, and version history

**Example:**
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://go.toopost.us/api/user/articles/article-456
```

**Response Body:**
```json
{
  "success": true,
  "data": {
    "id": "article-456",
    "title": "API Integration Guide",
    "slug": "api-integration-guide",
    "content": "# API Integration Guide\n\nThis guide covers...",
    "description": "A comprehensive guide to integrating third-party APIs",
    "author": {
      "id": "user-123",
      "name": "Andrew Brown",
      "avatar": "https://example.com/avatar.jpg"
    },
    "createdAt": "2026-02-15T10:00:00Z",
    "updatedAt": "2026-03-01T14:20:00Z",
    "publishedAt": "2026-02-15T11:30:00Z",
    "status": "published",
    "visibility": "public",
    "tags": ["api", "integration", "guide"],
    "category": "Technical",
    "readTime": 12,
    "views": 3420,
    "likes": 287,
    "comments": 45,
    "versions": [
      {
        "version": 3,
        "createdAt": "2026-03-01T14:20:00Z",
        "changes": "Added examples section"
      },
      {
        "version": 2,
        "createdAt": "2026-02-28T09:15:00Z",
        "changes": "Fixed typos and formatting"
      },
      {
        "version": 1,
        "createdAt": "2026-02-15T10:00:00Z",
        "changes": "Initial version"
      }
    ]
  }
}
```

---

#### POST /api/user/articles
Create a new article.

**Request Body:**
```json
{
  "title": "Article Title",
  "content": "Article content in markdown or HTML",
  "tags": ["tag1", "tag2"],
  "description": "Brief description",
  "category": "Tech",
  "visibility": "public"
}
```

**Response:** Created article with ID

**Example:**
```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Article",
    "content": "Article body here",
    "tags": ["tech", "api"]
  }' \
  https://go.toopost.us/api/user/articles
```

**Response Body:**
```json
{
  "success": true,
  "data": {
    "id": "article-999",
    "title": "My Article",
    "slug": "my-article",
    "content": "Article body here",
    "description": "",
    "status": "draft",
    "visibility": "draft",
    "tags": ["tech", "api"],
    "createdAt": "2026-03-03T10:30:00Z",
    "updatedAt": "2026-03-03T10:30:00Z",
    "version": 1
  }
}
```

---

#### POST /api/user/articles/{articleId}/versions
Create a new version of an existing article.

**Parameters:**
- `articleId` (string, required) - Article ID

**Request Body:**
```json
{
  "content": "Updated article content",
  "title": "Updated Title (optional)",
  "tags": ["tag1", "tag2"],
  "changes": "Brief description of changes"
}
```

**Response:** New version details with version number

**Example:**
```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated content here",
    "changes": "Added new examples"
  }' \
  https://go.toopost.us/api/user/articles/article-456/versions
```

**Response Body:**
```json
{
  "success": true,
  "data": {
    "id": "article-456",
    "title": "API Integration Guide",
    "version": 4,
    "content": "Updated content here",
    "changes": "Added new examples",
    "createdAt": "2026-03-03T11:45:00Z",
    "previousVersion": 3,
    "status": "published"
  }
}
```

---

### User Account

#### GET /api/user/info
Get current user account information.

**Response:** User profile details including username, email, subscription tier, and account settings

**Example:**
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://go.toopost.us/api/user/info
```

**Response Body:**
```json
{
  "success": true,
  "data": {
    "id": "user-123",
    "username": "andrew_brown",
    "email": "andrew@example.com",
    "displayName": "Andrew Brown",
    "avatar": "https://example.com/avatars/123.jpg",
    "bio": "Developer and content creator",
    "subscription": {
      "tier": "premium",
      "status": "active",
      "startDate": "2025-12-15T00:00:00Z",
      "renewalDate": "2026-12-15T00:00:00Z",
      "features": ["mcp-access", "unlimited-articles", "api-access", "priority-support"]
    },
    "followers": 2450,
    "following": 890,
    "joinedAt": "2024-01-10T00:00:00Z",
    "timezone": "UTC",
    "language": "en"
  }
}
```

---

#### GET /api/user/stats
Get user account statistics.

**Response:** User statistics including post count, feed subscriptions, saved articles, and engagement metrics

**Example:**
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://go.toopost.us/api/user/stats
```

**Response Body:**
```json
{
  "success": true,
  "data": {
    "totalPosts": 125,
    "totalArticles": 42,
    "totalSavedPosts": 342,
    "totalLikedPosts": 156,
    "totalFeeds": 87,
    "engagement": {
      "totalViews": 45230,
      "totalLikes": 3420,
      "totalShares": 1240,
      "totalComments": 2890
    },
    "readingStats": {
      "articlesRead": 234,
      "averageReadTime": 8.5,
      "totalReadTime": 1995,
      "lastArticleRead": "2026-03-03T08:20:00Z"
    },
    "accountStats": {
      "createdAt": "2024-01-10T00:00:00Z",
      "lastLoginAt": "2026-03-03T10:15:00Z",
      "loginStreak": 23
    },
    "quotaUsage": {
      "apiCallsThisMonth": 4250,
      "apiCallsLimit": 10000,
      "storageUsedMB": 245,
      "storageLimit": 1000
    }
  }
}
```

---

## Rate Limiting

API requests are rate-limited per token. Current limits:
- Standard users: 100 requests per minute
- Premium users: 1000 requests per minute

## Error Handling

All error responses use standard HTTP status codes:
- `400` - Bad Request (invalid parameters)
- `401` - Unauthorized (invalid or missing token)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found (resource doesn't exist)
- `429` - Too Many Requests (rate limit exceeded)
- `500` - Server Error

Error responses include a JSON body with error details:
```json
{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}
```

## Getting Your API Token

1. Log in to your Toopost account
2. Navigate to Settings → API & Integrations
3. Click "Generate API Token"
4. Copy your token and store it securely
5. Never share your API token in public repositories or untrusted environments

## Best Practices

1. **Security:** Always use HTTPS and transmit tokens securely
2. **Authorization Header:** Prefer the Authorization header over query parameters for sensitive operations
3. **Rate Limiting:** Implement exponential backoff for retries
4. **Caching:** Cache responses when appropriate to reduce API calls
5. **Monitoring:** Track your API usage in the dashboard to detect unusual activity
6. **Token Rotation:** Rotate your API tokens regularly
7. **Error Handling:** Always handle error responses appropriately

## Support

For API issues and support, visit: https://go.toopost.us/help/api