Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MatthewSabia1/SubPirate-Pro/llms.txt

Use this file to discover all available pages before exploring further.

​
GET /api/analyze/:subreddit

Analyze a subreddit for marketing potential using AI-powered insights. This endpoint performs a comprehensive analysis including rules, moderator activity, content strategy, and generates actionable recommendations.

​
Authentication

Requires active subscription and valid JWT token.

​
Path Parameters

​
subreddit
string
required
The subreddit name (3-21 characters, alphanumeric and underscores only). Do not include “r/” prefix.

​
Query Parameters

​
force
boolean
default:"false"
Admin-only. Force re-analysis even if cached data exists (within 30 days).

​
Caching Behavior

Analyses are cached for 30 days. If a valid cached analysis exists, it will be returned immediately without consuming quota. Admins can bypass cache with ?force=true.

​
Quota Management

This endpoint uses the analysis quota system:
  • Cached results don’t count against quota
  • Fresh analyses increment the usage counter
  • If quota is exceeded, returns 403 with upgrade prompt
  • Admin users have unlimited quota

​
Locking Mechanism

To prevent duplicate analyses, an advisory lock is acquired before fetching:
  1. If lock is available: proceeds with analysis
  2. If lock is held: waits 5 seconds, polls cache, then retries
  3. If lock still unavailable: returns 409 “analysis in progress”

​
Response

​
info
object
Subreddit metadata
​
posts
array
Top 25 posts from the past month (title, score, num_comments, created_utc)
​
analysis
object
AI-generated analysis

​
Example Request

cURL
curl -X GET "https://api.example.com/api/analyze/fitness" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Example Response

{
  "info": {
    "name": "fitness",
    "title": "Fitness",
    "description": "Discussion about fitness, exercise, and nutrition",
    "subscribers": 850000,
    "active_users": 5200,
    "created_utc": 1201747200,
    "over18": false,
    "rules": [
      {
        "title": "No self-promotion",
        "description": "No links to your blog, YouTube, etc.",
        "marketingImpact": "high"
      }
    ],
    "moderators": {
      "total": 8,
      "veryActive": 3,
      "active": 2,
      "dormant": 3,
      "names": ["mod1", "mod2"]
    }
  },
  "posts": [
    {
      "title": "Finally hit my goal weight!",
      "score": 1523,
      "num_comments": 89,
      "created_utc": 1709251200
    }
  ],
  "analysis": {
    "marketingFriendliness": {
      "score": 35,
      "reasons": [
        "Strict no self-promotion rule",
        "High moderator activity",
        "Community values authentic experiences"
      ],
      "recommendations": [
        "Focus on educational content",
        "Build credibility before promoting",
        "Participate genuinely in discussions"
      ]
    },
    "postingLimits": {
      "frequency": 2,
      "bestTimeToPost": ["Monday 6-8am EST", "Thursday 5-7pm EST"],
      "contentRestrictions": ["No direct product links", "No referral codes"]
    },
    "contentStrategy": {
      "recommendedTypes": ["text", "image"],
      "topics": ["Progress updates", "Form checks", "Nutrition tips"],
      "style": "Personal and encouraging",
      "dos": ["Share personal journey", "Ask for advice", "Celebrate wins"],
      "donts": ["Hard sell products", "Use promotional language", "Post repeatedly"]
    },
    "moderationAnalysis": {
      "totalMods": 8,
      "activeMods": 2,
      "veryActiveMods": 3,
      "dormantMods": 3,
      "strictnessLevel": "high",
      "enforcementStyle": "firm",
      "notes": ["Active mod team reviews all posts"],
      "redFlags": ["Zero tolerance for self-promotion"]
    }
  }
}

​
Error Responses

​
400
error
Invalid subreddit name
​
403
error
Subscription required or quota exceeded
{
  "error": "quota_exceeded",
  "feature": "analysis",
  "used": 10,
  "limit": 10,
  "upgrade_required": true,
  "message": "You've used 10/10 analyses this month."
}
​
404
error
Subreddit not found
​
409
error
Analysis already in progress
{
  "error": "analysis_in_progress",
  "message": "Analysis for this subreddit is already in progress. Please retry in a few seconds."
}
​
500
error
Server error or OpenRouter API key not configured
​
502
error
OpenRouter API error or invalid response

​
Implementation Details

The analysis workflow (from api/analyze/[subreddit].js):
  1. Cache check: Returns cached data if fresh (< 30 days old)
  2. Quota check: Verifies user hasn’t exceeded monthly limit
  3. Lock acquisition: Prevents duplicate analyses
  4. Phase 1 - Reddit data fetch (parallel):
    • Subreddit about info
    • Rules
    • Top posts (all-time for title analysis, monthly for UI)
    • Moderator list
  5. Phase 2 - Moderator enrichment: Fetches activity data for up to 8 mods
  6. LLM analysis: Sends enriched data to OpenRouter (google/gemini-3-flash-preview)
  7. Database cache: Stores result in subreddits table
  8. Quota increment: Increments usage counter (except for admins)
  9. Lock release: Frees advisory lock

​
Moderator Activity Tiers

  • very_active: Last activity within 7 days
  • active: Last activity within 30 days
  • dormant: No activity in 30+ days

​
Content Type Normalization

The endpoint normalizes AI-suggested content types to one of three core types:
  • text: Self posts, discussions, stories
  • link: External URLs, videos
  • image: Photos, screenshots, memes

​
Next Steps

OpenRouter Integration

Learn about the AI model configuration

Subreddit Analysis Feature

User guide for the analysis dashboard

Build docs developers (and LLMs) love

Get started for freeTalk to us