Documentation The scancontainer API
Start scans and read reports from your own tools. The API is included in the Fleet plan.
The basics
- Every request goes over HTTPS and every answer is JSON, except downloads.
- Send your access token in the Authorization header.
- Times are in UTC, in ISO 8601.
export SC_TOKEN="your access token"
curl https://platform.scancontainer.com/api/v1/usage \
-H "Authorization: Bearer $SC_TOKEN"Endpoints
| Request | What it does |
|---|---|
POST /scans | Starts a scan. |
GET /scans/{id} | Returns the state of a scan. |
GET /reports | Lists your reports, newest first. |
GET /reports/{id} | Returns one report as JSON. |
GET /reports/{id}/download?format=pdf | Downloads one report in the format you ask for. |
DELETE /reports/{id} | Deletes one report for good. |
GET /usage | Returns the scans used and left this month. |
All paths start with https://platform.scancontainer.com/api/v1.
Start a scan
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
}
A private image works once its registry is connected in your account. To scan a file from your machine, use the command line.
Wait for the result
Ask for the scan until its status is done. The status is one of queued, running, done or failed.
curl https://platform.scancontainer.com/api/v1/scans/s_2b9f4c \
-H "Authorization: Bearer $SC_TOKEN"{
"id": "s_2b9f4c",
"status": "done",
"report": "r_8f3k2a"
}
Read a report
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"
}
| Field | What it holds |
|---|---|
id | The ID of the report. |
target | What was scanned. |
created | When the scan finished. |
verdict | ready, almost_ready or not_ready. |
findings | How many findings there are at each level. |
fix_first | The fixes in order of importance. The full report adds the proof for each one. |
url | The report in your account. |
List your reports
curl "https://platform.scancontainer.com/api/v1/reports?limit=20&target=myapp:1.4" \
-H "Authorization: Bearer $SC_TOKEN"| Parameter | What it does |
|---|---|
limit | How many reports to return. From 1 to 100. The default is 20. |
target | Returns only the reports of one image. |
cursor | Continues from the next_cursor of the previous answer. |
{
"reports": [
{"id": "r_8f3k2a", "target": "myapp:1.4", "created": "2026-11-17T10:42:00Z", "verdict": "almost_ready"}
],
"next_cursor": null
}
Download a report
curl -L "https://platform.scancontainer.com/api/v1/reports/r_8f3k2a/download?format=pdf" \
-H "Authorization: Bearer $SC_TOKEN" \
-o report.pdf| Format | What you get |
|---|---|
pdf | The report as a document to send or file. |
html | The report as a single page that opens in any browser. |
json | Every finding as data, for your own tools. |
sarif | Findings for GitHub, GitLab and Azure DevOps code scanning. |
cyclonedx | The SBOM in CycloneDX. |
spdx | The SBOM in SPDX. |
openvex | The VEX statement in OpenVEX. |
cyclonedx-vex | The VEX statement in CycloneDX VEX. |
csaf | The VEX statement in CSAF. |
Errors
| Status | Meaning |
|---|---|
400 | The request is not valid. The message says which field is wrong. |
401 | The access token is missing, wrong or revoked. |
403 | Your plan does not include what you asked for. |
404 | There is no scan or report with that ID in your account. |
429 | The limit of your plan was reached, or too many requests were sent at once. |
{
"error": {
"code": "limit_reached",
"message": "The monthly scans of your plan are used up."
}
}
When the answer is 429, wait the number of seconds given in the Retry-After header before you try again.
A complete example in Python
It starts a scan, waits for the result and saves the report as 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)Versions
The version is part of the path. A change that would break existing calls gets a new version, and the previous one keeps working.