// 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
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.
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.
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 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
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.