> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/agents/api-quickstart-for-agents.md).

# API quickstart for agents

Authenticate, push, pull, and inspect artifacts in Harness Artifacts using environment variables, CLI tools, and the HTTP API.

## Authentication

All operations, including the REST management API, client CLIs, and HTTP package endpoints, authenticate with a single Harness API key. Set it once as an environment variable and use it everywhere.

```bash
export HARNESS_API_KEY="<pat-or-service-account-token>"
```

**Header for REST and HTTP API calls**: `x-api-key: $HARNESS_API_KEY`

**Password for CLI clients (Docker, Helm, npm, Maven, pip, Cargo)**: use `$HARNESS_API_KEY` as the password. For service account tokens the username is the literal string `_token`. For PATs the username is your Harness account email.

{% hint style="info" %}
**TOKEN TYPE**

Use a **Service Account Token** in CI/CD pipelines and automation. Personal Access Tokens (PATs) are tied to a user identity and break when that user leaves. Go to [Authentication for agents](https://developer.harness.io/artifact-registry/3.0/agents/authentication-for-agents.md) for token generation and rotation guidance.
{% endhint %}

***

## Environment setup

Set these four variables before running any of the commands in this guide. Every code block uses them. Format-specific variables (image name, chart name, package name, and so on) are declared at the top of each format section.

```bash
export HARNESS_API_KEY="<pat-or-service-account-token>"
export HARNESS_ACCOUNT_ID="<your-account-id>"          # visible in your Harness URL: app.harness.io/ng/account/<ID>
export HAR_REGISTRY="<registry-name>"                  # the registry you are targeting
export HARNESS_MANAGER_HOST="app.harness.io"           # replace with your cluster hostname if different
```

**Verify connectivity**:

```bash
curl -s -o /dev/null -w "%{http_code}" \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/"
```

Expected: `200`. Any other code means the token is wrong (`401`), the registry does not exist (`404`), or permissions are missing (`403`). Go to [Error reference](#error-reference) for status code explanations.

***

## Push and pull

Pick the format your agent works with. All commands use the environment variables declared at the start of this guide.

{% tabs %}
{% tab title="Docker" %}
**Variables**

```bash
export IMAGE_NAME="<image-name>"   # example: my-app
export TAG="<tag>"                 # example: 1.0.0
```

**Log in**

```bash
echo "$HARNESS_API_KEY" | docker login pkg.harness.io \
  --username "_token" \
  --password-stdin
```

**Push**

```bash
docker tag "$IMAGE_NAME:$TAG" \
  "pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/$IMAGE_NAME:$TAG"

docker push "pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/$IMAGE_NAME:$TAG"
```

**Pull**

```bash
docker pull "pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/$IMAGE_NAME:$TAG"
```

**Check if an image exists (no download)**

```bash
docker manifest inspect \
  "pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/$IMAGE_NAME:$TAG" \
  > /dev/null 2>&1 && echo "exists" || echo "not found"
```

{% endtab %}

{% tab title="Helm OCI" %}
**Variables**

```bash
export CHART_NAME="<chart-name>"
export CHART_VERSION="<version>"    # example: 1.2.3
export CHART_DIR="<path-to-chart>"  # local directory containing Chart.yaml
```

**Log in**

```bash
echo "$HARNESS_API_KEY" | helm registry login pkg.harness.io \
  --username "_token" \
  --password-stdin
```

**Push**

```bash
helm package "$CHART_DIR"
helm push "$CHART_NAME-$CHART_VERSION.tgz" \
  "oci://pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY"
```

**Pull**

```bash
helm pull "oci://pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/$CHART_NAME" \
  --version "$CHART_VERSION"
```

**Inspect chart metadata without downloading**

```bash
helm show chart \
  "oci://pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/$CHART_NAME" \
  --version "$CHART_VERSION"
```

{% endtab %}

{% tab title="Maven" %}
**Configure `~/.m2/settings.xml`**. Run this once per agent environment:

```bash
mkdir -p ~/.m2
cat > ~/.m2/settings.xml <<EOF
<settings>
  <servers>
    <server>
      <id>harness</id>
      <username>_token</username>
      <password>${HARNESS_API_KEY}</password>
    </server>
  </servers>
</settings>
EOF
```

**`pom.xml` blocks**. Add both to the project `pom.xml`:

```xml
<repositories>
  <repository>
    <id>harness</id>
    <url>https://pkg.harness.io/pkg/${HARNESS_ACCOUNT_ID}/${HAR_REGISTRY}/maven</url>
  </repository>
</repositories>

<distributionManagement>
  <repository>
    <id>harness</id>
    <url>https://pkg.harness.io/pkg/${HARNESS_ACCOUNT_ID}/${HAR_REGISTRY}/maven</url>
  </repository>
  <snapshotRepository>
    <id>harness</id>
    <url>https://pkg.harness.io/pkg/${HARNESS_ACCOUNT_ID}/${HAR_REGISTRY}/maven</url>
  </snapshotRepository>
</distributionManagement>
```

**Push**

```bash
mvn deploy \
  -DHARNESS_ACCOUNT_ID="$HARNESS_ACCOUNT_ID" \
  -DHAR_REGISTRY="$HAR_REGISTRY"
```

**Pull (resolve dependencies)**

```bash
mvn dependency:resolve \
  -DHARNESS_ACCOUNT_ID="$HARNESS_ACCOUNT_ID" \
  -DHAR_REGISTRY="$HAR_REGISTRY"
```

{% endtab %}

{% tab title="npm" %}
**Variables**

```bash
export PACKAGE_NAME="<package-name>"
export PACKAGE_VERSION="<version>"  # example: 1.0.0
```

**Configure npm**. Run this once per agent environment:

```bash
npm config set \
  "registry" "https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/npm/"
npm config set \
  "//pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/npm/:_authToken" \
  "$HARNESS_API_KEY"
```

Or write `~/.npmrc` directly:

```bash
cat > ~/.npmrc <<EOF
registry=https://pkg.harness.io/pkg/${HARNESS_ACCOUNT_ID}/${HAR_REGISTRY}/npm/
//pkg.harness.io/pkg/${HARNESS_ACCOUNT_ID}/${HAR_REGISTRY}/npm/:_authToken=${HARNESS_API_KEY}
EOF
```

**Push**

```bash
npm publish
```

**Pull**

```bash
npm install "$PACKAGE_NAME@$PACKAGE_VERSION"
```

{% endtab %}

{% tab title="Python / PyPI" %}
**Variables**

```bash
export PACKAGE_NAME="<package-name>"
export PACKAGE_VERSION="<version>"  # example: 1.0.0
```

**Configure Twine**. Write `~/.pypirc`:

```bash
cat > ~/.pypirc <<EOF
[distutils]
index-servers = harness

[harness]
repository = https://pkg.harness.io/pkg/${HARNESS_ACCOUNT_ID}/${HAR_REGISTRY}/python
username = _token
password = ${HARNESS_API_KEY}
EOF
```

**Push**

```bash
python -m build
python -m twine upload --repository harness dist/*
```

**Pull a specific version**

Write credentials to `~/.netrc` so pip can authenticate without embedding the token in the index URL:

```bash
cat > ~/.netrc <<EOF
machine pkg.harness.io
login _token
password ${HARNESS_API_KEY}
EOF
chmod 600 ~/.netrc

export PIP_INDEX_URL="https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/python/simple"
pip install --no-deps "$PACKAGE_NAME==$PACKAGE_VERSION"
```

{% hint style="info" %}
`--no-deps` installs only the named package without resolving transitive dependencies against the Harness registry. Remove `--no-deps` if your Harness registry also hosts the package's dependencies, or if you want pip to resolve them from other configured sources.
{% endhint %}
{% endtab %}

{% tab title="Cargo" %}
**Variables**

```bash
export CRATE_NAME="<crate-name>"
export CRATE_VERSION="<version>"  # example: 0.1.0
```

**Configure Cargo**. Write or append to `~/.cargo/config.toml`:

```bash
cat >> ~/.cargo/config.toml <<EOF

[registry]
global-credential-providers = ["cargo:token", "cargo:libsecret", "cargo:macos-keychain", "cargo:wincred"]

[registries.harness-${HAR_REGISTRY}]
index = "sparse+https://pkg.harness.io/pkg/${HARNESS_ACCOUNT_ID}/${HAR_REGISTRY}/cargo/index/"
EOF
```

**Set the token**. Write or append to `~/.cargo/credentials.toml`:

```bash
cat >> ~/.cargo/credentials.toml <<EOF

[registries.harness-${HAR_REGISTRY}]
token = "Bearer ${HARNESS_API_KEY}"
EOF
```

**Push**

```bash
cargo publish --registry "harness-$HAR_REGISTRY"
```

**Pull**

```bash
cargo add "$CRATE_NAME@$CRATE_VERSION" --registry "harness-$HAR_REGISTRY"
```

{% endtab %}

{% tab title="Generic / HTTP" %}
**Variables**

```bash
export ARTIFACT_NAME="<artifact-name>"
export VERSION="<version>"           # example: 1.0.0
export FILE_NAME="<filename>"        # example: app-1.0.0.tar.gz
export FILE_PATH="<local-file-path>" # path to the file you are uploading
```

The Generic registry accepts arbitrary files over HTTP. No CLI installation is required; use `curl`.

**Push a file**

```bash
curl -X PUT \
  -H "x-api-key: $HARNESS_API_KEY" \
  -T "$FILE_PATH" \
  "https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/files/$ARTIFACT_NAME/$VERSION/$FILE_NAME"
```

**Pull a file**

```bash
curl -L \
  -H "x-api-key: $HARNESS_API_KEY" \
  -J -O \
  "https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/files/$ARTIFACT_NAME/$VERSION/$FILE_NAME"
```

**Check if a file exists (HEAD request, no download)**

```bash
curl -I \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/files/$ARTIFACT_NAME/$VERSION/$FILE_NAME"
```

**Delete a file**

```bash
curl -X DELETE \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/files/$ARTIFACT_NAME/$VERSION/$FILE_NAME"
```

Nested paths are supported. Replace `$FILE_NAME` with a path like `config/prod/settings.json`.
{% endtab %}
{% endtabs %}

***

## Inspect artifacts using the REST API

Use the management REST API to list registries, query artifact metadata, and check vulnerability status. All endpoints require the `x-api-key` header.

**List registries in your account**

```bash
curl -s \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://$HARNESS_MANAGER_HOST/har/api/v1/registry?accountIdentifier=$HARNESS_ACCOUNT_ID" \
  | jq '.data.registries[] | {name: .identifier, type: .packageType}'
```

**List artifacts in a registry**

```bash
curl -s \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://$HARNESS_MANAGER_HOST/har/api/v1/artifact?accountIdentifier=$HARNESS_ACCOUNT_ID&registryIdentifier=$HAR_REGISTRY" \
  | jq '.data.artifacts[] | {name: .name, latestVersion: .latestVersion}'
```

**Get version details for a specific artifact**

```bash
curl -s \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://$HARNESS_MANAGER_HOST/har/api/v1/artifact/$ARTIFACT_NAME/version/$VERSION?accountIdentifier=$HARNESS_ACCOUNT_ID&registryIdentifier=$HAR_REGISTRY" \
  | jq '{digest: .data.digest, size: .data.size, vulnerabilities: .data.vulnerabilities}'
```

Go to [REST API reference](https://developer.harness.io/artifact-registry/3.0/reference/rest-api.md) for the full OpenAPI specification, including request and response schemas.

***

## Error reference

Match the HTTP status code returned by any REST or package manager call against this table to identify the cause and the fix.

| HTTP code                      | Meaning                                  | Common cause                                                                                 | Fix                                                                 |
| ------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `200`                          | OK                                       | None                                                                                         | None                                                                |
| `401 Unauthorized`             | Token missing or invalid                 | `x-api-key` header absent, token revoked, or token expired                                   | Regenerate the token and update `$HARNESS_API_KEY`                  |
| `403 Forbidden`                | Token valid but insufficient permissions | Service account lacks `Artifact Registries: Pull` or `Push` permission at the registry scope | Add the required permission to the service account role             |
| `404 Not Found`                | Resource does not exist                  | Registry name typo, artifact not yet pushed, or wrong account ID                             | Check `$HAR_REGISTRY`, `$HARNESS_ACCOUNT_ID`, and the artifact name |
| `409 Conflict`                 | Resource already exists                  | Pushing an artifact version that is already present                                          | Use a new version tag, or delete the existing version first         |
| `413 Request Entity Too Large` | Upload exceeds size limit                | File exceeds 5 TiB (Generic registry limit)                                                  | Split the payload or contact Harness Support                        |

***

## What to do next

* Go to [Authentication for agents](https://developer.harness.io/artifact-registry/3.0/agents/authentication-for-agents.md) for service account setup, token rotation, and Kubernetes `imagePullSecrets` configuration.
* Go to [Automate registry creation with Terraform](https://developer.harness.io/artifact-registry/3.0/agents/automate-with-terraform.md) to provision registries, upstream proxies, and lifecycle rules as code.
* Go to [REST API reference](https://developer.harness.io/artifact-registry/3.0/reference/rest-api.md) for the complete OpenAPI specification with all request and response schemas.
* Go to [Using Artifacts with AI agents](https://developer.harness.io/artifact-registry/3.0/agents/using-ar-with-ai-agents.md) for patterns specific to AI coding assistants and Model Context Protocol (MCP) tool integration.

{% @harness-feedback/feedback %}
