openapi: 3.2.0
info:
  title: Sylvia Live 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: Live
paths:
  /reddit/r/{subreddit}/comments/live:
    get:
      summary: Subreddit live comment stream
      description: Real-time comment stream for a subreddit. Billed at the Live Stream tier.
      operationId: getSubredditLiveComments
      parameters:
      - name: subreddit
        in: path
        required: true
        schema:
          type: string
      - 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: 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: Live comment stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              example:
                success: true
                data:
                  comments:
                  - id: 1abc
                    body: Example comment
                    subreddit: all
                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'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Live
      callbacks:
        onComment:
          '{$request.body#/callbackUrl}':
            post:
              summary: Live comment stream event (typed event surface)
              description: 'When polling /comments/live or /r/{subreddit}/comments/live, each new comment is returned in the data.comments array with a stable shape: id, body, author, subreddit, created_utc, permalink, score.'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/Comment'
                    example:
                      id: 1abc
                      body: Example comment
                      author: user
                      subreddit: all
                      created_utc: 1754132400
                      score: 5
              responses:
                '200':
                  description: Acknowledged
  /reddit/comments/live:
    get:
      summary: Global live comment firehose
      description: Real-time comment stream from across all of Reddit. Billed at the Live Stream tier.
      operationId: getGlobalLiveComments
      parameters:
      - 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: 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: Live comment stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              example:
                success: true
                data:
                  comments:
                  - id: 1abc
                    body: Example comment
                    subreddit: all
                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'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Live
      callbacks:
        onComment:
          '{$request.body#/callbackUrl}':
            post:
              summary: Live comment stream event (typed event surface)
              description: 'When polling /comments/live or /r/{subreddit}/comments/live, each new comment is returned in the data.comments array with a stable shape: id, body, author, subreddit, created_utc, permalink, score.'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/Comment'
                    example:
                      id: 1abc
                      body: Example comment
                      author: user
                      subreddit: all
                      created_utc: 1754132400
                      score: 5
              responses:
                '200':
                  description: Acknowledged
components:
  responses:
    Forbidden:
      description: Forbidden — insufficient access or credits
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
  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
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
        message:
          type: string
        status:
          type: integer
        code:
          type: string
        request_id:
          type: string
    Comment:
      type: object
      properties:
        id:
          type: string
        body:
          type: string
        author:
          type: string
        subreddit:
          type: string
        score:
          type: integer
        created_utc:
          type: integer
          format: int64
        permalink:
          type: string
        parent_id:
          type: string
        link_id:
          type: string
        submission_id:
          type: string
        depth:
          type: integer
    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
  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.