> ## Documentation Index
> Fetch the complete documentation index at: https://docs.githits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Requests and responses

> Choose response information with fields, pass parameters and read GitHits API results.

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:

| Request                                      | Information returned                                                                             |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Omit `fields`                                | Default package and selected-release information                                                 |
| `fields=security`                            | Vulnerability counts and whether the selected release is affected                                |
| `fields=security.*`                          | The security information above, plus up to five recent advisories affecting the selected release |
| `fields=package,selected_version,security.*` | The default information plus the security information and recent advisories                      |

**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`:

```bash theme={null}
curl --silent --show-error \
  --header "Authorization: Bearer $GITHITS_API_TOKEN" \
  'https://api.githits.dev/v1/packages/npm/express?version=4.18.2&fields=package,selected_version,security.*'
```

This example expects your API token in `GITHITS_API_TOKEN`, as explained in the [quickstart](/api/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](/api/errors) for troubleshooting and retry guidance.