openapi: 3.1.0
info:
  title: RubyGems Activity Owners 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: Owners
  description: Endpoints for managing gem ownership, including listing owners, adding and removing owners, and listing gems by owner.
paths:
  /owners/{userHandle}/gems.json:
    get:
      operationId: listGemsByOwner
      summary: List Gems By Owner
      description: Returns an array of gem objects owned by the specified user, identified by their handle or user ID.
      tags:
      - Owners
      security: []
      parameters:
      - $ref: '#/components/parameters/userHandle'
      responses:
        '200':
          description: Successful response with array of gems
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Gem'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /gems/{gemName}/owners.json:
    get:
      operationId: listGemOwners
      summary: List Owners Of A Gem
      description: Returns an array of owner objects for the specified gem, including their email addresses.
      tags:
      - Owners
      security: []
      parameters:
      - $ref: '#/components/parameters/gemName'
      responses:
        '200':
          description: Successful response with array of owners
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Owner'
        '404':
          description: Gem not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /gems/{gemName}/owners:
    post:
      operationId: addGemOwner
      summary: Add A Gem Owner
      description: Add a new owner to the specified gem. The new owner is identified by their email address and can be assigned a role.
      tags:
      - Owners
      parameters:
      - $ref: '#/components/parameters/gemName'
      - name: OTP
        in: header
        description: One-time passcode for multi-factor authentication if enabled.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address of the user to add as owner
                role:
                  type: string
                  description: Role to assign to the new owner
      responses:
        '200':
          description: Owner added successfully
          content:
            text/plain:
              schema:
                type: string
                example: Owner added successfully.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Gem or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: removeGemOwner
      summary: Remove A Gem Owner
      description: Remove an owner from the specified gem. The owner is identified by their email address.
      tags:
      - Owners
      parameters:
      - $ref: '#/components/parameters/gemName'
      - name: OTP
        in: header
        description: One-time passcode for multi-factor authentication if enabled.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address of the owner to remove
      responses:
        '200':
          description: Owner removed successfully
          content:
            text/plain:
              schema:
                type: string
                example: Owner removed successfully.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Gem or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: updateGemOwner
      summary: Update A Gem Owner
      description: Update the role of an existing owner on the specified gem.
      tags:
      - Owners
      parameters:
      - $ref: '#/components/parameters/gemName'
      - name: OTP
        in: header
        description: One-time passcode for multi-factor authentication if enabled.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - email
              - role
              properties:
                email:
                  type: string
                  format: email
                  description: Email address of the owner to update
                role:
                  type: string
                  description: New role for the owner
      responses:
        '200':
          description: Owner updated successfully
          content:
            text/plain:
              schema:
                type: string
                example: Owner updated successfully.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Gem or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    userHandle:
      name: userHandle
      in: path
      description: The user handle or numeric user ID
      required: true
      schema:
        type: string
      example: tenderlove
    gemName:
      name: gemName
      in: path
      description: The name of the gem
      required: true
      schema:
        type: string
      example: rails
  schemas:
    Dependency:
      type: object
      description: A gem dependency
      properties:
        name:
          type: string
          description: Name of the dependency gem
        requirements:
          type: string
          description: Version requirements string
    Owner:
      type: object
      description: A gem owner on RubyGems.org
      properties:
        id:
          type: integer
          description: Unique user ID
        handle:
          type: string
          description: User handle
        email:
          type: string
          format: email
          description: User email address
    Gem:
      type: object
      description: A Ruby gem hosted on RubyGems.org
      properties:
        name:
          type: string
          description: The name of the gem
        downloads:
          type: integer
          description: Total number of downloads for this gem
        version:
          type: string
          description: The current (latest) version number
        version_created_at:
          type: string
          format: date-time
          description: Timestamp when the current version was created
        version_downloads:
          type: integer
          description: Download count for the current version
        platform:
          type: string
          description: The platform of the gem (e.g., ruby, java)
        authors:
          type: string
          description: Comma-separated list of gem authors
        info:
          type: string
          description: Short description of the gem
        licenses:
          type: array
          items:
            type: string
          description: List of licenses for the gem
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Additional metadata key-value pairs
        yanked:
          type: boolean
          description: Whether this gem version has been yanked
        sha:
          type: string
          description: SHA-256 checksum of the gem file
        project_uri:
          type: string
          format: uri
          description: URI to the gem project page on RubyGems.org
        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
    Error:
      type: object
      description: Error response from the RubyGems.org API
      properties:
        error:
          type: string
          description: Error message
externalDocs:
  description: RubyGems.org API Documentation
  url: https://guides.rubygems.org/rubygems-org-api/