threadsnoop-com Subreddits API

openapi: 3.2.0
info:
  title: ThreadSnoop Reddit Read Subreddits API
  version: 1.0.0
  description: 'Read-only access to Reddit: posts, comments, comment trees, subreddit search, subreddit rules, and user profiles. Pay-as-you-go, 1 credit = 1 request, 100 free Reddit searches on signup. No writes, votes, DMs, or auth-ed Reddit actions — read-only, permanently. See https://threadsnoop.com/docs for the human-readable guide.'
  contact:
    email: hello@threadsnoop.com
servers:
- url: https://api.threadsnoop.com
security:
- ApiKeyHeader: []
- BearerAuth: []
tags:
- name: Subreddits
paths:
  /v1/subreddits/search:
    get:
      operationId: searchSubreddits
      summary: Search subreddits by name
      description: Name-prefix search over subreddit metadata (subscriber count, description). Returns up to 10 matches; there is no customer-facing `limit` param and no pagination (cursor/has_more are always null/false).
      parameters:
      - name: q
        in: query
        required: true
        description: Subreddit name or name prefix to search for.
        schema:
          type: string
          example: saas
      responses:
        '200':
          description: Up to 10 matching subreddits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubredditSearchEnvelope'
              example:
                data:
                - name: SaaS
                  subscribers: 180000
                  description: A place for SaaS founders...
                _threadsnoop:
                  cursor: null
                  has_more: false
                  credits_used: 1
                  credits_remaining: 329
          headers:
            x-credits-used:
              $ref: '#/components/headers/CreditsUsed'
            x-credits-remaining:
              $ref: '#/components/headers/CreditsRemaining'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
      tags:
      - Subreddits
  /v1/subreddits/{name}/rules:
    get:
      operationId: getSubredditRules
      summary: Get a subreddit's rules
      parameters:
      - name: name
        in: path
        required: true
        description: Subreddit name, 3-21 characters, letters/digits/underscore only.
        schema:
          type: string
          pattern: ^[A-Za-z0-9_]{3,21}$
          example: SaaS
      responses:
        '200':
          description: The subreddit's rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubredditRulesEnvelope'
              example:
                data:
                  subreddit: SaaS
                  rules:
                  - short_name: No self-promotion
                    description: Do not post ads or referral links.
                    priority: 0
                _threadsnoop:
                  credits_used: 1
                  credits_remaining: 328
          headers:
            x-credits-used:
              $ref: '#/components/headers/CreditsUsed'
            x-credits-remaining:
              $ref: '#/components/headers/CreditsRemaining'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
      tags:
      - Subreddits
components:
  schemas:
    SubredditSearchEnvelope:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SubredditMeta'
        _threadsnoop:
          $ref: '#/components/schemas/Envelope'
    Envelope:
      type: object
      properties:
        cursor:
          type:
          - integer
          - 'null'
          description: created_utc of the last row in this page (raw page, pre-filter if q= was used). Pass as `after` (sort=asc) or `before` (sort=desc) to fetch the next page. Null when the page was empty or the endpoint isn't paginated.
        has_more:
          type: boolean
        credits_used:
          type: integer
        credits_remaining:
          type: integer
      required:
      - credits_used
      - credits_remaining
    SubredditRulesEnvelope:
      type: object
      properties:
        data:
          type: object
          properties:
            subreddit:
              type: string
            rules:
              type: array
              items:
                $ref: '#/components/schemas/SubredditRule'
        _threadsnoop:
          $ref: '#/components/schemas/Envelope'
    SubredditMeta:
      type: object
      properties:
        name:
          type: string
        subscribers:
          type: integer
        description:
          type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    SubredditRule:
      type: object
      properties:
        short_name:
          type: string
        description:
          type: string
        priority:
          type: integer
  responses:
    PaymentRequired:
      description: Insufficient credit balance. Not charged (the debit is the balance check — it never went through).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: insufficient credits — top up at https://threadsnoop.com/api
    UpstreamUnavailable:
      description: The upstream data source was unreachable or errored after the connector's retry policy was exhausted. Any credit debited for this request is automatically refunded. When the upstream is busy, a Retry-After header gives the number of seconds to wait before retrying.
      headers:
        Retry-After:
          description: Seconds to wait before retrying. Present when the upstream reported it was busy.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: upstream temporarily unavailable — credit refunded
    Unauthorized:
      description: Missing, invalid, or revoked API key. Not charged (no key to attribute usage to).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid or revoked api key
    BadRequest:
      description: Invalid or missing parameters. Not charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: at least one of subreddit, author, or ids is required
    RateLimited:
      description: 'Rate limit exceeded — either your key''s own 2 req/s (burst 10) limit, or the shared global upstream ceiling (marked by the `x-ratelimit-scope: global` header, present only for the global case). Not charged.'
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        x-ratelimit-scope:
          description: Present and set to `global` only when the shared upstream ceiling (not your per-key limit) was hit.
          schema:
            type: string
            enum:
            - global
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate limit exceeded
  headers:
    CreditsRemaining:
      description: Balance remaining after this request.
      schema:
        type: integer
    CreditsUsed:
      description: Credits charged for this request (0 or 1).
      schema:
        type: integer
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <your key>. Equivalent to x-api-key; either header works.'