API Documentation

Pkgsite provides a JSON API for accessing information about Go packages and modules.

Requests

All requests are GET requests whose first URL segment selects the request type. Except for search, the remaining segments specify a module or package path. Additional arguments are specified as query parameters.

Package paths are ambiguous: the same path a/b/c could be package c in module a/b or package b/c in module a. If both exist, the API returns an error with a list of possible modules in its candidates field. Make a follow-up request with the module query parameter to disambiguate. (Note: this behavior differs from the pkgsite UI, which selects the longest matching module path.)

Some routes accept an optional version query parameter. If missing, the latest version is chosen.

Some routes accept optional GOOS and GOARCH query parameters to select the desired build context of the documentation. If omitted, the default documentation build context is selected, typically linux/amd64.

Some routes accept a filter, specifying a regular expression. Only items that match the filter are returned. The documentation for each route specifies what constitutes a match for that route's items.

Most regular expression metacharacters will need to be percent-encoded. For example, to filter with the regular expression ^abc.*, write filter=%5Eabc.%2A. Go programs should call url.QueryEscape to encode filters (and all other query parameter values as well).

Responses

All routes return a JSON response. You can find a link to the corresponding Go type for a route in the documentation below. Errors are also returned as a JSON object, whose message field contains the error message.

You can access the machine-readable OpenAPI Specification.

Pagination

Some responses are paginated. Each response page has a nextPageToken, which is non-empty if there is another page of items. To retrieve the next page, repeat the original request verbatim, adding a token query parameter whose value is the next-page token from the response. Changing the request in any way other than providing a token may result in an error.

As long as nextPageToken is non-empty, there is another page, even if the current page has no items.

Routes

• /v1beta/package/{path}

  Information about the package at {path}.

  Parameters:

  Name	Type	Description
  module	string	module path
  version	string	module version (latest if empty)
  goos	string	GOOS of documentation build context
  goarch	string	GOARCH of documentation build context
  doc	string	Documentation format: text, html, md or markdown. If omitted, documentation is not returned.
  examples	bool	Whether to include examples with the returned documentation.
  imports	bool	Whether to include the packages that this one imports.
  licenses	bool	Whether to include licenses in the result.

  Response: Package

  Example Request

  curl -L https://pkg.go.dev/v1beta/package/golang.org/x/time/rate

  Example Response

  getting response: Get "http://pkg.go.dev/v1beta/package/golang.org/x/time/rate": read tcp [fddf:3978:feb1:d745::c001]:23996->[2600:1901:0:f535::]:80: read: connection reset by peer

• /v1beta/module/{path}

  Information about the module at {path}.

  Parameters:

  Name	Type	Description
  version	string	module version (latest if empty)
  licenses	bool	Whether to include licenses in the result.
  readme	bool	Whether to include the README in the result.

  Response: Module

  Example Request

  curl -L https://pkg.go.dev/v1beta/module/golang.org/x/time

  Example Response

  getting response: Get "http://pkg.go.dev/v1beta/module/golang.org/x/time": EOF

• /v1beta/versions/{path}

  Versions of the module at {path}. If there are tagged versions, they are returned. Otherwise, the 10 most recent pseudo-versions are returned. The versions are in descending order. Only results whose version matches the regexp in the filter query parameter are returned.

  Parameters:

  Name	Type	Description
  limit	int	max number of items to return
  token	string	where to resume listing
  filter	string	include only items matching filter

  Response: PaginatedResponse[ModuleVersion]

  Example Request

  curl -L https://pkg.go.dev/v1beta/versions/golang.org/x/time?limit=3

  Example Response

  getting response: Get "http://pkg.go.dev/v1beta/versions/golang.org/x/time?limit=3": EOF

• /v1beta/packages/{path}

  Information about packages of the module at {path}. Only results whose path or synopsis matches the regexp in the filter query parameter are returned.

  Parameters:

  Name	Type	Description
  version	string	module version (latest if empty)
  limit	int	max number of items to return
  token	string	where to resume listing
  filter	string	include only items matching filter

  Response: PackagesResponse

  Example Request

  curl -L https://pkg.go.dev/v1beta/packages/golang.org/x/time/rate

  Example Response

  getting response: Get "http://pkg.go.dev/v1beta/packages/golang.org/x/time/rate": EOF

• /v1beta/search

  Search results. Only results whose package path or synopsis matches the regexp in the filter query parameter are returned.

  Parameters:

  Name	Type	Description
  q	string	Find packages matching this query.
  symbol	string	If non-empty, find symbols matching this string. The query further restricts the search to matching packages.
  limit	int	max number of items to return
  token	string	where to resume listing
  filter	string	include only items matching filter

  Response: PaginatedResponse[SearchResult]

  Example Request

  curl -L https://pkg.go.dev/v1beta/search?q=xyzzy

  Example Response

  getting response: Get "http://pkg.go.dev/v1beta/search?q=xyzzy": EOF

• /v1beta/symbols/{path}

  List of symbols for the package at {path}. Only results whose name or synopsis matches the regexp in the filter query parameter are returned.

  Parameters:

  Name	Type	Description
  module	string	module path
  version	string	module version (latest if empty)
  goos	string	GOOS of documentation build context
  goarch	string	GOARCH of documentation build context
  limit	int	max number of items to return
  token	string	where to resume listing
  filter	string	include only items matching filter

  Response: PackageSymbols

  Example Request

  curl -L https://pkg.go.dev/v1beta/symbols/golang.org/x/time/rate

  Example Response

  getting response: Get "http://pkg.go.dev/v1beta/symbols/golang.org/x/time/rate": read tcp [fddf:3978:feb1:d745::c001]:26194->[2600:1901:0:f535::]:80: read: connection reset by peer

• /v1beta/imported-by/{path}

  Paths of packages importing the package at {path}, not including packages in the same module. Only results whose path matches the regexp in the filter query parameter are returned.

  Parameters:

  Name	Type	Description
  module	string	module path
  version	string	module version (latest if empty)
  limit	int	max number of items to return
  token	string	where to resume listing
  filter	string	include only items matching filter

  Response: PackageImportedBy

  Example Request

  curl -L https://pkg.go.dev/v1beta/imported-by/golang.org/x/time/rate?limit=10&filter=%5E.%2A%5C.io%2F

  Example Response

  getting response: Get "http://pkg.go.dev/v1beta/imported-by/golang.org/x/time/rate?limit=10&filter=%5E.%2A%5C.io%2F": EOF

• /v1beta/vulns/{path}

  Vulnerabilities of the module at {path}, from the Go vulnerability database (https://vuln.go.dev). Only results whose ID or details matches the regexp in the filter query parameter are returned.

  Parameters:

  Name	Type	Description
  version	string	module version (latest if empty)
  limit	int	max number of items to return
  token	string	where to resume listing
  filter	string	include only items matching filter

  Response: PaginatedResponse[Vulnerability]

  Example Request

  curl -L https://pkg.go.dev/v1beta/vulns/golang.org/x/image

  Example Response

  getting response: Get "http://pkg.go.dev/v1beta/vulns/golang.org/x/image": EOF