---
title: "Upload a container image archive for scanning"
method: POST
path: "/api/v2/containerScans/uploadArchive"
tags: ["Container Scanning"]
---

# Upload a container image archive for scanning

`POST /api/v2/containerScans/uploadArchive`

## Request

- Base URL: `https://zeropath.com`
- URL: `https://zeropath.com/api/v2/containerScans/uploadArchive`
- Auth: API key in header `X-ZeroPath-API-Token-Id` and API key in header `X-ZeroPath-API-Token-Secret`

Upload a container image tarball / OCI archive (for air-gapped images that cannot be pulled from a registry) in chunks, then enqueue a scan. Send chunks in chunkIndex order; chunk 0 returns a server-assigned fileId and the resolved repositoryId to echo on later chunks. On the final chunk the assembled archive is staged and the response carries the tracked containerImageId; poll containerImages.get on it (its `queued` flag and `latestScan`) to follow progress. If repositoryId is omitted, an ephemeral standalone repository is created/reused for the image.

## Request body

- ContainerScanUploadArchiveRequest: Input for one chunk of a chunked container-image-archive upload (tarball / OCI archive) for air-gapped images. Send chunks in chunkIndex order: chunk 0 omits fileId and (when no repositoryId is given) repositoryId; the response returns the server-assigned fileId and the resolved repositoryId, which must be echoed on every subsequent chunk.
  - `organizationId` string: Organization that owns the image. If omitted, resolved from auth context.
  - `repositoryId` string: Existing repository to attach the image to. If omitted, an ephemeral standalone repository is created/reused on the first chunk and returned for reuse on later chunks.
  - `imageLabel` string, required: Display name for the uploaded image; stored as the image reference.
  - `chunk` string, required: Base64-encoded slice of the archive file.
  - `chunkIndex` number, required: Zero-based index of this chunk.
  - `totalChunks` number, required: Total number of chunks in the upload.
  - `fileId` string: Server-assigned upload id from the first chunk’s response; required on every chunk after the first.

## Response `200`

Chunk accepted (and, on the final chunk, scan enqueued)

- ContainerScanUploadArchiveResponse: Result of uploading one archive chunk. containerImageId is non-null only on the final chunk, once the assembled archive has been staged for scanning.
  - `fileId` string, required: Upload id to pass on subsequent chunks.
  - `repositoryId` string, required: Resolved repository id; pass it back on subsequent chunks.
  - `containerImageId` string, nullable, required: ID of the tracked container image whose scan was enqueued. Null until the final chunk; poll containerImages.get on it once set.

## Other responses

- `400`: Error Response
- `401`: Error Response
- `403`: Error Response

---

[API](https://skmtc.dev/zeropath/apis/zeropath-api.md) - [All operations](https://skmtc.dev/zeropath/apis/zeropath-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zeropath/apis/zeropath-api/revisions/126e9c80ba0d?raw)