{
  "openapi": "3.0.3",
  "info": {
    "title": "RedditDataAPI.io — Real-Time Reddit Posts, Comments Tree & Brand Mention JSON API",
    "version": "1.0.0",
    "description": "Enterprise-grade REST JSON API for real-time Reddit subreddit feeds, nested comment trees, keyword & brand mention search, subreddit intelligence, and user activity profiles. Zero Official Reddit OAuth Rate Limits. $1.00 = 10,000 Credits.",
    "contact": {
      "name": "RedditDataAPI.io Engineering",
      "url": "https://redditdataapi.io",
      "email": "contact@redditdataapi.io"
    }
  },
  "servers": [
    {
      "url": "https://api.redditdataapi.io",
      "description": "Production Gateway"
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your live API key (e.g. rd_live_...)"
      }
    },
    "schemas": {
      "RedditPost": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "1xmjld9"
          },
          "post_id": {
            "type": "string",
            "example": "t3_1xmjld9"
          },
          "subreddit": {
            "type": "string",
            "example": "SaaS"
          },
          "subreddit_name_prefixed": {
            "type": "string",
            "example": "r/SaaS"
          },
          "title": {
            "type": "string",
            "example": "How we scaled our B2B API from $0 to $42k MRR with developer SEO"
          },
          "selftext": {
            "type": "string",
            "example": "Here is the exact breakdown of our engineering-led growth loop..."
          },
          "author": {
            "type": "string",
            "example": "saas_builder_99"
          },
          "score": {
            "type": "integer",
            "example": 418
          },
          "upvote_ratio": {
            "type": "number",
            "example": 0.96
          },
          "num_comments": {
            "type": "integer",
            "example": 87
          },
          "created_utc": {
            "type": "integer",
            "example": 1762254000
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-04T11:00:00.000Z"
          },
          "url": {
            "type": "string",
            "example": "https://www.reddit.com/r/SaaS/comments/1xmjld9/how_we_scaled_our_b2b_api/"
          },
          "permalink": {
            "type": "string",
            "example": "https://www.reddit.com/r/SaaS/comments/1xmjld9/how_we_scaled_our_b2b_api/"
          },
          "domain": {
            "type": "string",
            "nullable": true,
            "example": "self.SaaS"
          },
          "flair": {
            "type": "string",
            "nullable": true,
            "example": "Case Study"
          },
          "over_18": {
            "type": "boolean",
            "example": false
          },
          "is_nsfw": {
            "type": "boolean",
            "example": false
          },
          "is_video": {
            "type": "boolean",
            "example": false
          },
          "is_self": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "RedditComment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "m7k9x2a"
          },
          "comment_id": {
            "type": "string",
            "example": "t1_m7k9x2a"
          },
          "post_id": {
            "type": "string",
            "example": "t3_1xmjld9"
          },
          "subreddit": {
            "type": "string",
            "example": "SaaS"
          },
          "parent_id": {
            "type": "string",
            "example": "t3_1xmjld9"
          },
          "author": {
            "type": "string",
            "example": "infra_lead"
          },
          "body": {
            "type": "string",
            "example": "Moving off official Reddit OAuth saved us from constant 429 errors on AWS IPs."
          },
          "score": {
            "type": "integer",
            "example": 64
          },
          "depth": {
            "type": "integer",
            "example": 0
          },
          "is_submitter": {
            "type": "boolean",
            "example": false
          },
          "is_stickied": {
            "type": "boolean",
            "example": false
          },
          "created_utc": {
            "type": "integer",
            "example": 1762255800
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-04T11:30:00.000Z"
          },
          "permalink": {
            "type": "string",
            "example": "https://www.reddit.com/r/SaaS/comments/1xmjld9/_/m7k9x2a/"
          }
        }
      },
      "ResponseMeta": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "UUID v4 request identifier"
          },
          "endpoint": {
            "type": "string",
            "description": "Canonical /v1/* endpoint path"
          },
          "credits_used": {
            "type": "integer",
            "description": "Credits deducted for this call (0 on error or empty)"
          },
          "credits_remaining": {
            "type": "integer",
            "description": "Remaining credit balance on account"
          },
          "cache_hit": {
            "type": "boolean",
            "description": "Whether served from L1 Redis cache"
          },
          "data_age_seconds": {
            "type": "integer",
            "description": "Age of cached payload in seconds"
          },
          "latency_ms": {
            "type": "integer",
            "description": "End-to-end gateway latency in milliseconds"
          }
        }
      }
    }
  },
  "paths": {
    "/v1/subreddit/posts": {
      "get": {
        "summary": "Fetch Subreddit Posts Feed (hot / new / top / rising)",
        "operationId": "getSubredditPosts",
        "parameters": [
          {
            "name": "subreddit",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "saas"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "hot",
                "new",
                "top",
                "rising"
              ],
              "default": "hot"
            }
          },
          {
            "name": "time_filter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "hour",
                "day",
                "week",
                "month",
                "year",
                "all"
              ],
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized subreddit posts list (1 Credit per post returned, min 2 Credits)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0,
                      "description": "0 on success"
                    },
                    "status": {
                      "type": "string",
                      "example": "ok",
                      "description": "Response status"
                    },
                    "data": {
                      "type": "object",
                      "description": "Normalized post feed payload",
                      "properties": {
                        "items": {
                          "type": "array",
                          "description": "Array of normalized Reddit posts",
                          "items": {
                            "$ref": "#/components/schemas/RedditPost"
                          }
                        },
                        "count": {
                          "type": "integer",
                          "example": 25,
                          "description": "Number of items returned in this page"
                        },
                        "next_cursor": {
                          "type": "string",
                          "nullable": true,
                          "example": "t3_1xmjld9",
                          "description": "Pagination cursor for next page"
                        },
                        "has_more": {
                          "type": "boolean",
                          "example": true,
                          "description": "Whether another page is available"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    }
                  }
                },
                "example": {
                  "code": 0,
                  "provider": "https://redditdataapi.io",
                  "status": "ok",
                  "msg": "success",
                  "data": {
                    "items": [
                      {
                        "id": "1xmjld9",
                        "post_id": "t3_1xmjld9",
                        "subreddit": "saas",
                        "subreddit_name_prefixed": "r/saas",
                        "title": "How we scaled our B2B SaaS to $42k MRR using automated Reddit brand mention alerts",
                        "selftext": "We built an internal keyword monitor across r/saas, r/startups, and r/entrepreneur...",
                        "author": "indie_founder_io",
                        "score": 384,
                        "upvote_ratio": 0.96,
                        "num_comments": 78,
                        "created_utc": 1762286400,
                        "created_at": "2026-11-04T20:00:00.000Z",
                        "url": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/",
                        "permalink": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/",
                        "domain": "self.saas",
                        "flair": "Case Study",
                        "over_18": false,
                        "is_nsfw": false,
                        "is_video": false,
                        "is_self": true
                      }
                    ],
                    "count": 1,
                    "next_cursor": "t3_1xmjld9",
                    "cursor": "t3_1xmjld9",
                    "has_more": true,
                    "hasMore": true
                  },
                  "meta": {
                    "request_id": "c42d9f10-81e3-4c22-9118-092f1a8b1122",
                    "endpoint": "/v1/subreddit/posts",
                    "credits_used": 2,
                    "credits_remaining": 249998,
                    "cache_hit": false,
                    "data_age_seconds": 0,
                    "latency_ms": 185
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/subreddit/info": {
      "get": {
        "summary": "Fetch Subreddit Metadata, Subscribers & Community Rules",
        "operationId": "getSubredditInfo",
        "parameters": [
          {
            "name": "subreddit",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "saas"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Subreddit profile metadata (2 Credits per lookup)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "data": {
                      "$ref": "#/components/schemas/RedditSubreddit"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    }
                  }
                },
                "example": {
                  "code": 0,
                  "provider": "https://redditdataapi.io",
                  "status": "ok",
                  "msg": "success",
                  "data": {
                    "subreddit": "saas",
                    "display_name": "SaaS",
                    "subreddit_id": "t5_2qk9v",
                    "title": "Software as a Service (SaaS) Founders, Engineers & Operators",
                    "public_description": "Discussions on building, scaling, and marketing B2B & B2C SaaS products.",
                    "description": "Welcome to r/SaaS! Share metrics, growth playbooks, and engineering architectures.",
                    "subscribers": 248900,
                    "active_user_count": 615,
                    "over_18": false,
                    "lang": "en",
                    "icon_img": "https://styles.redditmedia.com/t5_2qk9v/styles/communityIcon.png",
                    "banner_img": null,
                    "url": "https://www.reddit.com/r/SaaS/",
                    "created_utc": 1235865600,
                    "created_at": "2009-02-28T00:00:00.000Z",
                    "rules": [
                      {
                        "short_name": "No low-effort self-promotion",
                        "description": "Share actionable lessons and transparent data."
                      }
                    ]
                  },
                  "meta": {
                    "request_id": "e91b2f10-81e3-4c22-9118-092f1a8b5566",
                    "endpoint": "/v1/subreddit/info",
                    "credits_used": 2,
                    "credits_remaining": 249994,
                    "cache_hit": true,
                    "data_age_seconds": 12,
                    "latency_ms": 14
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/posts/search": {
      "get": {
        "summary": "Search Reddit Posts & Brand Mentions Globally or Within a Subreddit",
        "operationId": "searchRedditPosts",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "web scraping api"
            }
          },
          {
            "name": "subreddit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "saas"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "relevance",
                "top",
                "comments"
              ],
              "default": "new"
            }
          },
          {
            "name": "time_filter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "hour",
                "day",
                "week",
                "month",
                "year"
              ],
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching Reddit posts (1 Credit per post returned, 0 Credits if empty)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0,
                      "description": "0 on success"
                    },
                    "status": {
                      "type": "string",
                      "example": "ok",
                      "description": "Response status"
                    },
                    "data": {
                      "type": "object",
                      "description": "Normalized post feed payload",
                      "properties": {
                        "items": {
                          "type": "array",
                          "description": "Array of normalized Reddit posts",
                          "items": {
                            "$ref": "#/components/schemas/RedditPost"
                          }
                        },
                        "count": {
                          "type": "integer",
                          "example": 25,
                          "description": "Number of items returned in this page"
                        },
                        "next_cursor": {
                          "type": "string",
                          "nullable": true,
                          "example": "t3_1xmjld9",
                          "description": "Pagination cursor for next page"
                        },
                        "has_more": {
                          "type": "boolean",
                          "example": true,
                          "description": "Whether another page is available"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    }
                  }
                },
                "example": {
                  "code": 0,
                  "provider": "https://redditdataapi.io",
                  "status": "ok",
                  "msg": "success",
                  "data": {
                    "items": [
                      {
                        "id": "1xmjld9",
                        "post_id": "t3_1xmjld9",
                        "subreddit": "saas",
                        "subreddit_name_prefixed": "r/saas",
                        "title": "How we scaled our B2B SaaS to $42k MRR using automated Reddit brand mention alerts",
                        "selftext": "We built an internal keyword monitor across r/saas, r/startups, and r/entrepreneur...",
                        "author": "indie_founder_io",
                        "score": 384,
                        "upvote_ratio": 0.96,
                        "num_comments": 78,
                        "created_utc": 1762286400,
                        "created_at": "2026-11-04T20:00:00.000Z",
                        "url": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/",
                        "permalink": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/",
                        "domain": "self.saas",
                        "flair": "Case Study",
                        "over_18": false,
                        "is_nsfw": false,
                        "is_video": false,
                        "is_self": true
                      }
                    ],
                    "count": 1,
                    "next_cursor": "t3_1xmjld9",
                    "cursor": "t3_1xmjld9",
                    "has_more": true,
                    "hasMore": true
                  },
                  "meta": {
                    "request_id": "c42d9f10-81e3-4c22-9118-092f1a8b1122",
                    "endpoint": "/v1/posts/search",
                    "credits_used": 2,
                    "credits_remaining": 249998,
                    "cache_hit": false,
                    "data_age_seconds": 0,
                    "latency_ms": 185
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/posts/detail": {
      "get": {
        "summary": "Fetch Single Reddit Post Detail by ID or URL",
        "operationId": "getPostDetail",
        "parameters": [
          {
            "name": "post_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "1xmjld9"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized post object (2 Credits)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "data": {
                      "$ref": "#/components/schemas/RedditPost"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    }
                  }
                },
                "example": {
                  "code": 0,
                  "provider": "https://redditdataapi.io",
                  "status": "ok",
                  "msg": "success",
                  "data": {
                    "id": "1xmjld9",
                    "post_id": "t3_1xmjld9",
                    "subreddit": "saas",
                    "subreddit_name_prefixed": "r/saas",
                    "title": "How we scaled our B2B SaaS to $42k MRR using automated Reddit brand mention alerts",
                    "selftext": "We built an internal keyword monitor across r/saas, r/startups, and r/entrepreneur...",
                    "author": "indie_founder_io",
                    "score": 384,
                    "upvote_ratio": 0.96,
                    "num_comments": 78,
                    "created_utc": 1762286400,
                    "created_at": "2026-11-04T20:00:00.000Z",
                    "url": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/",
                    "permalink": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/",
                    "domain": "self.saas",
                    "flair": "Case Study",
                    "over_18": false,
                    "is_nsfw": false,
                    "is_video": false,
                    "is_self": true
                  },
                  "meta": {
                    "request_id": "f12c2f10-81e3-4c22-9118-092f1a8b7788",
                    "endpoint": "/v1/posts/detail",
                    "credits_used": 2,
                    "credits_remaining": 249992,
                    "cache_hit": true,
                    "data_age_seconds": 8,
                    "latency_ms": 11
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/posts/comments": {
      "get": {
        "summary": "Fetch Post Comment Tree & Replies",
        "operationId": "getPostComments",
        "parameters": [
          {
            "name": "post_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "1xmjld9"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "top",
                "new",
                "best",
                "controversial",
                "old"
              ],
              "default": "top"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Comment tree nodes with depth & parent_id (1 Credit per comment returned)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0,
                      "description": "0 on success"
                    },
                    "status": {
                      "type": "string",
                      "example": "ok",
                      "description": "Response status"
                    },
                    "data": {
                      "type": "object",
                      "description": "Flattened comment tree with depth and parent_id",
                      "properties": {
                        "post_id": {
                          "type": "string",
                          "example": "t3_1xmjld9",
                          "description": "Target Reddit post ID"
                        },
                        "items": {
                          "type": "array",
                          "description": "Array of normalized comments",
                          "items": {
                            "$ref": "#/components/schemas/RedditComment"
                          }
                        },
                        "count": {
                          "type": "integer",
                          "example": 100,
                          "description": "Number of comments returned"
                        },
                        "next_cursor": {
                          "type": "string",
                          "nullable": true,
                          "example": "100",
                          "description": "Offset cursor for next comment batch"
                        },
                        "has_more": {
                          "type": "boolean",
                          "example": false,
                          "description": "Whether more comments remain"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    }
                  }
                },
                "example": {
                  "code": 0,
                  "provider": "https://redditdataapi.io",
                  "status": "ok",
                  "msg": "success",
                  "data": {
                    "post_id": "t3_1xmjld9",
                    "items": [
                      {
                        "id": "m8kq21a",
                        "comment_id": "t1_m8kq21a",
                        "post_id": "t3_1xmjld9",
                        "subreddit": "saas",
                        "parent_id": "t3_1xmjld9",
                        "author": "devtools_builder",
                        "body": "What polling interval do you use for keyword search? We switched from PRAW to RedditDataAPI.io and cut latency to 180ms.",
                        "score": 49,
                        "depth": 0,
                        "is_submitter": false,
                        "is_stickied": false,
                        "created_utc": 1762287600,
                        "created_at": "2026-11-04T20:20:00.000Z",
                        "permalink": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/m8kq21a/"
                      }
                    ],
                    "count": 1,
                    "next_cursor": null,
                    "cursor": null,
                    "has_more": false,
                    "hasMore": false
                  },
                  "meta": {
                    "request_id": "d81a2f10-81e3-4c22-9118-092f1a8b3344",
                    "endpoint": "/v1/posts/comments",
                    "credits_used": 2,
                    "credits_remaining": 249996,
                    "cache_hit": false,
                    "data_age_seconds": 0,
                    "latency_ms": 210
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/posts/popular": {
      "get": {
        "summary": "Fetch Trending & Popular Reddit Posts (r/popular)",
        "operationId": "getPopularPosts",
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "hot",
                "new",
                "top",
                "rising"
              ],
              "default": "hot"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trending Reddit posts (1 Credit per post returned)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0,
                      "description": "0 on success"
                    },
                    "status": {
                      "type": "string",
                      "example": "ok",
                      "description": "Response status"
                    },
                    "data": {
                      "type": "object",
                      "description": "Normalized post feed payload",
                      "properties": {
                        "items": {
                          "type": "array",
                          "description": "Array of normalized Reddit posts",
                          "items": {
                            "$ref": "#/components/schemas/RedditPost"
                          }
                        },
                        "count": {
                          "type": "integer",
                          "example": 25,
                          "description": "Number of items returned in this page"
                        },
                        "next_cursor": {
                          "type": "string",
                          "nullable": true,
                          "example": "t3_1xmjld9",
                          "description": "Pagination cursor for next page"
                        },
                        "has_more": {
                          "type": "boolean",
                          "example": true,
                          "description": "Whether another page is available"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    }
                  }
                },
                "example": {
                  "code": 0,
                  "provider": "https://redditdataapi.io",
                  "status": "ok",
                  "msg": "success",
                  "data": {
                    "items": [
                      {
                        "id": "1xmjld9",
                        "post_id": "t3_1xmjld9",
                        "subreddit": "saas",
                        "subreddit_name_prefixed": "r/saas",
                        "title": "How we scaled our B2B SaaS to $42k MRR using automated Reddit brand mention alerts",
                        "selftext": "We built an internal keyword monitor across r/saas, r/startups, and r/entrepreneur...",
                        "author": "indie_founder_io",
                        "score": 384,
                        "upvote_ratio": 0.96,
                        "num_comments": 78,
                        "created_utc": 1762286400,
                        "created_at": "2026-11-04T20:00:00.000Z",
                        "url": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/",
                        "permalink": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/",
                        "domain": "self.saas",
                        "flair": "Case Study",
                        "over_18": false,
                        "is_nsfw": false,
                        "is_video": false,
                        "is_self": true
                      }
                    ],
                    "count": 1,
                    "next_cursor": "t3_1xmjld9",
                    "cursor": "t3_1xmjld9",
                    "has_more": true,
                    "hasMore": true
                  },
                  "meta": {
                    "request_id": "c42d9f10-81e3-4c22-9118-092f1a8b1122",
                    "endpoint": "/v1/posts/popular",
                    "credits_used": 2,
                    "credits_remaining": 249998,
                    "cache_hit": false,
                    "data_age_seconds": 0,
                    "latency_ms": 185
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/profile": {
      "get": {
        "summary": "Fetch Reddit User Profile & Karma Breakdown",
        "operationId": "getUserProfile",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "spez"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reddit user profile metadata (2 Credits)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "data": {
                      "$ref": "#/components/schemas/RedditUser"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    }
                  }
                },
                "example": {
                  "code": 0,
                  "provider": "https://redditdataapi.io",
                  "status": "ok",
                  "msg": "success",
                  "data": {
                    "username": "spez",
                    "display_name": "spez",
                    "user_id": "t2_1w72",
                    "link_karma": 164200,
                    "comment_karma": 785400,
                    "total_karma": 949600,
                    "is_gold": true,
                    "is_mod": true,
                    "is_verified": true,
                    "has_verified_email": true,
                    "over_18": false,
                    "icon_img": "https://www.redditstatic.com/avatars/defaults/v2/avatar_default_1.png",
                    "bio": "CEO at Reddit.",
                    "created_utc": 1118016000,
                    "created_at": "2005-06-06T00:00:00.000Z"
                  },
                  "meta": {
                    "request_id": "a34d2f10-81e3-4c22-9118-092f1a8b9900",
                    "endpoint": "/v1/users/profile",
                    "credits_used": 2,
                    "credits_remaining": 249990,
                    "cache_hit": true,
                    "data_age_seconds": 24,
                    "latency_ms": 12
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/posts": {
      "get": {
        "summary": "Fetch Public Posts Submitted by a Reddit User",
        "operationId": "getUserPosts",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "spez"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "hot",
                "top"
              ],
              "default": "new"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User submitted posts (1 Credit per post returned)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0,
                      "description": "0 on success"
                    },
                    "status": {
                      "type": "string",
                      "example": "ok",
                      "description": "Response status"
                    },
                    "data": {
                      "type": "object",
                      "description": "Normalized post feed payload",
                      "properties": {
                        "items": {
                          "type": "array",
                          "description": "Array of normalized Reddit posts",
                          "items": {
                            "$ref": "#/components/schemas/RedditPost"
                          }
                        },
                        "count": {
                          "type": "integer",
                          "example": 25,
                          "description": "Number of items returned in this page"
                        },
                        "next_cursor": {
                          "type": "string",
                          "nullable": true,
                          "example": "t3_1xmjld9",
                          "description": "Pagination cursor for next page"
                        },
                        "has_more": {
                          "type": "boolean",
                          "example": true,
                          "description": "Whether another page is available"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    }
                  }
                },
                "example": {
                  "code": 0,
                  "provider": "https://redditdataapi.io",
                  "status": "ok",
                  "msg": "success",
                  "data": {
                    "items": [
                      {
                        "id": "1xmjld9",
                        "post_id": "t3_1xmjld9",
                        "subreddit": "saas",
                        "subreddit_name_prefixed": "r/saas",
                        "title": "How we scaled our B2B SaaS to $42k MRR using automated Reddit brand mention alerts",
                        "selftext": "We built an internal keyword monitor across r/saas, r/startups, and r/entrepreneur...",
                        "author": "indie_founder_io",
                        "score": 384,
                        "upvote_ratio": 0.96,
                        "num_comments": 78,
                        "created_utc": 1762286400,
                        "created_at": "2026-11-04T20:00:00.000Z",
                        "url": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/",
                        "permalink": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/",
                        "domain": "self.saas",
                        "flair": "Case Study",
                        "over_18": false,
                        "is_nsfw": false,
                        "is_video": false,
                        "is_self": true
                      }
                    ],
                    "count": 1,
                    "next_cursor": "t3_1xmjld9",
                    "cursor": "t3_1xmjld9",
                    "has_more": true,
                    "hasMore": true
                  },
                  "meta": {
                    "request_id": "c42d9f10-81e3-4c22-9118-092f1a8b1122",
                    "endpoint": "/v1/users/posts",
                    "credits_used": 2,
                    "credits_remaining": 249998,
                    "cache_hit": false,
                    "data_age_seconds": 0,
                    "latency_ms": 185
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/comments": {
      "get": {
        "summary": "Fetch Public Comments Authored by a Reddit User",
        "operationId": "getUserComments",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "spez"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "top"
              ],
              "default": "new"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User comments (1 Credit per comment returned)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0,
                      "description": "0 on success"
                    },
                    "status": {
                      "type": "string",
                      "example": "ok",
                      "description": "Response status"
                    },
                    "data": {
                      "type": "object",
                      "description": "Flattened comment tree with depth and parent_id",
                      "properties": {
                        "post_id": {
                          "type": "string",
                          "example": "t3_1xmjld9",
                          "description": "Target Reddit post ID"
                        },
                        "items": {
                          "type": "array",
                          "description": "Array of normalized comments",
                          "items": {
                            "$ref": "#/components/schemas/RedditComment"
                          }
                        },
                        "count": {
                          "type": "integer",
                          "example": 100,
                          "description": "Number of comments returned"
                        },
                        "next_cursor": {
                          "type": "string",
                          "nullable": true,
                          "example": "100",
                          "description": "Offset cursor for next comment batch"
                        },
                        "has_more": {
                          "type": "boolean",
                          "example": false,
                          "description": "Whether more comments remain"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    }
                  }
                },
                "example": {
                  "code": 0,
                  "provider": "https://redditdataapi.io",
                  "status": "ok",
                  "msg": "success",
                  "data": {
                    "post_id": "t3_1xmjld9",
                    "items": [
                      {
                        "id": "m8kq21a",
                        "comment_id": "t1_m8kq21a",
                        "post_id": "t3_1xmjld9",
                        "subreddit": "saas",
                        "parent_id": "t3_1xmjld9",
                        "author": "devtools_builder",
                        "body": "What polling interval do you use for keyword search? We switched from PRAW to RedditDataAPI.io and cut latency to 180ms.",
                        "score": 49,
                        "depth": 0,
                        "is_submitter": false,
                        "is_stickied": false,
                        "created_utc": 1762287600,
                        "created_at": "2026-11-04T20:20:00.000Z",
                        "permalink": "https://www.reddit.com/r/saas/comments/1xmjld9/how_we_scaled_our_b2b_saas/m8kq21a/"
                      }
                    ],
                    "count": 1,
                    "next_cursor": null,
                    "cursor": null,
                    "has_more": false,
                    "hasMore": false
                  },
                  "meta": {
                    "request_id": "d81a2f10-81e3-4c22-9118-092f1a8b3344",
                    "endpoint": "/v1/users/comments",
                    "credits_used": 2,
                    "credits_remaining": 249996,
                    "cache_hit": false,
                    "data_age_seconds": 0,
                    "latency_ms": 210
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "operationId": "getGatewayHealth",
        "tags": [
          "System"
        ],
        "summary": "Gateway Health & Mirror Telemetry",
        "description": "Zero-cost health probe returning real-time upstream pool status and total posts, comments, subreddits, and users cached in our local PostgreSQL 16 mirror.",
        "x-credits-per-request": "0 Credits (Free)",
        "x-price-per-request": "$0.00",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Gateway health status and cached entity counts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Gateway health status (ok)"
                    },
                    "service": {
                      "type": "string",
                      "description": "Service identifier (redditdataapi.io)"
                    },
                    "version": {
                      "type": "string",
                      "description": "Gateway release version"
                    },
                    "posts_cached": {
                      "type": "integer",
                      "description": "Total public Reddit posts indexed in local PostgreSQL 16 mirror"
                    },
                    "comments_cached": {
                      "type": "integer",
                      "description": "Total public Reddit comments indexed in local PostgreSQL 16 mirror"
                    },
                    "subreddits_cached": {
                      "type": "integer",
                      "description": "Total subreddits indexed in local PostgreSQL 16 mirror"
                    },
                    "users_cached": {
                      "type": "integer",
                      "description": "Total Reddit user profiles indexed in local PostgreSQL 16 mirror"
                    },
                    "timestamp": {
                      "type": "string",
                      "description": "ISO-8601 server timestamp"
                    }
                  }
                },
                "example": {
                  "status": "ok",
                  "service": "redditdataapi.io",
                  "version": "1.0.0",
                  "posts_cached": 14820,
                  "comments_cached": 92410,
                  "subreddits_cached": 640,
                  "users_cached": 3890,
                  "timestamp": "2026-11-04T16:00:00.000Z"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "System",
      "description": "Gateway health and local PostgreSQL 16 mirror telemetry"
    }
  ]
}