> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/MatthewSabia1/Joip-Web-App-2/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Reddit Posts

> Search Reddit posts by keyword across all subreddits

## Overview

This endpoint searches Reddit for posts matching a keyword query. It searches across all subreddits and returns posts with media content, perfect for finding specific types of content without knowing which subreddit to search.

## Rate Limiting

This endpoint is protected by Reddit API rate limiting. The service handles rate limits with exponential backoff and retries.

## Request Body

<ParamField body="query" type="string" required>
  Search query string (1-200 characters)

  Examples:

  * `"sunset photography"`
  * `"cute cats"`
  * `"nsfw joi"`
</ParamField>

<ParamField body="limit" type="number" default="25">
  Maximum number of posts to return (1-100)
</ParamField>

<ParamField body="excludeUrls" type="string[]" default="[]">
  Array of media URLs to exclude from results. Useful for pagination and avoiding duplicates.

  URLs are normalized before comparison.
</ParamField>

## Response

Returns an array of Reddit posts matching the search query. The response structure is identical to the [Fetch Reddit Posts](/api/reddit/fetch) endpoint.

<ResponseField name="[].id" type="string">
  Reddit post ID
</ResponseField>

<ResponseField name="[].title" type="string">
  Post title
</ResponseField>

<ResponseField name="[].author" type="string">
  Reddit username of the post author
</ResponseField>

<ResponseField name="[].subreddit" type="string">
  Subreddit where the post was found
</ResponseField>

<ResponseField name="[].url" type="string">
  Reddit post URL
</ResponseField>

<ResponseField name="[].media_url" type="string">
  Direct URL to the media content
</ResponseField>

<ResponseField name="[].thumbnail" type="string | null">
  Thumbnail image URL
</ResponseField>

<ResponseField name="[].score" type="number">
  Post score (upvotes minus downvotes)
</ResponseField>

<ResponseField name="[].num_comments" type="number">
  Number of comments
</ResponseField>

<ResponseField name="[].created_utc" type="number">
  Unix timestamp of post creation
</ResponseField>

<ResponseField name="[].is_video" type="boolean">
  Whether the post contains video content
</ResponseField>

<ResponseField name="[].nsfw" type="boolean">
  Whether the post is marked as NSFW
</ResponseField>

<ResponseField name="[].spoiler" type="boolean">
  Whether the post is marked as a spoiler
</ResponseField>

## Examples

### Basic Search

```bash theme={null}
curl -X POST "https://app.joip.io/api/reddit-search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cute cats",
    "limit": 25
  }'
```

### Search with More Results

```bash theme={null}
curl -X POST "https://app.joip.io/api/reddit-search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "sunset photography",
    "limit": 50
  }'
```

### Search with URL Exclusion

```bash theme={null}
curl -X POST "https://app.joip.io/api/reddit-search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "nature",
    "limit": 25,
    "excludeUrls": [
      "https://i.redd.it/abc123.jpg",
      "https://i.imgur.com/xyz789.png"
    ]
  }'
```

## Response Example

```json theme={null}
[
  {
    "id": "abc123",
    "title": "Beautiful sunset over the ocean",
    "author": "photographer123",
    "subreddit": "earthporn",
    "url": "https://reddit.com/r/earthporn/comments/abc123",
    "media_url": "https://i.redd.it/abc123xyz.jpg",
    "thumbnail": "https://b.thumbs.redditmedia.com/abc.jpg",
    "score": 5432,
    "num_comments": 234,
    "created_utc": 1709280000,
    "is_video": false,
    "nsfw": false,
    "spoiler": false
  },
  {
    "id": "def456",
    "title": "Golden hour photography",
    "author": "sunsetlover",
    "subreddit": "photography",
    "url": "https://reddit.com/r/photography/comments/def456",
    "media_url": "https://i.imgur.com/def456.png",
    "thumbnail": "https://i.imgur.com/def456s.png",
    "score": 3210,
    "num_comments": 145,
    "created_utc": 1709283600,
    "is_video": false,
    "nsfw": false,
    "spoiler": false
  }
]
```

## Error Responses

### Invalid Query

**Status**: `400 Bad Request`

```json theme={null}
{
  "message": "Validation error: String must contain at least 1 character(s) at query"
}
```

### Query Too Long

**Status**: `400 Bad Request`

```json theme={null}
{
  "message": "Validation error: String must contain at most 200 character(s) at query"
}
```

### Reddit Service Not Configured

**Status**: `503 Service Unavailable`

```json theme={null}
{
  "message": "Content integration is not configured. Please contact support.",
  "error": "MISSING_CREDENTIALS"
}
```

### Search Error

**Status**: `500 Internal Server Error`

```json theme={null}
{
  "message": "Failed to search Reddit"
}
```

## Search Behavior

* Searches across **all subreddits** (not limited to specific communities)
* Returns posts sorted by **relevance** to the search query
* Automatically filters for posts with media URLs
* Excludes duplicate media URLs within results
* Uses Reddit's search API with appropriate rate limiting

## Use Cases

* **Content Discovery**: Find specific types of content without knowing subreddit names
* **Keyword-Based Sessions**: Create sessions based on topics rather than subreddits
* **Media Exploration**: Browse media matching specific themes or keywords
* **Cross-Community Search**: Find content across multiple related subreddits

## Notes

* Search queries are limited to 200 characters
* Results are filtered to only include posts with media URLs
* The endpoint uses the centralized Reddit service for API calls
* Rate limiting is handled automatically with retries
* This endpoint does not require authentication
* Search results may include NSFW content depending on the query