> ## 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.

# API quickstart

> Inspect an exact package version with an authenticated HTTP request to the GitHits API.

This example inspects Express `4.18.2`; substitute a package version your software depends on. You need a GitHits account, an API token and `curl`.

## Authenticate

Create an API token in [your token settings](https://app.githits.com/settings/tokens). The examples below expect it to be available in the `GITHITS_API_TOKEN` environment variable. Supply that variable through your CI or runtime secret store.

The API reads your token from the `Authorization: Bearer` header; your integration can use any variable name or credential-storage mechanism. See [API authentication](/api/authentication) for credential handling.

The command below assumes the secret is already available in the environment. Do not write the token into the command, enable shell tracing or copy credentials into an agent conversation.

## Inspect an exact package version

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

A successful request returns HTTP `200` with JSON containing `package` and `selected_version`. The package identity includes its latest version; `selected_version` describes the requested release, `4.18.2`. Keep that version information with the results your workflow uses. The package’s latest version can change independently.

The response headers include `X-Request-ID` for diagnostics and `Cache-Control: no-store`. If the request fails, use its HTTP status and problem `code` to choose the next action; see [errors](/api/errors).

## Add vulnerability information

Use `fields` to choose what the response includes. This request keeps the basic package and release information and adds vulnerability counts and up to five recent advisories affecting Express `4.18.2`:

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

The `package` and `selected_version` choices keep the information from your first request. `security.*` adds the security information. When you specify `fields`, it replaces the endpoint's default choices, so include everything you need.

See [Requests and responses](/api/requests-and-responses#choose-what-the-response-includes) for how `fields` works, and [Inspect a package release](/api-reference/v1/packages/inspect-a-package-release) for all available choices.

## Find documentation and source files

List documentation for the same release:

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

Pass a returned page's `docs_read_target` as the `target` query parameter to `GET /v1/read`, omitting `path`.

To discover source files instead:

```bash theme={null}
curl --silent --show-error \
  --header "Authorization: Bearer $GITHITS_API_TOKEN" \
  'https://api.githits.dev/v1/code/files?registry=npm&name=express&version=4.18.2'
```

Read a returned file with `GET /v1/read`, using `target=npm:express@4.18.2` and its exact target-relative `path`. Both read types use the same endpoint; the response's `kind` identifies documentation or code. See [Read documentation or source code](/api/requests-and-responses#read-documentation-or-source-code) for copyable read requests and response handling.

## Test locally with your CLI login

For local development, you can use your existing [GitHits CLI login](/authentication). Log in with `npx githits@latest login`, then run this in your own Bash or Zsh terminal. The command captures the current token without printing it and clears the temporary variable afterward. It uses `GITHITS_ACCESS_TOKEN` for that temporary value so it does not overwrite `GITHITS_API_TOKEN`, which the CLI reads first. Keep shell tracing disabled. If `GITHITS_API_TOKEN` is set, the CLI uses that credential instead of local OAuth storage.

```bash theme={null}
GITHITS_ACCESS_TOKEN=$(npx githits@latest auth token) &&
curl --silent --show-error --include \
  --header "Authorization: Bearer $GITHITS_ACCESS_TOKEN" \
  'https://api.githits.dev/v1/packages/npm/express?version=4.18.2'
unset GITHITS_ACCESS_TOKEN
```

## Try the same request in the browser

Open [Inspect a package release](/api-reference/v1/packages/inspect-a-package-release), choose **Try it**, enter your bearer token in the authorization field, and set `registry` to `npm`, `name` to `express` and `version` to `4.18.2`. Check that the destination is `https://api.githits.dev` before choosing **Send**.

The playground sends a live API request. Browser credentials can persist across reloads; follow the [playground authentication guidance](/api/authentication#use-the-api-playground).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.