openapi: 3.1.0
info:
  title: RubyGems Activity Versions API
  description: The RubyGems Activity API provides endpoints that return the most recently added and most recently updated gems on RubyGems.org. The latest endpoint returns the 50 gems most recently published to the registry, while the just-updated endpoint returns the 50 most recently modified gems. These endpoints are useful for building activity feeds, monitoring new releases, and tracking changes across the Ruby ecosystem.
  version: '1.0'
  contact:
    name: RubyGems.org Support
    url: https://help.rubygems.org
  termsOfService: https://rubygems.org/pages/about
servers:
- url: https://rubygems.org/api/v1
  description: Production Server
tags:
- name: Versions
  description: Endpoints for querying detailed version information for specific gem versions, including metadata, dependencies, checksums, and platform-specific builds.
paths:
  /rubygems/{gemName}/versions/{versionNumber}.json:
    get:
      operationId: getGemVersionDetails
      summary: Get Gem Version Details
      description: Returns detailed information about a specific gem version, including name, version number, download counts, platform, authors, description, dependencies, URIs, timestamps, checksums, and metadata. Optionally filter by platform using the platform query parameter.
      tags:
      - Versions
      security: []
      parameters:
      - name: gemName
        in: path
        description: The name of the gem
        required: true
        schema:
          type: string
        example: coulda
      - name: versionNumber
        in: path
        description: The version number of the gem
        required: true
        schema:
          type: string
        example: 0.7.1
      - name: platform
        in: query
        description: Filter by platform. Common values include ruby, java, and x86_64-linux. If not specified, defaults to the ruby platform.
        required: false
        schema:
          type: string
        example: ruby
      responses:
        '200':
          description: Successful response with version details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GemVersionDetail'
        '404':
          description: Gem or version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /versions/{gemName}.json:
    get:
      operationId: getGemVersions
      summary: List Gem Versions
      description: Returns an array of version objects for a specific gem, including version numbers, platforms, authors, descriptions, checksums, and metadata for each published version.
      tags:
      - Versions
      security: []
      parameters:
      - $ref: '#/components/parameters/gemName'
      responses:
        '200':
          description: Successful response with array of version objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GemVersion'
        '404':
          description: Gem not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /versions/{gemName}/latest.json:
    get:
      operationId: getLatestGemVersion
      summary: Get Latest Gem Version
      description: Returns an object containing the latest version number for the specified gem.
      tags:
      - Versions
      security: []
      parameters:
      - $ref: '#/components/parameters/gemName'
      responses:
        '200':
          description: Successful response with latest version
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    description: The latest version number
                    example: 3.5.0
        '404':
          description: Gem not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /timeframe_versions.json:
    get:
      operationId: getTimeframeVersions
      summary: Get Versions Within A Timeframe
      description: Returns an array of gem versions created within a specified timeframe. The from parameter is required and must be an ISO 8601 timestamp. The time span cannot exceed 7 days. Results are paginated with 30 versions per page.
      tags:
      - Versions
      security: []
      parameters:
      - name: from
        in: query
        description: Start of the timeframe in ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Required.
        required: true
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: End of the timeframe in ISO 8601 format. Defaults to current time if not specified.
        required: false
        schema:
          type: string
          format: date-time
      - name: page
        in: query
        description: Page number for paginated results
        required: false
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: Successful response with array of gem versions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GemVersion'
components:
  schemas:
    GemVersionDetail:
      type: object
      description: Detailed information about a specific gem version
      properties:
        name:
          type: string
          description: The name of the gem
        downloads:
          type: integer
          description: Total downloads across all versions
        version:
          type: string
          description: The version number
        version_created_at:
          type: string
          format: date-time
          description: Timestamp when this version was created
        version_downloads:
          type: integer
          description: Download count for this specific version
        platform:
          type: string
          description: The platform for this version
        authors:
          type: string
          description: Comma-separated list of authors
        info:
          type: string
          description: Short description of the gem
        licenses:
          type: array
          items:
            type: string
          description: List of licenses
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Additional metadata key-value pairs
        yanked:
          type: boolean
          description: Whether this version has been yanked
        sha:
          type: string
          description: SHA-256 checksum of the gem file
        spec_sha:
          type: string
          description: SHA-256 checksum of the gemspec
        project_uri:
          type: string
          format: uri
          description: URI to the gem project page
        gem_uri:
          type: string
          format: uri
          description: URI to download the gem file
        homepage_uri:
          type: string
          format: uri
          description: URI to the gem homepage
        wiki_uri:
          type: string
          format: uri
          description: URI to the gem wiki
        documentation_uri:
          type: string
          format: uri
          description: URI to the gem documentation
        mailing_list_uri:
          type: string
          format: uri
          description: URI to the gem mailing list
        source_code_uri:
          type: string
          format: uri
          description: URI to the gem source code
        bug_tracker_uri:
          type: string
          format: uri
          description: URI to the gem bug tracker
        changelog_uri:
          type: string
          format: uri
          description: URI to the gem changelog
        funding_uri:
          type: string
          format: uri
          description: URI to the gem funding page
        dependencies:
          type: object
          properties:
            development:
              type: array
              items:
                $ref: '#/components/schemas/Dependency'
              description: Development dependencies
            runtime:
              type: array
              items:
                $ref: '#/components/schemas/Dependency'
              description: Runtime dependencies
          description: Gem dependency information
        built_at:
          type: string
          format: date-time
          description: Timestamp when the gem was built
        created_at:
          type: string
          format: date-time
          description: Timestamp when the version was published
        description:
          type: string
          description: Full description of the gem
        downloads_count:
          type: integer
          description: Download count for this version
        number:
          type: string
          description: The version number
        summary:
          type: string
          description: Short summary of the gem
        rubygems_version:
          type: string
          description: Minimum RubyGems version required
        ruby_version:
          type: string
          description: Minimum Ruby version required
        prerelease:
          type: boolean
          description: Whether this is a prerelease version
        requirements:
          type: array
          items:
            type: string
          description: Requirements for this version
    Dependency:
      type: object
      description: A gem dependency
      properties:
        name:
          type: string
          description: Name of the dependency gem
        requirements:
          type: string
          description: Version requirements string
    GemVersion:
      type: object
      description: A specific version of a Ruby gem
      properties:
        authors:
          type: string
          description: Comma-separated list of version authors
        built_at:
          type: string
          format: date-time
          description: Timestamp when the version was built
        created_at:
          type: string
          format: date-time
          description: Timestamp when the version was published
        description:
          type: string
          description: Full description of the gem version
        downloads_count:
          type: integer
          description: Number of downloads for this version
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Additional metadata for this version
        number:
          type: string
          description: The version number
        summary:
          type: string
          description: Short summary of the gem version
        platform:
          type: string
          description: The platform for this version
        rubygems_version:
          type: string
          description: The minimum RubyGems version required
        ruby_version:
          type: string
          description: The minimum Ruby version required
        prerelease:
          type: boolean
          description: Whether this is a prerelease version
        licenses:
          type: array
          items:
            type: string
          description: Licenses for this version
        requirements:
          type: array
          items:
            type: string
          description: Requirements for this version
        sha:
          type: string
          description: SHA-256 checksum of the gem file
    Error:
      type: object
      description: Error response from the RubyGems.org API
      properties:
        error:
          type: string
          description: Error message
  parameters:
    gemName:
      name: gemName
      in: path
      description: The name of the gem
      required: true
      schema:
        type: string
      example: rails
externalDocs:
  description: RubyGems.org API Documentation
  url: https://guides.rubygems.org/rubygems-org-api/