// interfaces
Images
Configure monitored AWS and GCP images, inspect advisories, and manage image validation reports through REST and MCP.
The Images API uses the same organization bearer API keys and /api/v1 base URL as
other REST endpoints. The key selects the organization; do not send
an organization ID. MCP exposes matching tools through the Superagent MCP server.
Connections and monitored images
Connect an AWS role or configure AWS/GCP keys 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.
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.
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.
The dashboard accepts exact tags and wildcards in one Tracked tags field. Adding the first wildcard defaults Newest versions to 1; this limit is always visible and can be adjusted to 20. REST and MCP keep the explicit settings below.
Tracking settings are tracked_tags (up to 20 exact tags), tag_patterns (up to
20 simple case-sensitive globs using * and ?), and newest_versions (1–20, or
null to disable dynamic selection). Exact tags are unioned with the newest N
unique supported image versions matching any pattern. With no patterns, all tagged
versions are eligible, including commit-SHA tags. Empty tracked_tags and
tag_patterns with newest_versions: null pause tracking; save this state with
auto_validate: false. Patterns require newest_versions. Omitted settings are
preserved on PATCH. New images default to latest unless newest-N is specified.
{
"tracked_tags": [],
"tag_patterns": ["staging-*"],
"newest_versions": 3,
"auto_validate": false
}Save changed tracking rules with auto_validate: false; changing rules while
requesting enabled automation returns 409. Saving settings automatically queues a
registry refresh. Wait for it to complete, then read
selected_versions using GET /images/{image_id} or MCP get_image to review the
selected tags and immutable digests. selection_revision must match
tracking_revision; selection_synced_at records the completed refresh. Only then
PATCH auto_validate: true. Enabling requires a nonempty, successful selection
less than 24 hours old. Future scheduled refreshes update this selection without
requiring another opt-in. Historical reports remain available when rules change.
Selection uses provider push/upload timestamps, descending, and source image URI ascending for ties. Multi-platform aliases resolve to Linux amd64 digests and count once toward N. Discovery is bounded to 10,000 records/100 pages per provider list; at most 80 dynamic candidates are prioritized within a 100-image import window. If that window cannot produce N distinct supported versions while more candidates exist, the refresh fails without admitting automatic work. Narrow the pattern to recover. See selection rules for details.
Setting auto_validate: true authorizes billable validations of selected image versions
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.
Tracking and refreshes do not consume credits; each admitted validation uses 5 credits.
The daily limit, organization concurrency limit, and admission idempotency apply
to exact and dynamic selection alike.
See 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, provider push/upload
time (pushed_at), 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
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 and the OpenAPI specification
for response schemas. API errors use the normal { "error": { "code", "message" } }
envelope; cross-organization resource IDs return 404.