> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Configure monitored AWS and GCP images, inspect advisories, and manage image validation reports through REST and MCP.

# Images


The Images API uses the same organization bearer API keys and `/api/v1` base URL as
other [REST endpoints](https://www.superagent.sh/docs/api). The key selects the organization; do not send
an organization ID. MCP exposes matching tools through the [Superagent MCP server](https://www.superagent.sh/docs/mcp).

## Connections and monitored images

Create or rotate AWS/GCP credentials in **Integrations** first. Public REST and MCP
can discover existing connections and repositories but never return registry keys.

| Method | Path | MCP tool |
| --- | --- | --- |
| GET | `/image-connections` | `list_image_connections` |
| GET | `/image-connections/{connection_id}/repositories` | `discover_images` |
| GET | `/images` | `list_images` |
| POST | `/images` | `create_image` |
| GET | `/images/{image_id}` | `get_image` |
| PATCH | `/images/{image_id}` | `update_image` |
| DELETE | `/images/{image_id}` | `delete_image` |
| GET | `/images/{image_id}/versions` | `list_image_versions` |
| GET | `/images/{image_id}/advisories` | `list_image_advisories` |
| POST | `/images/{image_id}/refresh` | `refresh_image` |

Discover repositories using an existing connection, then pass an exact returned
`name` to create an image. An image resource represents monitoring for a registry
repository; its versions identify individual immutable digests.

```bash
export SUPERAGENT_API_URL=https://superagent.sh/api/v1

curl "$SUPERAGENT_API_URL/image-connections" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"

curl "$SUPERAGENT_API_URL/image-connections/$CONNECTION_ID/repositories" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"

curl "$SUPERAGENT_API_URL/images" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "00000000-0000-4000-8000-000000000001",
    "name": "production-images",
    "tracked_tags": ["latest"],
    "auto_validate": false,
    "max_runs_per_day": 5,
    "environment": {"port": 80, "health_path": "/"}
  }'
```

Creation returns `201` with `{ "data": { ...image } }` and queues its first import.
An already-monitored repository keeps its identifier; provided settings are applied.
An archived repository can be added again using the existing connection.

`GET /images` supports `connection_id` and `q` (name search). Image, version,
advisory, report, and event lists accept `limit` (1–100, default 25) and `offset`
(default 0), and return `data` plus `pagination` containing `limit`, `offset`,
`total`, and `has_more`. Connection/discovery endpoints return an unpaginated
`data` array; MCP wraps their arrays in `data` as well.

## Configure an existing image

PATCH updates only supplied settings. Omitted settings and variables are preserved.
`environment.health_path` is the public API spelling; the dashboard JSON editor
uses `healthPath`.

```bash
curl -X PATCH "$SUPERAGENT_API_URL/images/$IMAGE_ID" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environment": {"port": 80, "health_path": "/"}}'
```

Environment fields are `port`, `health_path`, `command` (argument array), `variables`
(string map), and `services` (array of `name`, digest-pinned `image`, and optional
`variables`). Providing `variables` replaces that complete map; use `{}` to clear it.
Providing `services` replaces the service list; omitted variables for a retained
service name are preserved. Use `[]` to remove services or clear a command override.

Public reads expose `variable_names`, never variable values. Values remain encrypted
at rest. The dashboard's owner-only saved-settings editor is separate from public
API reads. Changes apply to future runs; existing runs keep their pinned environment.

Setting `auto_validate: true` authorizes billable validations of tracked image tags
within `max_runs_per_day` (1–100). Registry findings are refreshed about hourly in
production. New image digests, changed advisory revisions, and changed test
environments can trigger another validation; unchanged inputs are deduplicated.
See [Image Validation](https://www.superagent.sh/docs/products/image-validation) for scanner prerequisites.

## Versions, advisories, and refresh

Request a refresh with `POST /images/{image_id}/refresh` (`202`). It is asynchronous;
the scheduler retries dispatch failures. Poll the image's `last_synced_at`, versions,
and advisories. With automation enabled, a refresh can start billable validations.

The versions endpoint returns IDs, digests, tags, platform and scanner status.
Advisory filters are `version_id`, `severity`, `exposure`, and `q` (CVE, package or
summary). Exposure values are `unvalidated`, `exploitable`, `not_applicable`, and
`inconclusive`. Assessments only apply when the advisory revision and environment
still match. Incomplete or stale scanner observations are excluded, rather than
presented as current findings or evidence that an image is clean.

## Start and inspect a validation

```bash
curl "$SUPERAGENT_API_URL/reports/image" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version_id": "00000000-0000-4000-8000-000000000002",
    "idempotency_key": "00000000-0000-4000-8000-000000000003",
    "target_keys": []
  }'
```

Creation returns `202` and a report with `type: "image"`. Reuse the same UUID
`idempotency_key` when retrying the same request; changing the request under the
same key returns `409`. Retries return the original report, including after it
finishes, without admitting or billing another run.

Supply `candidate_version_id` to test a replacement from the same repository.
Omit it for exposure validation only. Omit `target_keys`, or pass `[]`, to test all
current active advisories (1–100); otherwise use the keys from the advisories list.
Runs use the existing billing, daily limit, and organization concurrency limit.
Only Linux amd64 versions with usable current cloud scan results are accepted.

| Method | Path | MCP tool |
| --- | --- | --- |
| POST | `/reports/image` | `create_image_report` |
| GET | `/reports?type=image&image_id={image_id}` | `list_reports` |
| GET | `/reports/{report_id}` | `get_report` |
| GET | `/reports/{report_id}/events` | `list_image_report_events` |
| POST | `/reports/{report_id}/cancel` | `cancel_image_report` |
| DELETE | `/reports/{report_id}` | `delete_image_report` |

Image status is `queued`, `provisioning`, `running`, `completed`, `failed`, or
`cancelled`. Poll `stage` and the events endpoint for progress. Events are ordered
oldest first. A completed report contains advisory assessments, reproduction
evidence, exposure and fix outcomes, and verification gaps; completion alone does
not establish that an image is safe. Image reports do not have an editable review
status. The cancel, delete, and events operations above currently support image
reports only.

`DELETE /images/{image_id}` removes monitoring and cancels active runs while
preserving historical reports and the image in AWS/GCP. Deleting a report cancels
active work, cleans up the sandbox, and removes its execution events. If cleanup
is unavailable, the report is retained for a safe retry.

Subscribe to `image_validation.finished` with the `image` source for terminal
notifications. See [webhooks](https://www.superagent.sh/docs/webhooks) and the [OpenAPI specification](https://www.superagent.sh/openapi/v1.yaml)
for response schemas. API errors use the normal `{ "error": { "code", "message" } }`
envelope; cross-organization resource IDs return `404`.

---
Source: https://www.superagent.sh/docs/api/images
Index: https://www.superagent.sh/llms.txt
