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

# Submit a container image for scanning

`POST /api/v2/containerScans/submit`

## Request

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

Submit a container image (by registry reference, e.g. "ghcr.io/acme/api:1.4") for vulnerability scanning. If repositoryId is omitted, an ephemeral standalone repository is created/reused for the image. Returns the tracked containerImageId; poll containerImages.get on it (its `queued` flag and `latestScan`) to follow progress. Resubmitting the same image enqueues another scan.

## Request body

- ContainerScanSubmitRequest: Input for submitting a container image to be scanned.
  - `organizationId` string: Organization that owns the image. If omitted, resolved from auth context.
  - `imageRef` string, required: Full image reference to scan, e.g. "ghcr.io/acme/api:1.4".
  - `repositoryId` string: Existing repository to attach the image to. If omitted, an ephemeral standalone repository is created/reused.
  - `registryUsername` string: Optional username for pulling a private image. Stored in plaintext alongside the encrypted token. Requires registryToken to also be set.
  - `registryToken` string: Token/password for pulling a private image. Encrypted at rest and NEVER returned in any response. Omit for anonymous pulls.
  - `registryConnectionId` string: ID of an org-level registry connection to pull with (the reusable alternative to inline credentials). Must belong to the caller's organization, and the image reference's host must match the connection's registry host. Mutually exclusive with registryUsername/registryToken and clearRegistryAuth; linking a connection clears any inline credentials stored on the image.
  - `clearRegistryAuth` boolean: Clear any stored private-registry credentials on this image — inline credentials and any linked registry connection — reverting it to an anonymous pull. Cannot be combined with registryUsername/registryToken or registryConnectionId. Without this flag, submit only ever overwrites credentials, never removes them.
  - `monitoringCrontab` string, nullable: Cron expression to enable recurring monitoring on this (registry) image as part of the same submit, e.g. "0 0 * * 1". Three states: a string sets the schedule, an explicit null clears it, and omitting the field leaves any existing schedule unchanged. Only valid for registry images (uploaded archives cannot be monitored).

## Response `200`

Scan enqueued

- ContainerScanSubmitResponse
  - `containerImageId` string, required: ID of the tracked container image whose scan was enqueued. Poll containerImages.get on it.

## Other responses

- `400`: Error Response
- `401`: Error Response
- `403`: Error Response
- `429`: 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)