openapi: 3.1.0
info:
  title: PowerShell Gallery API
  description: |
    The PowerShell Gallery exposes a public OData v2 API for discovering, retrieving,
    and downloading PowerShell modules, scripts, and DSC resources. The service is
    consumed by the PowerShellGet / Microsoft.PowerShell.PSResourceGet client modules,
    but can also be queried directly via HTTP. Publishing endpoints require a Gallery
    API key passed in the X-NuGet-ApiKey header.
  version: "2.0"
  contact:
    name: PowerShell Gallery
    url: https://www.powershellgallery.com/
  license:
    name: PowerShell Gallery Terms of Use
    url: https://www.powershellgallery.com/policies/Terms
servers:
  - url: https://www.powershellgallery.com/api/v2
    description: PowerShell Gallery OData v2 endpoint
tags:
  - name: Metadata
    description: OData service metadata.
  - name: Packages
    description: Browse and retrieve package entries from the Gallery feed.
  - name: Search
    description: Search and discovery operations.
  - name: Updates
    description: Find updates for installed packages.
paths:
  /$metadata:
    get:
      tags: [Metadata]
      summary: Retrieve OData service metadata
      description: Returns the EDM CSDL describing entity sets, types, and function imports exposed by the Gallery.
      operationId: getMetadata
      responses:
        "200":
          description: OData CSDL document.
          content:
            application/xml: {}
  /Packages:
    get:
      tags: [Packages]
      summary: List packages
      description: |
        Returns the V2FeedPackage entity set. Supports standard OData query options
        such as $filter, $orderby, $top, $skip, $select, $expand.
      operationId: listPackages
      parameters:
        - $ref: "#/components/parameters/Filter"
        - $ref: "#/components/parameters/OrderBy"
        - $ref: "#/components/parameters/Top"
        - $ref: "#/components/parameters/Skip"
        - $ref: "#/components/parameters/Select"
        - $ref: "#/components/parameters/SemVerLevel"
      responses:
        "200":
          description: OData feed of packages.
          content:
            application/atom+xml: {}
            application/json: {}
  /Packages(Id='{id}',Version='{version}'):
    get:
      tags: [Packages]
      summary: Get a package by Id and Version
      description: Retrieves a single V2FeedPackage entity by its primary key (Id, Version).
      operationId: getPackage
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: version
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Package entity.
          content:
            application/atom+xml: {}
            application/json: {}
        "404":
          description: Package not found.
  /Search():
    get:
      tags: [Search]
      summary: Search packages
      description: |
        OData function import that searches the Gallery feed using a free-text search
        term, with optional target framework, prerelease, and SemVer level filters.
      operationId: searchPackages
      parameters:
        - name: searchTerm
          in: query
          required: true
          schema: { type: string }
          description: Quoted search expression, e.g. 'Az'.
        - name: targetFramework
          in: query
          schema: { type: string }
          description: Quoted target framework moniker.
        - name: includePrerelease
          in: query
          schema: { type: boolean, default: false }
        - name: semVerLevel
          in: query
          schema: { type: string, example: "2.0.0" }
        - $ref: "#/components/parameters/Top"
        - $ref: "#/components/parameters/Skip"
        - $ref: "#/components/parameters/OrderBy"
      responses:
        "200":
          description: Search results feed.
          content:
            application/atom+xml: {}
            application/json: {}
  /FindPackagesById():
    get:
      tags: [Packages]
      summary: Find all versions of a package by Id
      description: OData function import returning every published version of the supplied package Id.
      operationId: findPackagesById
      parameters:
        - name: id
          in: query
          required: true
          schema: { type: string }
          description: Quoted package id, e.g. 'PSReadLine'.
        - name: semVerLevel
          in: query
          schema: { type: string }
      responses:
        "200":
          description: Feed of package versions.
  /GetUpdates():
    get:
      tags: [Updates]
      summary: Check for package updates
      description: OData function import that returns available updates for a supplied set of installed packages.
      operationId: getUpdates
      parameters:
        - name: packageIds
          in: query
          required: true
          schema: { type: string }
          description: Pipe-delimited, quoted list of package ids.
        - name: versions
          in: query
          required: true
          schema: { type: string }
          description: Pipe-delimited, quoted list of currently installed versions.
        - name: includePrerelease
          in: query
          schema: { type: boolean, default: false }
        - name: includeAllVersions
          in: query
          schema: { type: boolean, default: false }
        - name: targetFrameworks
          in: query
          schema: { type: string }
        - name: versionConstraints
          in: query
          schema: { type: string }
        - name: semVerLevel
          in: query
          schema: { type: string }
      responses:
        "200":
          description: Feed of update candidates.
components:
  parameters:
    Filter:
      name: $filter
      in: query
      schema: { type: string }
      description: OData $filter expression.
    OrderBy:
      name: $orderby
      in: query
      schema: { type: string }
    Top:
      name: $top
      in: query
      schema: { type: integer, minimum: 0 }
    Skip:
      name: $skip
      in: query
      schema: { type: integer, minimum: 0 }
    Select:
      name: $select
      in: query
      schema: { type: string }
    SemVerLevel:
      name: semVerLevel
      in: query
      schema: { type: string }
  securitySchemes:
    galleryApiKey:
      type: apiKey
      in: header
      name: X-NuGet-ApiKey
      description: |
        PowerShell Gallery publishing API key, issued from a signed-in PowerShell
        Gallery user account. Required for package push and unlist operations.
security: []