openapi: 3.2.0
info:
  title: Sylvia Posts & Comments API
  version: 3.0.0
  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
  description: 'Operations tagged Posts & Comments across 2 of this provider''s published API definitions: sylvia-api-openapi-2026-08-18.json, sylvia-api-openapi-2026-08-20.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.sylvia-api.com/v1
  description: Production API server
security:
- ApiKeyAuth: []
tags:
- name: Posts & Comments
paths:
  /reddit/submission:
    get:
      summary: Fetch post by URL
      description: Returns a single post given its full Reddit URL.
      operationId: getSubmissionByUrl
      parameters:
      - name: url
        in: query
        required: true
        description: Full Reddit post URL
        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: Post object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
              example:
                success: true
                data:
                  posts:
                  - id: 1abc
                    title: Example post
                  after: t3_1abc
                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:
      - Posts & Comments
    servers:
    - url: https://api.sylvia-api.com/v1
      description: Production API server
  /reddit/comment:
    get:
      summary: Fetch comment by URL
      description: Returns a single comment given its full Reddit permalink URL.
      operationId: getCommentByUrl
      parameters:
      - name: url
        in: query
        required: true
        description: Full Reddit comment permalink URL
        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: Comment object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
              example:
                success: true
                data:
                  posts:
                  - id: 1abc
                    title: Example post
                  after: t3_1abc
                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:
      - Posts & Comments
    servers:
    - url: https://api.sylvia-api.com/v1
      description: Production API server
  /reddit/submission/{post_id}/full:
    get:
      summary: Fully resolved thread
      description: Returns the post listing plus all comments with recursive expansion of 'more' stubs (depth-limited).
      operationId: getFullThread
      parameters:
      - name: post_id
        in: path
        required: true
        description: Reddit post ID (e.g. 'abc123' from t3_abc123)
        schema:
          type: string
      - name: sort
        in: query
        description: Comment sort order
        schema:
          type: string
          enum:
          - confidence
          - top
          - new
          - controversial
          - old
          - qa
          default: confidence
      - 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: Resolved thread [post_listing, comment_listing]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadResponse'
              example:
                success: true
                data:
                  posts:
                  - id: 1abc
                    title: Example post
                  after: t3_1abc
                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:
      - Posts & Comments
    servers:
    - url: https://api.sylvia-api.com/v1
      description: Production API server
  /reddit/duplicates/{submission_id}:
    get:
      summary: Crosspost duplicates
      description: Returns crosspost duplicates of a submission.
      operationId: getDuplicates
      parameters:
      - name: submission_id
        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: 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: Duplicate submissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingResponse'
              example:
                success: true
                data:
                  posts:
                  - id: 1abc
                    title: Example post
                  after: t3_1abc
                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:
      - Posts & Comments
    servers:
    - url: https://api.sylvia-api.com/v1
      description: Production API server
  /reddit/morechildren:
    get:
      summary: Load more comments
      description: Expands truncated 'more' comment stubs in a thread.
      operationId: getMoreChildren
      parameters:
      - name: link_id
        in: query
        required: true
        description: Thread fullname (e.g. t3_abc123)
        schema:
          type: string
      - name: children
        in: query
        required: true
        description: Comma-separated comment IDs to expand
        schema:
          type: string
      - name: sort
        in: query
        description: Comment sort order
        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: Resolved comments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              example:
                success: true
                data:
                  posts:
                  - id: 1abc
                    title: Example post
                  after: t3_1abc
                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'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Posts & Comments
    servers:
    - url: https://api.sylvia-api.com/v1
      description: Production API server
  /reddit/by_id:
    get:
      summary: Fetch by fullname IDs
      description: Bulk fetch posts, comments, or subreddits by their fullnames.
      operationId: getByIds
      parameters:
      - name: names
        in: query
        required: true
        description: Comma-separated fullnames (e.g. t3_abc,t3_def), max 100
        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: Requested objects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              example:
                success: true
                data:
                  posts:
                  - id: 1abc
                    title: Example post
                  after: t3_1abc
                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'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Posts & Comments
    servers:
    - url: https://api.sylvia-api.com/v1
      description: Production API server
components:
  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:
    GenericResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            type: object
    ListingResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/ListingData'
    ListingData:
      type: object
      properties:
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        after:
          type:
          - string
          - 'null'
    PostResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Post'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
        message:
          type: string
        status:
          type: integer
        code:
          type: string
        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
    CommentResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Comment'
    ThreadResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            type: array
            description: Reddit thread format [post_listing, comment_listing]
            items:
              type: object
    Envelope:
      type: object
      properties:
        success:
          type: boolean
        message:
          type:
          - string
          - 'null'
        error:
          type:
          - string
          - 'null'
        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
    ErrorResponse_2:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
        message:
          type: string
        status:
          type: integer
        code:
          type: string
          enum:
          - BAD_REQUEST
          - UNAUTHORIZED
          - FORBIDDEN
          - NOT_FOUND
          - LOW_BALANCE
          - RATE_LIMITED
          - FEATURE_LOCKED
          - TIER_EXPIRED
          - REQUEST_FAILED
        request_id:
          type: string
  headers:
    X-RateLimit-Remaining:
      description: Remaining requests in the current window.
      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
    Retry-After:
      description: Seconds until retry is allowed, present on 429.
      schema:
        type: integer
    X-RateLimit-Limit:
      description: Requests per second for the tier.
      schema:
        type: integer
  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.
x-refined-from:
- sylvia-api-openapi-2026-08-18.json
- sylvia-api-openapi-2026-08-20.json