openapi: 3.2.0
info:
  title: Sylvia Subreddits API
  version: 3.0.0
  description: 'Sylvia API is a read-only Reddit data gateway serving structured JSON for posts, comments with full recursive threads, subreddits, users, search, and live comment streams. Authentication uses a single API key in the X-API-KEY header; no OAuth, no KYC.


    ## Idempotency

    All operations are HTTP GET and read-only: they do not mutate server state and are safe to retry. Repeated identical requests return identical data (modulo the live endpoints, which are inherently time-sensitive). No Idempotency-Key header is required.


    ## Stable error envelope

    Every response is wrapped in a stable envelope. On success: {"success": true, "data": {...}, "request_id": "<uuid>"}. On failure: {"success": false, "error": "<message>", "request_id": "<uuid>"} with an appropriate 4xx/5xx status code. Error responses always reference the ErrorResponse schema.


    ## Rate limiting

    Rate limits are enforced per API key with a sliding window, signalled through response headers: X-RateLimit-Tier, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After on 429. Tiers: Free (480 req/min), Strela (1,200), Svetka (2,400), Enterprise (3,600).


    ## Live streams

    The live endpoints (/comments/live and /r/{subreddit}/comments/live) return a paged poll of the newest comments. Pass the `after` cursor to advance. Each comment carries a stable, documented shape (see the onComment callback).


    ## Agent access

    The same surface is available as a Model Context Protocol (MCP) server at https://api.sylvia-api.com/mcp, and agent access semantics are declared in x-agentic-access. See https://sylvia-api.com/llms.txt.'
  contact:
    name: Sylvia API
    url: https://sylvia-api.com
    email: support@sylvia-api.com
  license:
    name: Proprietary
    url: https://sylvia-api.com/terms
  x-agentic-access:
    intent: read-only
    authenticated: true
    idempotent: true
    rateLimits:
      headers:
      - X-RateLimit-Limit
      - X-RateLimit-Remaining
      - X-RateLimit-Reset
      - Retry-After
      statusCode: 429
    mcpServer: https://api.sylvia-api.com/mcp
    llmsTxt: https://sylvia-api.com/llms.txt
servers:
- url: https://api.sylvia-api.com/v1
  description: Production API server
security:
- ApiKeyAuth: []
tags:
- name: Subreddits
paths:
  /reddit/r/{subreddit}/about:
    get:
      summary: Subreddit metadata
      description: 'Returns subreddit info: members, description, NSFW flag, icon, creation date.'
      operationId: getSubredditAbout
      parameters:
      - name: subreddit
        in: path
        required: true
        description: Subreddit name (without r/)
        schema:
          type: string
      - name: format
        in: query
        description: Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.
        schema:
          type: string
          enum:
          - reddit
          - minimal
          - ndjson
          - csv
          - markdown
          default: reddit
      responses:
        '200':
          description: Subreddit metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubredditResponse'
              example:
                success: true
                data:
                  subreddit:
                    name: Python
                    subscribers: 1400000
                request_id: 00000000-0000-0000-0000-000000000000
          headers:
            X-RateLimit-Tier:
              $ref: '#/components/headers/X-RateLimit-Tier'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Subreddits
  /reddit/r/{subreddit}/about/rules:
    get:
      summary: Subreddit rules
      description: Returns the list of rules for a subreddit.
      operationId: getSubredditRules
      parameters:
      - name: subreddit
        in: path
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.
        schema:
          type: string
          enum:
          - reddit
          - minimal
          - ndjson
          - csv
          - markdown
          default: reddit
      responses:
        '200':
          description: Subreddit rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              example:
                success: true
                data:
                  subreddit:
                    name: Python
                    subscribers: 1400000
                request_id: 00000000-0000-0000-0000-000000000000
          headers:
            X-RateLimit-Tier:
              $ref: '#/components/headers/X-RateLimit-Tier'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Subreddits
  /reddit/r/{subreddit}/{sort}:
    get:
      summary: Subreddit post listing
      description: 'Returns posts from a subreddit by sort: hot, new, top, rising, or controversial.'
      operationId: getSubredditPosts
      parameters:
      - name: subreddit
        in: path
        required: true
        schema:
          type: string
      - name: sort
        in: path
        required: true
        schema:
          type: string
          enum:
          - hot
          - new
          - top
          - rising
          - controversial
      - name: limit
        in: query
        description: Items per page (1-100, default 25)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        example: 25
      - name: after
        in: query
        description: Pagination token from previous response
        schema:
          type: string
      - name: before
        in: query
        description: Pagination token for previous page
        schema:
          type: string
      - name: t
        in: query
        description: Time filter for top sort
        schema:
          type: string
          enum:
          - hour
          - day
          - week
          - month
          - year
          - all
      - name: format
        in: query
        description: Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.
        schema:
          type: string
          enum:
          - reddit
          - minimal
          - ndjson
          - csv
          - markdown
          default: reddit
      responses:
        '200':
          description: Paginated posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingResponse'
              example:
                success: true
                data:
                  subreddit:
                    name: Python
                    subscribers: 1400000
                request_id: 00000000-0000-0000-0000-000000000000
          headers:
            X-RateLimit-Tier:
              $ref: '#/components/headers/X-RateLimit-Tier'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Subreddits
  /reddit/r/{subreddit}/sticky:
    get:
      summary: Subreddit sticky posts
      description: Returns stickied/pinned posts from a subreddit.
      operationId: getSubredditSticky
      parameters:
      - name: subreddit
        in: path
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.
        schema:
          type: string
          enum:
          - reddit
          - minimal
          - ndjson
          - csv
          - markdown
          default: reddit
      responses:
        '200':
          description: Sticky posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingResponse'
              example:
                success: true
                data:
                  subreddit:
                    name: Python
                    subscribers: 1400000
                request_id: 00000000-0000-0000-0000-000000000000
          headers:
            X-RateLimit-Tier:
              $ref: '#/components/headers/X-RateLimit-Tier'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Subreddits
  /reddit/r/{subreddit}/wiki/pages:
    get:
      summary: List subreddit wiki pages
      description: Returns the list of wiki pages for a subreddit.
      operationId: getSubredditWikiPages
      parameters:
      - name: subreddit
        in: path
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.
        schema:
          type: string
          enum:
          - reddit
          - minimal
          - ndjson
          - csv
          - markdown
          default: reddit
      responses:
        '200':
          description: Wiki page list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              example:
                success: true
                data:
                  subreddit:
                    name: Python
                    subscribers: 1400000
                request_id: 00000000-0000-0000-0000-000000000000
          headers:
            X-RateLimit-Tier:
              $ref: '#/components/headers/X-RateLimit-Tier'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Subreddits
  /reddit/r/{subreddit}/wiki/{page}:
    get:
      summary: Get subreddit wiki page
      description: Returns the content of a specific wiki page.
      operationId: getSubredditWikiPage
      parameters:
      - name: subreddit
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: path
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.
        schema:
          type: string
          enum:
          - reddit
          - minimal
          - ndjson
          - csv
          - markdown
          default: reddit
      responses:
        '200':
          description: Wiki page content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              example:
                success: true
                data:
                  subreddit:
                    name: Python
                    subscribers: 1400000
                request_id: 00000000-0000-0000-0000-000000000000
          headers:
            X-RateLimit-Tier:
              $ref: '#/components/headers/X-RateLimit-Tier'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Subreddits
components:
  headers:
    X-RateLimit-Limit:
      description: Requests per second for the tier.
      schema:
        type: integer
    Retry-After:
      description: Seconds until retry is allowed, present on 429.
      schema:
        type: integer
    X-RateLimit-Tier:
      description: 'Rate limit tier: free | strela | svetka | enterprise.'
      schema:
        type: string
    X-RateLimit-Reset:
      description: Epoch milliseconds when the window resets.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Remaining requests in the current window.
      schema:
        type: integer
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ListingResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/ListingData'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
        message:
          type: string
        status:
          type: integer
        code:
          type: string
        request_id:
          type: string
    SubredditResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Subreddit'
    ListingData:
      type: object
      properties:
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        after:
          type:
          - string
          - 'null'
    Subreddit:
      type: object
      properties:
        name:
          type: string
        members:
          type: integer
        description:
          type: string
        is_private:
          type: boolean
        over18:
          type: boolean
        icon_img:
          type:
          - string
          - 'null'
        created_utc:
          type: integer
          format: int64
    GenericResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            type: object
    Envelope:
      type: object
      properties:
        success:
          type: boolean
        message:
          type:
          - string
          - 'null'
        error:
          type:
          - string
          - 'null'
        request_id:
          type: string
    Post:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        selftext:
          type: string
        author:
          type: string
        subreddit:
          type: string
        score:
          type: integer
        upvote_ratio:
          type: number
        num_comments:
          type: integer
        created_utc:
          type: integer
          format: int64
        permalink:
          type: string
        url:
          type: string
        is_self:
          type: boolean
        over_18:
          type: boolean
        stickied:
          type: boolean
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication. Get yours at https://sylvia-api.com
    AccountTokenAuth:
      type: apiKey
      in: header
      name: x-sylvia-auth
      description: Account token (SV_...) for account management endpoints. Sign in at https://sylvia-api.com to get yours.