| login | Authenticate with USCardForum credentials.
Args:
username: Your forum username
password: Your forum password
second_factor_token: 2FA code if you have 2FA enabled (optional)
IMPORTANT: Only use this if you need authenticated features like:
- Reading notifications
- Bookmarking posts
- Subscribing to topics
Most read operations work without authentication.
Returns a LoginResult with:
- success: Whether login succeeded
- username: Logged-in username
- error: Error message if failed
- requires_2fa: Whether 2FA is required
The session remains authenticated for subsequent calls.
Security note: Credentials are used only for this session
and are not persisted.
|
| get_current_session | Get information about the current session.
Returns a Session object with:
- is_authenticated: Whether logged in
- current_user: CurrentUser object with user info (if authenticated)
Use to verify authentication status.
|
| get_notifications | Fetch your notifications. REQUIRES AUTHENTICATION.
Args:
since_id: Only get notifications newer than this ID (optional)
only_unread: Only return unread notifications (default: False)
limit: Maximum number to return (optional)
Must call login() first.
Returns a list of Notification objects with:
- id: Notification ID
- notification_type: Type of notification
- read: Whether read
- topic_id: Related topic
- post_number: Related post
- created_at: When created
Use to:
- Check for new replies to your posts
- See mentions and likes
- Track topic updates you're watching
|
| bookmark_post | Bookmark a post for later reference. REQUIRES AUTHENTICATION.
Args:
post_id: The numeric post ID to bookmark
name: Optional label/name for the bookmark
reminder_type: Optional reminder setting
reminder_at: Optional reminder datetime (ISO format)
auto_delete_preference: When to auto-delete (default: 3)
- 0: Never
- 1: When reminder sent
- 2: On click
- 3: Clear after 3 days
Must call login() first.
Returns a Bookmark object with the created bookmark information.
Use to save interesting posts for later reference.
|
| subscribe_topic | Set your notification level for a topic. REQUIRES AUTHENTICATION.
Args:
topic_id: The topic ID to subscribe to
level: Notification level:
- 0: Muted (no notifications)
- 1: Normal (only if mentioned)
- 2: Tracking (notify on replies to your posts)
- 3: Watching (notify on all new posts)
Must call login() first.
Returns a SubscriptionResult with:
- success: Whether subscription succeeded
- notification_level: The new notification level
Use to:
- Watch topics for all updates (level=3)
- Mute noisy topics (level=0)
- Track topics you've contributed to (level=2)
|
| get_categories | Get a mapping of all forum categories.
Returns a CategoryMap object with category_id to category name mapping.
Categories organize topics by subject area.
Common USCardForum categories include sections for:
- Credit card applications and approvals
- Bank account bonuses
- Travel and redemptions
- Data points and experiences
Use category IDs to:
- Filter search results by category
- Understand which section a topic belongs to
- Navigate to specific areas of interest
The mapping includes both main categories and subcategories.
|
| search_forum | Search USCardForum for topics and posts matching a query.
Args:
query: Search query string. Supports Discourse operators:
- Basic: "chase sapphire bonus"
- In title only: "chase sapphire in:title"
- By author: "@username chase"
- In category: "category:credit-cards chase"
- With tag: "#amex bonus"
- Exact phrase: '"sign up bonus"'
- Exclude: "chase -sapphire"
- Time: "after:2024-01-01" or "before:2024-06-01"
page: Page number for pagination (starts at 1)
order: Sort order for results. Options:
- "relevance": Best match (default)
- "latest": Most recent first
- "views": Most viewed
- "likes": Most liked
- "activity": Recent activity
- "posts": Most replies
Returns a SearchResult object with:
- posts: List of matching SearchPost objects with excerpts
- topics: List of matching SearchTopic objects
- users: List of matching SearchUser objects
- grouped_search_result: Metadata about result counts
Example queries:
- "Chase Sapphire Reserve order:latest" - Recent CSR discussions
- "AMEX popup in:title" - Topics about AMEX popup in title
- "data point category:credit-cards" - Data points in CC category
- "@expert_user order:likes" - Most liked posts by a user
Pagination: If more results exist, increment page parameter.
|
| get_hot_topics | Fetch currently trending/hot topics from USCardForum.
This returns the most actively discussed topics right now, ranked by
engagement metrics like recent replies, views, and likes.
Use this to:
- See what the community is currently discussing
- Find breaking news or time-sensitive opportunities
- Discover popular ongoing discussions
Args:
page: Page number for pagination (0-indexed). Use page=1 to get more topics.
Returns a list of TopicSummary objects with fields:
- id: Topic ID (use with get_topic_posts)
- title: Topic title
- posts_count: Total replies
- views: View count
- like_count: Total likes
- created_at: Creation timestamp
- last_posted_at: Last activity timestamp
Example response interpretation:
A topic with high views but low posts may be informational.
A topic with many recent posts is actively being discussed.
|
| get_new_topics | Fetch the latest/newest topics from USCardForum.
Returns recently created topics sorted by creation time (newest first).
These may have fewer replies but contain fresh information.
Use this to:
- Find newly posted deals or offers
- See fresh questions from the community
- Discover emerging discussions before they get popular
Args:
page: Page number for pagination (0-indexed). Use page=1 to get more topics.
Returns a list of TopicSummary objects with:
- id: Topic ID
- title: Topic title
- posts_count: Number of posts
- created_at: When the topic was created
- category_id: Which forum section it's in
Tip: New topics with high view counts may indicate important news.
|
| get_top_topics | Fetch top-performing topics for a specific time period.
Args:
period: Time window for ranking. Must be one of:
- "daily": Top topics from today
- "weekly": Top topics this week
- "monthly": Top topics this month (default)
- "quarterly": Top topics this quarter
- "yearly": Top topics this year
page: Page number for pagination (0-indexed). Use page=1 to get more topics.
Use this to:
- Find the most valuable discussions in a time range
- Research historically important threads
- Identify evergreen popular content
Returns TopicSummary objects sorted by engagement score.
Example: Use "yearly" to find the most impactful discussions,
or "daily" to see what's trending today.
|
| get_topic_info | Get metadata about a specific topic without fetching all posts.
Args:
topic_id: The numeric topic ID (from URLs like /t/slug/12345)
Use this FIRST before reading a topic to:
- Check how many posts it contains (for pagination planning)
- Get the topic title and timestamps
- Decide whether to fetch all posts or paginate
Returns a TopicInfo object with:
- topic_id: The topic ID
- title: Full topic title
- post_count: Total number of posts
- highest_post_number: Last post number (may differ from count if posts deleted)
- last_posted_at: When the last reply was made
Strategy for large topics:
- <50 posts: Safe to fetch all at once
- 50-200 posts: Consider using max_posts parameter
- >200 posts: Fetch in batches or summarize key posts
|
| get_topic_posts | Fetch a batch of posts from a topic starting at a specific position.
Args:
topic_id: The numeric topic ID
post_number: Which post number to start from (default: 1 = first post)
include_raw: Include raw markdown source (default: False, returns HTML)
This fetches ~20 posts per call starting from post_number.
Use for paginated reading of topics.
Returns a list of Post objects with:
- post_number: Position in topic (1, 2, 3...)
- username: Author's username
- cooked: HTML content of the post
- raw: Markdown source (if include_raw=True)
- created_at: When posted
- updated_at: Last edit time
- like_count: Number of likes
- reply_count: Number of direct replies
- reply_to_post_number: Which post this replies to (if any)
Pagination example:
1. Call with post_number=1, get posts 1-20
2. Call with post_number=21, get posts 21-40
3. Continue until no posts returned
|
| get_all_topic_posts | Fetch all posts from a topic with automatic pagination.
Args:
topic_id: The numeric topic ID
include_raw: Include markdown source (default: False)
start_post_number: First post to fetch (default: 1)
end_post_number: Last post to fetch (optional, fetches to end if not set)
max_posts: Maximum number of posts to return (optional safety limit)
This automatically handles pagination to fetch multiple batches.
IMPORTANT: For topics with many posts (>100), use max_posts to limit
the response size. You can always fetch more with start_post_number.
Use cases:
- Fetch entire small topic: get_all_topic_posts(topic_id=123)
- Fetch first 50 posts: get_all_topic_posts(topic_id=123, max_posts=50)
- Fetch posts 51-100: get_all_topic_posts(topic_id=123, start_post_number=51, max_posts=50)
- Fetch specific range: get_all_topic_posts(topic_id=123, start=10, end=30)
Returns the same Post structure as get_topic_posts but for all matching posts.
Pro tip: Use get_topic_info first to check post_count before deciding
whether to fetch all or paginate manually.
|
| get_user_summary | Fetch a comprehensive summary of a user's profile.
Args:
username: The user's handle (case-insensitive)
Returns a UserSummary object with:
- user_id: User ID
- username: Username
- stats: UserStats with posts, topics, likes given/received, etc.
- badges: List of recent Badge objects
- top_topics: Most successful topics
- top_replies: Most successful replies
Use this to:
- Evaluate a user's credibility and experience
- Find their most valuable contributions
- Understand their participation level
The summary provides a quick overview without fetching
individual post histories.
|
| get_user_topics | Fetch topics created by a specific user.
Args:
username: The user's handle
page: Page number for pagination (optional)
Returns a list of topic objects with:
- id: Topic ID
- title: Topic title
- posts_count: Number of replies
- views: View count
- created_at: When created
- category_id: Forum category
Use this to:
- See what discussions a user has initiated
- Find expert users in specific areas
- Research a user's areas of interest
Paginate by incrementing the page parameter.
|
| get_user_replies | Fetch replies/posts made by a user in other topics.
Args:
username: The user's handle
offset: Pagination offset (0, 30, 60, ...)
Returns a list of UserAction objects with:
- topic_id: Which topic they replied to
- post_number: Their post number in that topic
- title: Topic title
- excerpt: Preview of their reply
- created_at: When they replied
Use this to:
- See a user's contributions across topics
- Find their data points and experiences
- Evaluate the quality of their participation
Paginate with offset in increments of 30.
|
| get_user_actions | Fetch a user's activity feed with optional filtering.
Args:
username: The user's handle
filter: Action type filter (optional). Common values:
- 1: Likes given
- 2: Likes received
- 4: Topics created
- 5: Replies posted
- 6: Posts (all)
- 7: Mentions
offset: Pagination offset (0, 30, 60, ...)
Returns a list of UserAction objects showing what the user has done.
Use this for detailed activity analysis beyond just replies.
For most cases, get_user_replies or get_user_topics are simpler.
|
| get_user_badges | Fetch badges earned by a user.
Args:
username: The user's handle
grouped: Group badges by type (default: True)
Returns a UserBadges object with:
- badges: List of Badge objects with name, description, granted_at
- badge_types: Badge type information
Badges indicate:
- Participation milestones (first post, anniversaries)
- Community recognition (editor, leader)
- Special achievements
Use to assess user experience and trustworthiness.
|
| get_user_following | Fetch the list of users that a user follows.
Args:
username: The user's handle
page: Page number for pagination (optional)
Returns a FollowList object with:
- users: List of FollowUser objects
- total_count: Total users being followed
Use to:
- Discover influential users in the community
- Find related experts
- Map social connections
|
| get_user_followers | Fetch the list of users following a specific user.
Args:
username: The user's handle
page: Page number for pagination (optional)
Returns a FollowList object with:
- users: List of FollowUser objects
- total_count: Total followers
A high follower count often indicates an influential
or helpful community member.
|
| get_user_reactions | Fetch a user's post reactions (likes, etc.).
Args:
username: The user's handle
offset: Pagination offset (optional)
Returns a UserReactions object with reaction data.
Use to see what content a user has reacted to,
which can indicate their interests and values.
|
| list_users_with_badge | List all users who have earned a specific badge.
Args:
badge_id: The numeric badge ID
offset: Pagination offset (optional)
Returns a dictionary with user badge information.
Use to find community members with specific achievements
or recognition levels.
|
