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

> Connect your software factory to GitHits with an authenticated HTTP request for an exact package version.

Inspect an exact package version with one HTTP request—the first step in connecting GitHits to your software factory. This example uses 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 evidence 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.

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