> 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/using-ar-with-ai-agents.md).

# Using Harness Artifacts with AI agents

What Harness Artifacts is, how to authenticate, what URLs to use, and which operations are available, written for AI agents and LLMs.

{% hint style="info" %}
**For AI agents and LLMs**

This page is written to be consumed directly by an AI agent. It covers authentication, URL patterns, available operations, REST API endpoints, and supported formats in a dense, copy-paste-ready format. If you are an agent reading this, start at [Authentication](#authentication) and work top to bottom.
{% endhint %}

## What Harness Artifacts is

Harness Artifacts is a universal artifact storage service. It hosts Docker images, Helm charts, npm packages, Python wheels, Maven JARs, Go modules, Cargo crates, NuGet packages, Terraform modules, Hugging Face models, generic files, and more in a single system.

A **registry** is a named namespace inside a Harness account. Each registry hosts one package type. The registry URL follows a predictable pattern:

```
pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>
```

The REST management API lives at a separate host:

```
https://app.harness.io/har/api/v1
```

***

## Authentication

One API key authenticates every operation: package manager clients, the REST API, and the CLI.

```bash
export HARNESS_API_KEY="<pat-or-service-account-token>"
export HARNESS_ACCOUNT_ID="<account-id>"        # from app.harness.io URL: /ng/account/<ID>
export HARNESS_EMAIL="<harness-account-email>"  # only needed for PAT auth; service accounts use "_token" as username
export HAR_REGISTRY="<registry-name>"
```

| Context                                              | How to pass the key                                                 |
| ---------------------------------------------------- | ------------------------------------------------------------------- |
| REST API calls                                       | `x-api-key: $HARNESS_API_KEY` header                                |
| Package manager clients: service account             | password = `$HARNESS_API_KEY`, username = `_token` (literal string) |
| Package manager clients: personal access token (PAT) | password = `$HARNESS_API_KEY`, username = `$HARNESS_EMAIL`          |
| `hc auth login`                                      | `--api-token $HARNESS_API_KEY`                                      |
| All other `hc` commands                              | `--token $HARNESS_API_KEY` or `HARNESS_API_TOKEN` env var           |
| Kubernetes `imagePullSecret`                         | username = `_token`, password = `$HARNESS_API_KEY`                  |

Use a **Service Account Token**, not a Personal Access Token, for any non-interactive agent. PATs are tied to a user identity.

**Verify the token works**:

```bash
curl -s -o /dev/null -w "%{http_code}" \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://app.harness.io/har/api/v1/registry?accountIdentifier=$HARNESS_ACCOUNT_ID"
```

Expected: `200`. `401` = bad token. `403` = token valid but no registry permissions.

***

## Registry URL patterns

Docker and OCI clients use `pkg.harness.io/<ACCOUNT_ID>/<REGISTRY>` directly. All HTTP-based package manager clients (npm, Maven, Python, Cargo, and other HTTP-based package managers) use `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>`; note the extra `/pkg/` path segment after the hostname.

| Format            | Registry URL suffix         | Example                                                                       |
| ----------------- | --------------------------- | ----------------------------------------------------------------------------- |
| Docker / OCI      | *(none)*                    | `pkg.harness.io/<ACCOUNT_ID>/<REGISTRY>`                                      |
| Helm OCI          | *(none, same as Docker)*    | `oci://pkg.harness.io/<ACCOUNT_ID>/<REGISTRY>`                                |
| npm               | `/npm/`                     | `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/npm/`                     |
| Python / PyPI     | `/python/`                  | `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/python/`                  |
| Maven             | `/maven`                    | `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/maven`                    |
| Go modules        | *(inline in GOPROXY)*       | `https://_token:<TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/go`        |
| Cargo             | `/cargo/index/`             | `sparse+https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/cargo/index/`      |
| NuGet             | `/nuget/index.json`         | `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/nuget/index.json`         |
| Hugging Face      | `/huggingface`              | `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/huggingface`              |
| Generic / HTTP    | `/generic/<NAME>/<VERSION>` | `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/generic/<NAME>/<VERSION>` |
| Terraform modules | `/terraform`                | `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/terraform`                |
| RPM               | `/rpm`                      | `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/rpm`                      |
| Debian / APT      | `/deb`                      | `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY>/deb`                      |

***

## Core operations

### Check if an artifact exists

```bash
# Docker image: log in first, then inspect (suppress download)
echo "$HARNESS_API_KEY" | docker login pkg.harness.io \
  --username _token --password-stdin

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

# Generic file (HEAD, no download)
curl -s -o /dev/null -w "%{http_code}" -I \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/generic/$ARTIFACT/$VERSION/$FILE"
```

### Push an artifact

```bash
# Docker image: requires prior docker login (see Check if an artifact exists above)
docker push "pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/$IMAGE:$TAG"

# Python package (after twine is configured)
python -m twine upload --repository harness dist/*

# Generic file
curl -s -X PUT \
  -H "x-api-key: $HARNESS_API_KEY" \
  -F "file=@\"$FILE_PATH\"" \
  "https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/generic/$ARTIFACT/$VERSION"
```

### Pull an artifact

```bash
# Docker image
docker pull "pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/$IMAGE:$TAG"

# Python package
pip install \
  --index-url "https://_token:$HARNESS_API_KEY@pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/python/simple" \
  "$PACKAGE==$VERSION"

# Generic file
curl -s -L -J -O \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/generic/$ARTIFACT/$VERSION?filename=$FILE"
```

### Delete an artifact version

```bash
curl -s -X DELETE \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://app.harness.io/har/api/v1/artifact/$ARTIFACT/version/$VERSION?accountIdentifier=$HARNESS_ACCOUNT_ID&registryIdentifier=$HAR_REGISTRY"
```

Go to [API quickstart for agents](https://developer.harness.io/artifact-registry/3.0/agents/api-quickstart-for-agents.md) for the full per-format command reference.

***

## REST management API

Use the REST management API for operations that package manager clients do not cover, such as listing registries, querying artifact metadata, or deleting a version programmatically.

Base URL: `https://app.harness.io/har/api/v1`

All requests: `x-api-key: $HARNESS_API_KEY`

### Key endpoints

```bash
# List all registries in the account
GET /registry?accountIdentifier=<ID>

# Get a single registry
GET /registry/{registryRef}

# Create a registry
POST /registry
# Body: {"identifier":"<name>","packageType":"<type>","config":{"type":"VIRTUAL"}}

# List artifacts in a registry
GET /artifact?accountIdentifier=<ID>&registryIdentifier=<REGISTRY>

# Get artifact metadata
GET /artifact/{artifactName}?accountIdentifier=<ID>&registryIdentifier=<REGISTRY>

# List versions of an artifact
GET /artifact/{artifactName}/version?accountIdentifier=<ID>&registryIdentifier=<REGISTRY>

# Get version details (digest, size, vulnerability summary)
GET /artifact/{artifactName}/version/{version}?accountIdentifier=<ID>&registryIdentifier=<REGISTRY>

# Delete an artifact version
DELETE /artifact/{artifactName}/version/{version}?accountIdentifier=<ID>&registryIdentifier=<REGISTRY>
```

**Copy-paste examples**:

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

# List artifacts in a registry
curl -s \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://app.harness.io/har/api/v1/artifact?accountIdentifier=$HARNESS_ACCOUNT_ID&registryIdentifier=$HAR_REGISTRY" \
  | jq '.data.artifacts[] | {name: .name, latest: .latestVersion}'

# Get version details
curl -s \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://app.harness.io/har/api/v1/artifact/$ARTIFACT/version/$VERSION?accountIdentifier=$HARNESS_ACCOUNT_ID&registryIdentifier=$HAR_REGISTRY" \
  | jq '{digest: .data.digest, size: .data.size}'
```

Go to [REST API reference](https://developer.harness.io/artifact-registry/3.0/reference/rest-api.md) for all endpoints and schemas.

***

## Supported formats

26 formats across 12 ecosystems:

| Ecosystem                  | Formats                                                                    |
| -------------------------- | -------------------------------------------------------------------------- |
| Container                  | Docker, Helm OCI, Helm HTTP                                                |
| Java Virtual Machine (JVM) | Maven, Gradle                                                              |
| JavaScript                 | npm                                                                        |
| Python                     | Python / PyPI                                                              |
| .NET                       | NuGet                                                                      |
| Rust                       | Cargo                                                                      |
| Go                         | Go modules                                                                 |
| AI / ML                    | Hugging Face                                                               |
| Infrastructure             | Terraform modules, Terraform Backend                                       |
| OS packages                | RPM, Debian / APT, Alpine / APK, Wolfi / APK                               |
| Languages                  | PHP Composer, Dart, Swift, Ruby / RubyGems, R / CRAN, Conan, Conda, Puppet |
| Generic                    | Generic / Raw                                                              |

Go to [Supported formats](https://developer.harness.io/artifact-registry/3.0/get-started/supported-formats.md) for the full list including GA status.

***

## Patterns for AI agents

### Storing build outputs

An agent that generates and builds code can push build artifacts directly to Harness Artifacts:

```bash
# After building a Docker image
docker build -t my-app:$VERSION .
docker tag my-app:$VERSION "pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/my-app:$VERSION"
docker push "pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/my-app:$VERSION"

# Store the version identifier for later retrieval
echo "pkg.harness.io/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/my-app:$VERSION"
```

### Checking before building

Before triggering a build, check if the artifact already exists in the registry:

```bash
EXISTS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://app.harness.io/har/api/v1/artifact/my-app/version/$VERSION?accountIdentifier=$HARNESS_ACCOUNT_ID&registryIdentifier=$HAR_REGISTRY")

if [ "$EXISTS" = "200" ]; then
  echo "Version $VERSION already in registry. Skipping build"
else
  echo "Building version $VERSION"
fi
```

### Storing and retrieving model weights

For Hugging Face format registries, set `HF_ENDPOINT` to route model downloads through Artifacts:

```bash
export HF_ENDPOINT="https://pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/huggingface"
export HF_TOKEN="$HARNESS_API_KEY"
# huggingface_hub and transformers use HF_ENDPOINT automatically
python -c "from transformers import AutoModel; AutoModel.from_pretrained('org/model')"
```

This routes model downloads through your Artifacts registry, enabling offline environments, caching, and version pinning for model weights.

### Routing package dependencies through Artifacts

Point package managers at Artifacts to route all dependency resolution through your registry (useful for supply-chain control):

```bash
# npm: all packages resolved through Artifacts upstream proxy
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"

# Python: pip resolves through Artifacts upstream proxy
pip config set global.index-url \
  "https://_token:$HARNESS_API_KEY@pkg.harness.io/pkg/$HARNESS_ACCOUNT_ID/$HAR_REGISTRY/python/simple"
```

An upstream proxy registry forwards requests for packages not yet in Artifacts to the configured public registry (npm, PyPI, and other package registries) and caches them on first pull.

### Querying what is available

```bash
# Find the latest version of an artifact
curl -s \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://app.harness.io/har/api/v1/artifact/$ARTIFACT?accountIdentifier=$HARNESS_ACCOUNT_ID&registryIdentifier=$HAR_REGISTRY" \
  | jq '.data.latestVersion'

# List all versions
curl -s \
  -H "x-api-key: $HARNESS_API_KEY" \
  "https://app.harness.io/har/api/v1/artifact/$ARTIFACT/version?accountIdentifier=$HARNESS_ACCOUNT_ID&registryIdentifier=$HAR_REGISTRY" \
  | jq '.data.versions[].name'
```

***

## HTTP status codes

Every REST and package manager call returns one of these codes; match it here to decide the next action.

| Code  | Meaning                  | Action                                                                      |
| ----- | ------------------------ | --------------------------------------------------------------------------- |
| `200` | OK                       | None                                                                        |
| `401` | Bad or missing token     | Check `$HARNESS_API_KEY`; regenerate if expired                             |
| `403` | Insufficient permissions | Add `Artifact Registries: Pull` or `Push` permission to the service account |
| `404` | Resource not found       | Check `$HAR_REGISTRY`, `$HARNESS_ACCOUNT_ID`, artifact name, and version    |
| `409` | Already exists           | Use a new version tag, or delete the existing version first                 |
| `413` | Payload too large        | Generic registry max is 5 TiB per file                                      |
| `429` | Rate limit exceeded      | Back off and retry; limit is 1,000 requests/min per API key                 |

***

## Next steps

* [Authentication for agents](https://developer.harness.io/artifact-registry/3.0/agents/authentication-for-agents.md): service account setup, token rotation, Kubernetes `imagePullSecrets`
* [API quickstart for agents](https://developer.harness.io/artifact-registry/3.0/agents/api-quickstart-for-agents.md): full per-format push/pull commands
* [Automate with Terraform](https://developer.harness.io/artifact-registry/3.0/agents/automate-with-terraform.md): provision registries and upstream proxies as code
* [REST API reference](https://developer.harness.io/artifact-registry/3.0/reference/rest-api.md): full OpenAPI specification
* [CLI reference](https://developer.harness.io/artifact-registry/3.0/reference/cli.md): `hc` CLI command reference
* [Supported formats](https://developer.harness.io/artifact-registry/3.0/get-started/supported-formats.md): complete format and GA status list

{% @harness-feedback/feedback %}
