openapi: 3.0.3
info:
  title: TwitterShots Tweet Screenshot API
  description: |
    Generate high-quality Twitter/X tweet screenshots via REST.
    No Twitter/X developer API key required — authenticate with a TwitterShots API key only.
  version: 0.9.1
  contact:
    name: TwitterShots
    url: https://twittershots.com
    email: support@twittershots.com
  license:
    name: Proprietary
servers:
  - url: https://api.twittershots.com
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/screenshot/{tweetId}:
    get:
      operationId: getTweetScreenshot
      summary: Generate a tweet screenshot
      description: |
        Returns a rendered screenshot of a public tweet as PNG, SVG, or HTML.
        Quota remaining is returned in X-Quota-Remaining and X-Quota-Limit response headers.
      parameters:
        - name: tweetId
          in: path
          required: true
          description: Tweet status ID (numeric) or full tweet URL
          schema:
            type: string
          example: "1981415642981888505"
        - name: format
          in: query
          required: false
          description: Output format
          schema:
            type: string
            enum: [svg, png, html]
            default: svg
        - name: theme
          in: query
          required: false
          description: Color theme
          schema:
            type: string
            enum: [light, dark]
            default: light
        - name: returnType
          in: query
          required: false
          description: buffer returns image bytes; url returns JSON with a hosted image URL
          schema:
            type: string
            enum: [buffer, url]
            default: buffer
      responses:
        "200":
          description: Screenshot image (buffer) or JSON with url when returnType=url
          headers:
            X-Quota-Remaining:
              description: Remaining API credits in the current period
              schema:
                type: integer
            X-Quota-Limit:
              description: Total API credits for the current period
              schema:
                type: integer
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
                format: binary
            text/html:
              schema:
                type: string
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                  format:
                    type: string
                  tweetId:
                    type: string
        "401":
          description: Missing or invalid X-API-KEY
        "403":
          description: Quota exceeded or plan restriction
        "404":
          description: Tweet not found or unavailable
  /api/v1/usage:
    get:
      operationId: getApiUsage
      summary: Check remaining API quota
      responses:
        "200":
          description: Usage for the authenticated key
          content:
            application/json:
              schema:
                type: object
                properties:
                  remaining:
                    type: integer
                  limit:
                    type: integer
        "401":
          description: Missing or invalid X-API-KEY
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key from https://twittershots.com/settings/keys