api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "page": {
          "description": "Pagination information for the current response.",
          "properties": {
            "hasMore": {
              "description": "Whether another page of results is available.",
              "type": "boolean"
            },
            "nextCursor": {
              "description": "Cursor to pass in the next request when another page exists.",
              "nullable": true,
              "type": "string"
            }
          },
          "required": [
            "nextCursor",
            "hasMore"
          ],
          "type": "object"
        },
        "posts": {
          "description": "Matching posts for the search.",
          "items": {
            "description": "A post returned from a subreddit search.",
            "properties": {
              "createdAt": {
                "description": "ISO-8601 publish timestamp when available.",
                "nullable": true,
                "type": "string"
              },
              "crosspost": {
                "description": "Whether the post is a crosspost.",
                "type": "boolean"
              },
              "id": {
                "description": "Stable post identifier.",
                "minLength": 1,
                "type": "string"
              },
              "metrics": {
                "description": "Engagement metrics for this post.",
                "properties": {
                  "comments": {
                    "description": "Comment count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "votes": {
                    "description": "Vote count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "required": [
                  "votes",
                  "comments"
                ],
                "type": "object"
              },
              "nsfw": {
                "description": "Whether the post is marked as adult content.",
                "type": "boolean"
              },
              "permalink": {
                "description": "Permalink path or URL for this post.",
                "minLength": 1,
                "type": "string"
              },
              "position": {
                "description": "Position of this row in the current result page.",
                "minimum": 0,
                "nullable": true,
                "type": "integer"
              },
              "postId": {
                "description": "Post identifier when available.",
                "minLength": 1,
                "type": "string"
              },
              "relativePosition": {
                "description": "Relative position of this row in the current result page.",
                "minimum": 0,
                "nullable": true,
                "type": "integer"
              },
              "spoiler": {
                "description": "Whether the post is marked as a spoiler.",
                "type": "boolean"
              },
              "subreddit": {
                "description": "Subreddit metadata when available.",
                "nullable": true,
                "properties": {
                  "bannerUrl": {
                    "description": "Subreddit banner URL when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "description": {
                    "description": "Subreddit description when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "iconUrl": {
                    "description": "Subreddit icon URL when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "id": {
                    "description": "Subreddit identifier when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "name": {
                    "description": "Subreddit name when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "nsfw": {
                    "description": "Whether the subreddit is marked as adult content.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "quarantined": {
                    "description": "Whether the subreddit is quarantined.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "weeklyContributions": {
                    "description": "Approximate weekly contributions when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "weeklyVisitors": {
                    "description": "Approximate weekly visitors when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "nsfw",
                  "quarantined",
                  "iconUrl",
                  "bannerUrl",
                  "description",
                  "weeklyVisitors",
                  "weeklyContributions"
                ],
                "type": "object"
              },
              "thumbnailBlurred": {
                "description": "Whether the thumbnail is blurred.",
                "nullable": true,
                "type": "boolean"
              },
              "thumbnailUrl": {
                "description": "Thumbnail image URL when available.",
                "nullable": true,
                "type": "string"
              },
              "title": {
                "description": "Post title.",
                "minLength": 1,
                "type": "string"
              },
              "url": {
                "description": "Canonical public URL for this post.",
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "id",
              "postId",
              "title",
              "url",
              "permalink",
              "nsfw",
              "spoiler",
              "crosspost",
              "subreddit",
              "metrics",
              "createdAt",
              "thumbnailUrl",
              "thumbnailBlurred",
              "position",
              "relativePosition"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "query": {
          "description": "Search query evaluated for this response.",
          "nullable": true,
          "type": "string"
        },
        "sort": {
          "description": "Sort order applied for this response.",
          "enum": [
            "relevance",
            "hot",
            "top",
            "new",
            "comments"
          ],
          "type": "string"
        },
        "subreddit": {
          "description": "Subreddit name evaluated for this response.",
          "type": "string"
        },
        "timeframe": {
          "description": "Time range filter applied for this response.",
          "enum": [
            "all",
            "year",
            "month",
            "week",
            "day",
            "hour"
          ],
          "type": "string"
        },
        "totalResults": {
          "description": "Number of post rows returned in this response.",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "subreddit",
        "query",
        "sort",
        "timeframe",
        "posts",
        "totalResults",
        "page"
      ],
      "type": "object"
    },
    "meta": {
      "description": "Metadata describing the request and billing outcome.",
      "properties": {
        "cached": {
          "description": "True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.",
          "type": "boolean"
        },
        "creditsCharged": {
          "description": "Credits charged for this request.",
          "minimum": 0,
          "type": "integer"
        },
        "requestId": {
          "description": "Unique request identifier for tracing this API call.",
          "minLength": 1,
          "type": "string"
        },
        "version": {
          "description": "Public API version that served the response.",
          "enum": [
            "v1"
          ],
          "type": "string"
        }
      },
      "required": [
        "requestId",
        "creditsCharged",
        "version"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "meta"
  ],
  "type": "object"
}