{
  "openapi": "3.1.0",
  "info": {
    "title": "FetchLayer Reddit API",
    "version": "1.0.0",
    "description": "Independent Reddit API with structured JSON responses, Bearer auth, and 15 REST endpoints for search, content, communities, users, discovery, and utility workflows."
  },
  "servers": [
    {
      "url": "https://api.fetchlayer.dev/reddit"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key. No Reddit OAuth credentials are required."
      }
    }
  },
  "paths": {
    "/search": {
      "post": {
        "operationId": "search",
        "tags": [
          "Search"
        ],
        "summary": "Posts matching a keyword — globally or within a subreddit",
        "description": "Search Reddit posts by keyword. Optionally narrow to a specific subreddit. Results include title, score, comment count, author, and permalink.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search keyword or phrase."
                  },
                  "subreddit": {
                    "type": "string",
                    "description": "Limit search to a specific subreddit."
                  },
                  "sort": {
                    "type": "string",
                    "description": "Sort order.",
                    "example": "relevance"
                  },
                  "limit": {
                    "type": "number",
                    "description": "Number of results (max 100).",
                    "example": "25"
                  },
                  "time": {
                    "type": "string",
                    "description": "Time filter: hour, day, week, month, year, all.",
                    "example": "all"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "developer tools",
                    "subreddit": "webdev",
                    "sort": "top",
                    "limit": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string",
                            "description": "Post title."
                          },
                          "subreddit": {
                            "type": "string",
                            "description": "Subreddit name."
                          },
                          "author": {
                            "type": "string",
                            "description": "Reddit username."
                          },
                          "score": {
                            "type": "number",
                            "description": "Upvote score."
                          },
                          "numComments": {
                            "type": "number",
                            "description": "Comment count."
                          },
                          "url": {
                            "type": "string",
                            "description": "Permalink to the post."
                          },
                          "createdUtc": {
                            "type": "number",
                            "description": "Unix timestamp of creation."
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "results": [
                        {
                          "title": "What tools do you swear by?",
                          "subreddit": "webdev",
                          "author": "devuser",
                          "score": 3241,
                          "numComments": 418,
                          "url": "https://reddit.com/r/webdev/comments/...",
                          "createdUtc": 1718000000
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/search-comments": {
      "post": {
        "operationId": "search-comments",
        "tags": [
          "Search"
        ],
        "summary": "Comments matching a keyword — globally or within a subreddit",
        "description": "Search Reddit comments by keyword. Optionally narrow to a specific subreddit. Results include comment body, score, author, subreddit, and permalink.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search keyword or phrase."
                  },
                  "subreddit": {
                    "type": "string",
                    "description": "Limit search to a specific subreddit."
                  },
                  "sort": {
                    "type": "string",
                    "description": "Sort order: relevance, new, comments, top.",
                    "example": "relevance"
                  },
                  "time": {
                    "type": "string",
                    "description": "Time filter: hour, day, week, month, year, all.",
                    "example": "all"
                  },
                  "limit": {
                    "type": "number",
                    "description": "Number of results (max 100).",
                    "example": "25"
                  },
                  "pages": {
                    "type": "number",
                    "description": "Number of pages to scrape.",
                    "example": "1"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "mcp",
                    "sort": "top",
                    "time": "all",
                    "limit": 25
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "body": {
                            "type": "string",
                            "description": "Comment text."
                          },
                          "subreddit": {
                            "type": "string",
                            "description": "Subreddit name."
                          },
                          "author": {
                            "type": "string",
                            "description": "Reddit username."
                          },
                          "score": {
                            "type": "number",
                            "description": "Upvote score."
                          },
                          "permalink": {
                            "type": "string",
                            "description": "Permalink to the comment."
                          },
                          "createdUtc": {
                            "type": "number",
                            "description": "Unix timestamp of creation."
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "results": [
                        {
                          "body": "MCP has been a game changer for my workflow.",
                          "subreddit": "programming",
                          "author": "devuser",
                          "score": 342,
                          "permalink": "/r/programming/comments/.../comment/...",
                          "createdUtc": 1718000000
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/post": {
      "post": {
        "operationId": "post",
        "tags": [
          "Content"
        ],
        "summary": "Full post body + complete comment tree (paginated)",
        "description": "Retrieve a single post by its Reddit ID (t3_xxxxx) or full URL. Returns the post body, metadata, and paginated comments.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "postId": {
                    "type": "string",
                    "description": "Reddit post ID (e.g. t3_abc123) or full URL."
                  },
                  "sort": {
                    "type": "string",
                    "description": "Comment sort order.",
                    "example": "best"
                  },
                  "limit": {
                    "type": "number",
                    "description": "Max comments to return.",
                    "example": "100"
                  },
                  "depth": {
                    "type": "number",
                    "description": "How many levels of replies to include.",
                    "example": "3"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "postId"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "postId": "t3_abc123",
                    "sort": "top",
                    "limit": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "post": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "Post title."
                        },
                        "selftext": {
                          "type": "string",
                          "description": "Post body text (may be empty for link posts)."
                        },
                        "author": {
                          "type": "string",
                          "description": "Author username."
                        },
                        "score": {
                          "type": "number",
                          "description": "Upvote score."
                        },
                        "upvoteRatio": {
                          "type": "number",
                          "description": "Upvote ratio (0–1)."
                        },
                        "numComments": {
                          "type": "number",
                          "description": "Total comment count."
                        },
                        "url": {
                          "type": "string",
                          "description": "URL the post links to (if link post)."
                        },
                        "permalink": {
                          "type": "string",
                          "description": "Reddit permalink."
                        },
                        "createdUtc": {
                          "type": "number",
                          "description": "Unix timestamp."
                        },
                        "edited": {
                          "type": "boolean",
                          "description": "Whether the post was edited."
                        }
                      },
                      "additionalProperties": false
                    },
                    "comments": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Comment ID."
                          },
                          "author": {
                            "type": "string",
                            "description": "Comment author."
                          },
                          "body": {
                            "type": "string",
                            "description": "Comment text."
                          },
                          "score": {
                            "type": "number",
                            "description": "Comment score."
                          },
                          "replies": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "description": "Nested reply objects."
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "post": {
                        "title": "Example post",
                        "selftext": "This is the post body...",
                        "author": "reddituser",
                        "score": 1500,
                        "upvoteRatio": 0.92,
                        "numComments": 87,
                        "url": "https://example.com",
                        "permalink": "/r/test/comments/abc123/example_post/",
                        "createdUtc": 1718000000,
                        "edited": false
                      },
                      "comments": [
                        {
                          "id": "c1",
                          "author": "user1",
                          "body": "Great post!",
                          "score": 42,
                          "replies": []
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/community-posts": {
      "post": {
        "operationId": "community-posts",
        "tags": [
          "Community"
        ],
        "summary": "Posts from any subreddit — hot, new, top, rising",
        "description": "Retrieve the current post feed for a subreddit. Supports sorting by hot, new, top, rising, and controversy.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subreddit": {
                    "type": "string",
                    "description": "Subreddit name (without r/)."
                  },
                  "sort": {
                    "type": "string",
                    "description": "Feed sort order.",
                    "example": "hot"
                  },
                  "limit": {
                    "type": "number",
                    "description": "Number of posts (max 100).",
                    "example": "25"
                  },
                  "time": {
                    "type": "string",
                    "description": "Time filter for top sort.",
                    "example": "all"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "subreddit"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "subreddit": "programming",
                    "sort": "top",
                    "limit": 10,
                    "time": "week"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string",
                            "description": "Post title."
                          },
                          "author": {
                            "type": "string",
                            "description": "Author username."
                          },
                          "score": {
                            "type": "number",
                            "description": "Upvote score."
                          },
                          "numComments": {
                            "type": "number",
                            "description": "Comment count."
                          },
                          "permalink": {
                            "type": "string",
                            "description": "Relative permalink."
                          },
                          "createdUtc": {
                            "type": "number",
                            "description": "Unix timestamp."
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "posts": [
                        {
                          "title": "Example programming post",
                          "author": "coder123",
                          "score": 2500,
                          "numComments": 320,
                          "permalink": "/r/programming/comments/xyz/",
                          "createdUtc": 1718000000
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/community-details": {
      "post": {
        "operationId": "community-details",
        "tags": [
          "Community"
        ],
        "summary": "Subreddit metadata — subscribers, description, rules",
        "description": "Get detailed metadata about a subreddit including subscriber count, active users, description, rules, and moderation info.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subreddit": {
                    "type": "string",
                    "description": "Subreddit name (without r/)."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "subreddit"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "subreddit": "programming"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Subreddit display name."
                    },
                    "title": {
                      "type": "string",
                      "description": "Subreddit title."
                    },
                    "description": {
                      "type": "string",
                      "description": "Sidebar/description text."
                    },
                    "subscribers": {
                      "type": "number",
                      "description": "Subscriber count."
                    },
                    "activeUsers": {
                      "type": "number",
                      "description": "Currently active users."
                    },
                    "createdUtc": {
                      "type": "number",
                      "description": "Creation timestamp."
                    },
                    "rules": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "Array of rule objects with title and description."
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "name": "programming",
                      "title": "Programming",
                      "description": "Computer Programming",
                      "subscribers": 35000000,
                      "activeUsers": 45000,
                      "createdUtc": 1200000000,
                      "rules": [
                        {
                          "title": "No spam",
                          "description": "Self-promotion is not allowed."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/user-profile": {
      "post": {
        "operationId": "user-profile",
        "tags": [
          "User"
        ],
        "summary": "Karma, bio, account age, and public profile info",
        "description": "Retrieve public profile information for any Reddit user including karma breakdown, account age, and bio.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "type": "string",
                    "description": "Reddit username."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "username"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "username": "spez"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "username": {
                      "type": "string",
                      "description": "Username."
                    },
                    "totalKarma": {
                      "type": "number",
                      "description": "Combined karma."
                    },
                    "postKarma": {
                      "type": "number",
                      "description": "Post karma."
                    },
                    "commentKarma": {
                      "type": "number",
                      "description": "Comment karma."
                    },
                    "accountAgeDays": {
                      "type": "number",
                      "description": "Account age in days."
                    },
                    "createdUtc": {
                      "type": "number",
                      "description": "Account creation timestamp."
                    },
                    "isGold": {
                      "type": "boolean",
                      "description": "Has Reddit Premium."
                    },
                    "isMod": {
                      "type": "boolean",
                      "description": "Is a moderator anywhere."
                    },
                    "description": {
                      "type": "string",
                      "description": "User bio/about text."
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "username": "spez",
                      "totalKarma": 1500000,
                      "postKarma": 800000,
                      "commentKarma": 700000,
                      "accountAgeDays": 6200,
                      "createdUtc": 1150000000,
                      "isGold": true,
                      "isMod": true,
                      "description": "Reddit co-founder."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/user-posts": {
      "post": {
        "operationId": "user-posts",
        "tags": [
          "User"
        ],
        "summary": "All public posts submitted by a user",
        "description": "Retrieve the public post history for a Reddit user. Supports pagination.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "type": "string",
                    "description": "Reddit username."
                  },
                  "limit": {
                    "type": "number",
                    "description": "Number of posts (max 100).",
                    "example": "25"
                  },
                  "before": {
                    "type": "string",
                    "description": "Pagination cursor (before)."
                  },
                  "after": {
                    "type": "string",
                    "description": "Pagination cursor (after)."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "username"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "username": "spez",
                    "limit": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string",
                            "description": "Post title."
                          },
                          "subreddit": {
                            "type": "string",
                            "description": "Subreddit."
                          },
                          "score": {
                            "type": "number",
                            "description": "Score."
                          },
                          "numComments": {
                            "type": "number",
                            "description": "Comment count."
                          },
                          "permalink": {
                            "type": "string",
                            "description": "Relative permalink."
                          },
                          "createdUtc": {
                            "type": "number",
                            "description": "Unix timestamp."
                          }
                        },
                        "additionalProperties": false
                      }
                    },
                    "after": {
                      "type": "string",
                      "description": "Cursor for next page."
                    },
                    "before": {
                      "type": "string",
                      "description": "Cursor for previous page."
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "posts": [
                        {
                          "title": "Announcing new features",
                          "subreddit": "reddit",
                          "score": 5000,
                          "numComments": 800,
                          "permalink": "/r/reddit/comments/abc/",
                          "createdUtc": 1718000000
                        }
                      ],
                      "after": "t3_next"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/user-comments": {
      "post": {
        "operationId": "user-comments",
        "tags": [
          "User"
        ],
        "summary": "Comment history for any public user",
        "description": "Retrieve the public comment history for a Reddit user. Supports pagination.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "type": "string",
                    "description": "Reddit username."
                  },
                  "limit": {
                    "type": "number",
                    "description": "Number of comments (max 100).",
                    "example": "25"
                  },
                  "before": {
                    "type": "string",
                    "description": "Pagination cursor (before)."
                  },
                  "after": {
                    "type": "string",
                    "description": "Pagination cursor (after)."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "username"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "username": "spez",
                    "limit": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "comments": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "body": {
                            "type": "string",
                            "description": "Comment text."
                          },
                          "subreddit": {
                            "type": "string",
                            "description": "Subreddit."
                          },
                          "score": {
                            "type": "number",
                            "description": "Score."
                          },
                          "postTitle": {
                            "type": "string",
                            "description": "Parent post title."
                          },
                          "permalink": {
                            "type": "string",
                            "description": "Relative permalink."
                          },
                          "createdUtc": {
                            "type": "number",
                            "description": "Unix timestamp."
                          }
                        },
                        "additionalProperties": false
                      }
                    },
                    "after": {
                      "type": "string",
                      "description": "Cursor for next page."
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "comments": [
                        {
                          "body": "Thanks for the feedback!",
                          "subreddit": "reddit",
                          "score": 250,
                          "postTitle": "Announcing new features",
                          "permalink": "/r/reddit/comments/abc/comment/xyz/",
                          "createdUtc": 1718000000
                        }
                      ],
                      "after": "t1_next"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/search-communities": {
      "post": {
        "operationId": "search-communities",
        "tags": [
          "Search"
        ],
        "summary": "Find subreddits by keyword",
        "description": "Search for subreddits matching a keyword. Returns community name, subscriber count, and description.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search keyword."
                  },
                  "limit": {
                    "type": "number",
                    "description": "Max results.",
                    "example": "25"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "programming",
                    "limit": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "Subreddit name."
                          },
                          "title": {
                            "type": "string",
                            "description": "Subreddit display title."
                          },
                          "subscribers": {
                            "type": "number",
                            "description": "Subscriber count."
                          },
                          "description": {
                            "type": "string",
                            "description": "Short description."
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "results": [
                        {
                          "name": "programming",
                          "title": "Programming",
                          "subscribers": 35000000,
                          "description": "Computer Programming"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/search-users": {
      "post": {
        "operationId": "search-users",
        "tags": [
          "Search"
        ],
        "summary": "Find Reddit users by name",
        "description": "Search for Reddit users by username. Useful for account lookup and verification.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Username to search for."
                  },
                  "limit": {
                    "type": "number",
                    "description": "Max results.",
                    "example": "10"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "spez",
                    "limit": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "username": {
                            "type": "string",
                            "description": "Username."
                          },
                          "totalKarma": {
                            "type": "number",
                            "description": "Combined karma."
                          },
                          "accountAgeDays": {
                            "type": "number",
                            "description": "Account age in days."
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "results": [
                        {
                          "username": "spez",
                          "totalKarma": 1500000,
                          "accountAgeDays": 6200
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/comment-permalink": {
      "post": {
        "operationId": "comment-permalink",
        "tags": [
          "Content"
        ],
        "summary": "Single comment with parent context and replies",
        "description": "Retrieve a specific comment by its ID, including parent post context and nested replies.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "commentId": {
                    "type": "string",
                    "description": "Comment ID (t1_xxxxx) or full permalink URL."
                  },
                  "depth": {
                    "type": "number",
                    "description": "How many levels of replies to include.",
                    "example": "3"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "commentId"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "commentId": "t1_xyz123",
                    "depth": 2
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "comment": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Comment ID."
                        },
                        "author": {
                          "type": "string",
                          "description": "Author username."
                        },
                        "body": {
                          "type": "string",
                          "description": "Comment body."
                        },
                        "score": {
                          "type": "number",
                          "description": "Score."
                        },
                        "createdUtc": {
                          "type": "number",
                          "description": "Unix timestamp."
                        },
                        "replies": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": "Nested replies."
                        }
                      },
                      "additionalProperties": false
                    },
                    "post": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "Parent post title."
                        },
                        "permalink": {
                          "type": "string",
                          "description": "Parent post permalink."
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "comment": {
                        "id": "t1_xyz123",
                        "author": "user1",
                        "body": "This is a comment.",
                        "score": 100,
                        "createdUtc": 1718000000,
                        "replies": []
                      },
                      "post": {
                        "title": "Example post",
                        "permalink": "/r/test/comments/abc/example/"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/popular": {
      "post": {
        "operationId": "popular",
        "tags": [
          "Discover"
        ],
        "summary": "r/popular — trending posts across Reddit right now",
        "description": "Get the current r/popular feed. See what's trending across all of Reddit in real time.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit": {
                    "type": "number",
                    "description": "Number of posts (max 100).",
                    "example": "25"
                  }
                },
                "additionalProperties": false
              },
              "examples": {
                "default": {
                  "value": {
                    "limit": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string",
                            "description": "Post title."
                          },
                          "subreddit": {
                            "type": "string",
                            "description": "Subreddit."
                          },
                          "author": {
                            "type": "string",
                            "description": "Author."
                          },
                          "score": {
                            "type": "number",
                            "description": "Score."
                          },
                          "numComments": {
                            "type": "number",
                            "description": "Comment count."
                          },
                          "permalink": {
                            "type": "string",
                            "description": "Permalink."
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "posts": [
                        {
                          "title": "Trending post",
                          "subreddit": "popular",
                          "author": "user123",
                          "score": 10000,
                          "numComments": 2000,
                          "permalink": "/r/popular/comments/xyz/"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/leaderboard": {
      "post": {
        "operationId": "leaderboard",
        "tags": [
          "Discover"
        ],
        "summary": "Trending communities leaderboard",
        "description": "Get a leaderboard of trending communities by subscriber growth, activity, or other metrics.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit": {
                    "type": "number",
                    "description": "Number of communities.",
                    "example": "25"
                  }
                },
                "additionalProperties": false
              },
              "examples": {
                "default": {
                  "value": {
                    "limit": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "leaderboard": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rank": {
                            "type": "number",
                            "description": "Rank position."
                          },
                          "name": {
                            "type": "string",
                            "description": "Subreddit name."
                          },
                          "subscribers": {
                            "type": "number",
                            "description": "Subscriber count."
                          },
                          "growth": {
                            "type": "number",
                            "description": "Growth percentage."
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "leaderboard": [
                        {
                          "rank": 1,
                          "name": "programming",
                          "subscribers": 35000000,
                          "growth": 2.5
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/resolve-url-type": {
      "post": {
        "operationId": "resolve-url-type",
        "tags": [
          "Utility"
        ],
        "summary": "Identify what a Reddit URL points to",
        "description": "Pass any Reddit URL and get back the resource type (post, comment, subreddit, user) and its ID. Useful for routing and validation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Full Reddit URL."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "url"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "url": "https://www.reddit.com/r/programming/comments/abc123/"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "Resource type: post, comment, subreddit, user."
                    },
                    "id": {
                      "type": "string",
                      "description": "Resource ID (t3_, t1_, etc.)."
                    },
                    "slug": {
                      "type": "string",
                      "description": "URL slug."
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "type": "post",
                      "id": "t3_abc123",
                      "slug": "programming/comments/abc123"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/explore": {
      "post": {
        "operationId": "explore",
        "tags": [
          "Discover"
        ],
        "summary": "Browse communities grouped by topic",
        "description": "Explore subreddits organized by topic/category. Returns a curated list of communities across different interests.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "category": {
                    "type": "string",
                    "description": "Topic category filter."
                  },
                  "limit": {
                    "type": "number",
                    "description": "Max results.",
                    "example": "50"
                  }
                },
                "additionalProperties": false
              },
              "examples": {
                "default": {
                  "value": {
                    "category": "technology",
                    "limit": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "Category name."
                          },
                          "communities": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "description": "Subreddit name."
                                },
                                "subscribers": {
                                  "type": "number",
                                  "description": "Subscriber count."
                                }
                              },
                              "additionalProperties": false
                            }
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "categories": [
                        {
                          "name": "technology",
                          "communities": [
                            {
                              "name": "programming",
                              "subscribers": 35000000
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}