Skip to main content
GitHits endpoints use common request conventions. Each endpoint’s reference describes the parameters it accepts and the information it returns.

​
Choose what the response includes

The fields parameter lets you request the information your application or agent needs. For example, package inspection returns basic package and release information by default. You can also ask for download counts, vulnerability information or release notes. Add fields to the URL as a query parameter. Separate multiple choices with commas. For package inspection: When you supply fields, your choices replace the defaults. Include the default groups explicitly if you want to keep them. Some information, such as the package name and resolved version in package inspection, is always returned so you can identify the result. This request keeps the default package and release information and adds security information for Express 4.18.2:
This example expects your API token in GITHITS_API_TOKEN, as explained in the quickstart. The quotes around the URL ensure your shell passes the whole URL, including &, to curl.

​
Check the choices for your endpoint

Each endpoint defines its own allowed fields values. Use the names listed in its reference; a property appearing in a JSON response does not automatically make it an accepted fields value. For example, package inspection accepts security.* as a name for security counts and recent advisories. That does not mean * works with every name or endpoint. Likewise, requesting package does not include the separately listed package.downloads information. fields stays in the URL for both GET and POST requests. For a POST, put the other inputs in the JSON body as shown in the endpoint reference. Send one fields parameter containing your comma-separated choices, rather than repeating the parameter. Not every endpoint accepts fields. If the reference does not list it, use that endpoint’s normal response. Unsupported choices return 400 VALIDATION_ERROR. Selecting less information can reduce the response size. It does not always reduce the work needed to produce the result; each endpoint explains when a choice changes the work performed.

​
Pass request parameters

  • Put URL parameters after ? and separate them with &, as in the example above.
  • For JSON request bodies, send Content-Type: application/json. Use the exact property names shown in the reference, such as current_version.
  • Encode special characters in URL values. A scoped npm package such as @scope/package becomes %40scope%2Fpackage in the package-name part of the path.
  • When a version contains a literal +, write %2B in the URL. An unencoded + in a query value is read as a space.
  • Use returned documentation page IDs and other read targets as described by the endpoint. If the target belongs in one URL path segment, encode the entire value, including any / characters it contains.

​
Interpret the result

Keep the returned package version or commit and source references with the information your workflow uses. When discovery returns a target for a later source or documentation read, follow the endpoint’s instructions for using that target. Check whether a response reports incomplete information or when its data was last updated. HTTP 200 means the request succeeded; some endpoints can still report missing or incomplete evidence. An omitted property, null, an empty list and zero can mean different things. The reference explains those meanings for each response. For failed requests, use the HTTP status and the response’s code to decide what to do next. See API errors for troubleshooting and retry guidance.