openapi: 3.1.0
info:
  title: NuGet Search API
  description: >-
    The NuGet Search API allows clients to query for packages available on a
    NuGet package source using the SearchQueryService resource found in the
    service index. It supports filtering by keyword, target framework,
    prerelease status, and package type, and returns paginated results with
    package metadata including versions, descriptions, download counts, and
    dependency information. This API also provides an autocomplete service
    for discovering package IDs and versions by substring, powering the
    search and typeahead experience in NuGet client tools.
  version: '3.5.0'
  contact:
    name: NuGet Support
    url: https://github.com/NuGet/Home/issues
  termsOfService: https://www.nuget.org/policies/Terms
externalDocs:
  description: NuGet Search API Documentation
  url: https://learn.microsoft.com/en-us/nuget/api/search-query-service-resource
servers:
  - url: https://azuresearch-usnc.nuget.org
    description: NuGet.org Search Service (US North Central)
tags:
  - name: Autocomplete
    description: >-
      Autocomplete package IDs and enumerate package versions for typeahead
      and discovery features.
  - name: Search
    description: >-
      Search for packages by keyword, filter by various criteria, and retrieve
      paginated results with full package metadata.
security: []
paths:
  /query:
    get:
      operationId: searchPackages
      summary: Search for packages
      description: >-
        Queries for a page of packages matching a specified search query.
        Results are grouped by package ID and include metadata from the latest
        version. Unlisted packages never appear in search results. The base
        URL for this endpoint must be obtained from the service index using the
        SearchQueryService resource type.
      tags:
        - Search
      parameters:
        - $ref: '#/components/parameters/SearchQuery'
        - $ref: '#/components/parameters/Skip'
        - $ref: '#/components/parameters/Take'
        - $ref: '#/components/parameters/Prerelease'
        - $ref: '#/components/parameters/SemVerLevel'
        - $ref: '#/components/parameters/PackageType'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
  /autocomplete:
    get:
      operationId: autocompletePackageIds
      summary: Autocomplete package IDs
      description: >-
        Searches for package IDs matching a substring. This endpoint supports
        typeahead features in user interfaces integrated with a NuGet package
        source. Packages with only unlisted versions do not appear in results.
        The base URL for this endpoint must be obtained from the service index
        using the SearchAutocompleteService resource type.
      tags:
        - Autocomplete
      parameters:
        - $ref: '#/components/parameters/SearchQuery'
        - $ref: '#/components/parameters/Skip'
        - $ref: '#/components/parameters/Take'
        - $ref: '#/components/parameters/Prerelease'
        - $ref: '#/components/parameters/SemVerLevel'
        - $ref: '#/components/parameters/PackageType'
      responses:
        '200':
          description: Successful autocomplete results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteResponse'
  /autocomplete-versions:
    get:
      operationId: enumeratePackageVersions
      summary: Enumerate package versions
      description: >-
        Enumerates all listed versions for a given package ID. Unlisted
        versions do not appear in the results. This endpoint uses the same
        SearchAutocompleteService base URL with the id parameter instead of
        the q parameter.
      tags:
        - Autocomplete
      parameters:
        - name: id
          in: query
          required: true
          description: >-
            The package ID to fetch versions for.
          schema:
            type: string
        - $ref: '#/components/parameters/Prerelease'
        - $ref: '#/components/parameters/SemVerLevel'
      responses:
        '200':
          description: Successful version enumeration results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionEnumerationResponse'
components:
  parameters:
    SearchQuery:
      name: q
      in: query
      required: false
      description: >-
        The search terms used to filter packages. If not provided, all packages
        are returned within the boundaries of skip and take.
      schema:
        type: string
    Skip:
      name: skip
      in: query
      required: false
      description: >-
        The number of results to skip for pagination. Defaults to 0. On
        nuget.org, limited to 3000.
      schema:
        type: integer
        default: 0
        minimum: 0
    Take:
      name: take
      in: query
      required: false
      description: >-
        The number of results to return for pagination. The server may impose
        a maximum value. On nuget.org, limited to 1000.
      schema:
        type: integer
        minimum: 1
    Prerelease:
      name: prerelease
      in: query
      required: false
      description: >-
        When true, pre-release packages are included in results. Defaults to
        false, which excludes pre-release packages.
      schema:
        type: boolean
        default: false
    SemVerLevel:
      name: semVerLevel
      in: query
      required: false
      description: >-
        A SemVer version string used to opt-in to SemVer 2.0.0 packages. If
        excluded, only SemVer 1.0.0 compatible versions are returned. Use
        2.0.0 to include SemVer 2.0.0 packages.
      schema:
        type: string
        example: '2.0.0'
    PackageType:
      name: packageType
      in: query
      required: false
      description: >-
        The package type name to filter results. Added in
        SearchQueryService/3.5.0. If empty or not provided, no filter is
        applied.
      schema:
        type: string
  schemas:
    SearchResponse:
      type: object
      description: >-
        The response from a package search query.
      required:
        - totalHits
        - data
      properties:
        totalHits:
          type: integer
          description: >-
            The total number of matches, disregarding skip and take.
        data:
          type: array
          description: >-
            The search results matched by the request, grouped by package ID.
          items:
            $ref: '#/components/schemas/SearchResult'
    SearchResult:
      type: object
      description: >-
        A search result representing a package, with metadata from the latest
        version.
      required:
        - id
        - version
        - versions
        - packageTypes
      properties:
        id:
          type: string
          description: >-
            The ID of the matched package.
        version:
          type: string
          description: >-
            The full SemVer 2.0.0 version string of the latest package version.
        description:
          type: string
          description: >-
            The description of the package.
        versions:
          type: array
          description: >-
            All versions of the package matching the prerelease parameter.
          items:
            $ref: '#/components/schemas/SearchResultVersion'
        authors:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: >-
            The author or authors of the package.
        iconUrl:
          type: string
          format: uri
          description: >-
            The URL to the package icon.
        licenseUrl:
          type: string
          format: uri
          description: >-
            The URL to the package license.
        owners:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: >-
            The owner or owners of the package on the package source.
        projectUrl:
          type: string
          format: uri
          description: >-
            The URL to the project page.
        registration:
          type: string
          format: uri
          description: >-
            The absolute URL to the associated registration index.
        summary:
          type: string
          description: >-
            A summary of the package.
        tags:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: >-
            Tags associated with the package.
        title:
          type: string
          description: >-
            The title of the package.
        totalDownloads:
          type: integer
          description: >-
            The total number of downloads across all versions.
        verified:
          type: boolean
          description: >-
            Whether the package is verified via ID prefix reservation.
        packageTypes:
          type: array
          description: >-
            The package types defined by the package author.
          items:
            $ref: '#/components/schemas/PackageType'
    SearchResultVersion:
      type: object
      description: >-
        A specific version entry within a search result.
      required:
        - '@id'
        - version
        - downloads
      properties:
        '@id':
          type: string
          format: uri
          description: >-
            The absolute URL to the associated registration leaf.
        version:
          type: string
          description: >-
            The full SemVer 2.0.0 version string.
        downloads:
          type: integer
          description: >-
            The number of downloads for this specific version.
    PackageType:
      type: object
      description: >-
        A package type defined by the package author.
      required:
        - name
      properties:
        name:
          type: string
          description: >-
            The name of the package type.
    AutocompleteResponse:
      type: object
      description: >-
        The response from a package ID autocomplete query.
      required:
        - totalHits
        - data
      properties:
        totalHits:
          type: integer
          description: >-
            The total number of matches, disregarding skip and take.
        data:
          type: array
          description: >-
            The package IDs matched by the request.
          items:
            type: string
    VersionEnumerationResponse:
      type: object
      description: >-
        The response from a package version enumeration query.
      required:
        - data
      properties:
        data:
          type: array
          description: >-
            The package versions matched by the request.
          items:
            type: string