openapi: 3.2.0
info:
  title: Sylvia Users 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: Users
paths:
  /reddit/u/{username}/about:
    get:
      summary: User profile metadata
      description: 'Returns user profile info: name, karma, account age, avatar, and more.'
      operationId: getUserAbout
      parameters:
      - name: username
        in: path
        required: true
        description: Username (without u/)
        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: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
              example:
                success: true
                data:
                  user:
                    name: spez
                    karma: 8000000
                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:
      - Users
  /reddit/u/{username}/{where}:
    get:
      summary: User content
      description: Returns a user's submitted posts, comments, or combined overview.
      operationId: getUserContent
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: where
        in: path
        required: true
        schema:
          type: string
          enum:
          - submitted
          - comments
          - overview
      - 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: 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 content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingResponse'
              example:
                success: true
                data:
                  user:
                    name: spez
                    karma: 8000000
                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:
      - Users
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'
    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
    ListingData:
      type: object
      properties:
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        after:
          type:
          - string
          - 'null'
    User:
      type: object
      properties:
        name:
          type: string
        created_utc:
          type: integer
          format: int64
        link_karma:
          type: integer
        comment_karma:
          type: integer
        icon_img:
          type:
          - string
          - 'null'
    Envelope:
      type: object
      properties:
        success:
          type: boolean
        message:
          type:
          - string
          - 'null'
        error:
          type:
          - string
          - 'null'
        request_id:
          type: string
    UserResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/User'
    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.