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.

Filters ¶

Some routes accept a filter query parameter. Only items that match the filter are returned. The filter must be a Go expression that returns a boolean value. Filters support the following subset of Go:

• The values true, false and nil.
• == and != on any value.
• +, -,*, / and % on integers.
• + on strings.
• <, <=, > and >= on strings and integers.
• Parenthesized expressions.
• Field selection on nested objects, as in importedByCounts.packages.

The following functions are also defined:

contains(s, sub)

String s contains substring sub.

hasPrefix(s, pre)

String s has the prefix pre.

hasSuffix(s, suf)

String s has the suffix suf.

matches(s, re)

String s matches the regular expression re.

In addition, each route adds its own variables for the list items being filtered. In general, each JSON field is a variable.

Some examples of filters:

• To list only the main packages in a module, use the packages route with the filter name == "main".
• To list only symbols that are types, use the symbols route with the filter kind == "Type".
• To list only module versions for major version v2, use the versions route with the filter hasPrefix(version, "v2.").
• To list only search results imported by more than 100 packages, use the search route with the filter importedByCounts.packages > 100.

Most filters will need to be percent-encoded. Go programs should call url.QueryEscape to encode filters and all other query parameter values. Or better, put all values into a url.Values and then call Encode on that.

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.

Rate Limiting ¶

Requests to the API are rate-limited to 45 queries per second (QPS) per IP block. Exceeding the rate limit returns an HTTP status code 429 Too Many Requests.

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 ¶

• /v1/package/{path} ¶

  Information about the package at {path}.

  Parameters:

  Name	Type	Description
  module	string	Module path.
  version	string	Module version: semantic version, 'latest', or default branches 'master' or 'main'. (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.
  imported-by-counts	bool	Whether to include counts of packages and modules that are importers of this one.

  Response: Package

  Example Request

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

  Example Response

  getting response: Get "https://katy-atelier.ru/v1/package/golang.org/x/time/rate": tls: failed to verify certificate: x509: certificate is valid for pkg.go.dev, not katy-atelier.ru

• /v1/module/{path} ¶

  Information about the module at {path}.

  Parameters:

  Name	Type	Description
  version	string	Module version: semantic version, 'latest', or default branches 'master' or 'main'. (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/v1/module/golang.org/x/time

  Example Response

  getting response: Get "https://katy-atelier.ru/v1/module/golang.org/x/time": tls: failed to verify certificate: x509: certificate is valid for pkg.go.dev, not katy-atelier.ru

• /v1/versions/{path} ¶

  All versions of the module at {path}, including all major versions. Versions are listed in descending order, with incompatible versions last. Only tagged versions are returned, unless the pseudo query parameter is true. In addition, only results that match the filter query parameter are returned. The total in the response is -1 to indicate that the total number of results is unknown, unless all results fit on a single page.

  Parameters:

  Name	Type	Description
  limit	int	Max number of items to return.
  token	string	Where to resume listing.
  filter	string	Include only items matching the regular expression filter.
  pseudo	bool	Whether to include pseudo-versions in the result.

  Response: PaginatedResponse[ModuleVersion]

  Example Request

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

  Example Response

  getting response: Get "https://katy-atelier.ru/v1/versions/golang.org/x/time?limit=3": tls: failed to verify certificate: x509: certificate is valid for pkg.go.dev, not katy-atelier.ru

• /v1/packages/{path} ¶

  Information about packages of the module at {path}. Filtering is applied to the list of packages in the response. Only packages that match the filter query parameter are returned.

  Parameters:

  Name	Type	Description
  version	string	Module version: semantic version, 'latest', or default branches 'master' or 'main'. (Latest if empty).
  limit	int	Max number of items to return.
  token	string	Where to resume listing.
  filter	string	Include only items matching the regular expression filter.

  Response: PackagesResponse

  Example Request

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

  Example Response

  getting response: Get "https://katy-atelier.ru/v1/packages/golang.org/x/time/rate": tls: failed to verify certificate: x509: certificate is valid for pkg.go.dev, not katy-atelier.ru

• /v1/search ¶

  Search results. Only results that match the filter query parameter are returned. Results are sorted by how well the match the query, with the best match first.

  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 the regular expression filter.

  Response: PaginatedResponse[SearchResult]

  Example Request

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

  Example Response

  getting response: Get "https://katy-atelier.ru/v1/search?q=xyzzy": tls: failed to verify certificate: x509: certificate is valid for pkg.go.dev, not katy-atelier.ru

• /v1/symbols/{path} ¶

  List of symbols for the package at {path}. Filtering is applied to the list of symbols in the response. Only symbols that match the filter query parameter are returned.

  Parameters:

  Name	Type	Description
  module	string	Module path.
  version	string	Module version: semantic version, 'latest', or default branches 'master' or 'main'. (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 the regular expression filter.

  Response: PackageSymbols

  Example Request

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

  Example Response

  getting response: Get "https://katy-atelier.ru/v1/symbols/golang.org/x/time/rate": tls: failed to verify certificate: x509: certificate is valid for pkg.go.dev, not katy-atelier.ru

• /v1/imported-by/{path} ¶

  Paths of packages importing the package at {path}, not including packages in the same module. Filtering is applied to the list of paths in the response. Only paths that match the filter query parameter are returned. Within a filter, the variable `path` is set to the import path. The total in the response is -1 to indicate that the total number of results is unknown. This can occur if the count of importers has not been calculated yet.

  Parameters:

  Name	Type	Description
  module	string	Module path.
  version	string	Module version: semantic version, 'latest', or default branches 'master' or 'main'. (Latest if empty).
  limit	int	Max number of items to return.
  token	string	Where to resume listing.
  filter	string	Include only items matching the regular expression filter.

  Response: PackageImportedBy

  Example Request

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

  Example Response

  getting response: Get "https://katy-atelier.ru/v1/imported-by/golang.org/x/time/rate?limit=10&filter=%5E.%2A%5C.io%2F": tls: failed to verify certificate: x509: certificate is valid for pkg.go.dev, not katy-atelier.ru

• /v1/vulns/{path} ¶

  Vulnerabilities of the module or package at {path}. Data comes from the Go vulnerability database (https://vuln.go.dev). Only results that match the filter query parameter are returned.

  Parameters:

  Name	Type	Description
  module	string	Module path.
  version	string	Module version: semantic version, 'latest', or default branches 'master' or 'main'. (Latest if empty).
  limit	int	Max number of items to return.
  token	string	Where to resume listing.
  filter	string	Include only items matching the regular expression filter.

  Response: PaginatedResponse[Vulnerability]

  Example Request

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

  Example Response

  getting response: Get "https://katy-atelier.ru/v1/vulns/golang.org/x/image": tls: failed to verify certificate: x509: certificate is valid for pkg.go.dev, not katy-atelier.ru