// interfaces

Images

[ view markdown ]

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.