Documentación La API de scancontainer

Lanza análisis y lee informes desde tus propias herramientas. La API está incluida en el plan Fleet.

Lo básico

  • Todas las peticiones van por HTTPS y todas las respuestas son JSON, salvo las descargas.
  • Envía tu token de acceso en la cabecera Authorization.
  • Las horas van en UTC, en ISO 8601.
export SC_TOKEN="your access token"

curl https://platform.scancontainer.com/api/v1/usage \
  -H "Authorization: Bearer $SC_TOKEN"

Endpoints

PeticiónQué hace
POST /scansLanza un análisis.
GET /scans/{id}Devuelve el estado de un análisis.
GET /reportsLista tus informes, del más reciente al más antiguo.
GET /reports/{id}Devuelve un informe en JSON.
GET /reports/{id}/download?format=pdfDescarga un informe en el formato que pidas.
DELETE /reports/{id}Borra un informe de forma definitiva.
GET /usageDevuelve los análisis usados y los que quedan este mes.

Todas las rutas empiezan por https://platform.scancontainer.com/api/v1.

Lanzar un análisis

curl -X POST https://platform.scancontainer.com/api/v1/scans \
  -H "Authorization: Bearer $SC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image": "nginx:latest"}'
{
  "id": "s_2b9f4c",
  "status": "queued",
  "report": null
}

Una imagen privada funciona cuando su registro está conectado en tu cuenta. Para analizar un fichero de tu máquina, usa la línea de comandos.

Esperar el resultado

Consulta el análisis hasta que su estado sea done. El estado es uno de estos: queued, running, done o failed.

curl https://platform.scancontainer.com/api/v1/scans/s_2b9f4c \
  -H "Authorization: Bearer $SC_TOKEN"
{
  "id": "s_2b9f4c",
  "status": "done",
  "report": "r_8f3k2a"
}

Leer un informe

curl https://platform.scancontainer.com/api/v1/reports/r_8f3k2a \
  -H "Authorization: Bearer $SC_TOKEN"
{
  "id": "r_8f3k2a",
  "target": "myapp:1.4",
  "created": "2026-11-17T10:42:00Z",
  "verdict": "almost_ready",
  "findings": {"critical": 0, "high": 2, "medium": 0, "low": 14},
  "fix_first": [
    {"title": "Update the base image", "fix": "FROM node:22-alpine"}
  ],
  "url": "https://platform.scancontainer.com/reports/r_8f3k2a"
}
CampoQué contiene
idEl ID del informe.
targetLo que se analizó.
createdCuándo terminó el análisis.
verdictready, almost_ready o not_ready.
findingsCuántos hallazgos hay en cada nivel.
fix_firstLos arreglos por orden de importancia. El informe completo añade la prueba de cada uno.
urlEl informe en tu cuenta.

Listar tus informes

curl "https://platform.scancontainer.com/api/v1/reports?limit=20&target=myapp:1.4" \
  -H "Authorization: Bearer $SC_TOKEN"
ParámetroQué hace
limitCuántos informes devolver. De 1 a 100. Por defecto, 20.
targetDevuelve solo los informes de una imagen.
cursorContinúa desde el next_cursor de la respuesta anterior.
{
  "reports": [
    {"id": "r_8f3k2a", "target": "myapp:1.4", "created": "2026-11-17T10:42:00Z", "verdict": "almost_ready"}
  ],
  "next_cursor": null
}

Descargar un informe

curl -L "https://platform.scancontainer.com/api/v1/reports/r_8f3k2a/download?format=pdf" \
  -H "Authorization: Bearer $SC_TOKEN" \
  -o report.pdf
FormatoQué te da
pdfEl informe como documento para enviar o archivar.
htmlEl informe como una sola página que se abre en cualquier navegador.
jsonTodos los hallazgos como datos, para tus propias herramientas.
sarifLos hallazgos para el análisis de código de GitHub, GitLab y Azure DevOps.
cyclonedxEl SBOM en CycloneDX.
spdxEl SBOM en SPDX.
openvexLa declaración VEX en OpenVEX.
cyclonedx-vexLa declaración VEX en CycloneDX VEX.
csafLa declaración VEX en CSAF.

Errores

EstadoSignificado
400La petición no es válida. El mensaje dice qué campo está mal.
401Falta el token de acceso, es incorrecto o está revocado.
403Tu plan no incluye lo que has pedido.
404No hay ningún análisis ni informe con ese ID en tu cuenta.
429Se ha alcanzado el límite de tu plan, o se han enviado demasiadas peticiones a la vez.
{
  "error": {
    "code": "limit_reached",
    "message": "The monthly scans of your plan are used up."
  }
}

Cuando la respuesta sea 429, espera los segundos que indica la cabecera Retry-After antes de volver a intentarlo.

Un ejemplo completo en Python

Lanza un análisis, espera el resultado y guarda el informe en PDF.

import os, time, requests

API = "https://platform.scancontainer.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["SC_TOKEN"]}

scan = requests.post(API + "/scans", headers=HEADERS, json={"image": "nginx:latest"}).json()

while scan["status"] in ("queued", "running"):
    time.sleep(5)
    scan = requests.get(API + "/scans/" + scan["id"], headers=HEADERS).json()

report = requests.get(API + "/reports/" + scan["report"], headers=HEADERS).json()
print(report["verdict"], report["url"])

pdf = requests.get(API + "/reports/" + scan["report"] + "/download", headers=HEADERS, params={"format": "pdf"})
open("report.pdf", "wb").write(pdf.content)

Versiones

La versión forma parte de la ruta. Un cambio que rompería las llamadas existentes sale con una versión nueva, y la anterior sigue funcionando.

Escanea la tuya antes del próximo despliegue.