Documentation The scancodebase 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.scancodebase.com/api/v1/usage \
  -H "Authorization: Bearer $SC_TOKEN"

Endpoints

RequestWhat it does
POST /scansStarts a scan.
GET /scans/{id}Returns the state of a scan.
GET /reportsLists your reports, newest first.
GET /reports/{id}Returns one report as JSON.
GET /reports/{id}/download?format=pdfDownloads one report in the format you ask for.
DELETE /reports/{id}Deletes one report for good.
GET /usageReturns the scans used and left this month.

All paths start with https://platform.scancodebase.com/api/v1.

Start a scan

curl -X POST https://platform.scancodebase.com/api/v1/scans \
  -H "Authorization: Bearer $SC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repository": "https://github.com/you/myapp", "ref": "main"}'
{
  "id": "s_2b9f4c",
  "status": "queued",
  "report": null
}

A private repository works once your code platform 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.scancodebase.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.scancodebase.com/api/v1/reports/r_8f3k2a \
  -H "Authorization: Bearer $SC_TOKEN"
{
  "id": "r_8f3k2a",
  "target": "myapp",
  "created": "2026-11-17T10:42:00Z",
  "verdict": "almost_ready",
  "findings": {"critical": 1, "high": 2, "medium": 0, "low": 31},
  "fix_first": [
    {"title": "Fix the query in users.js", "fix": "db.query('SELECT * FROM users WHERE id = ?', [id])"}
  ],
  "url": "https://platform.scancodebase.com/reports/r_8f3k2a"
}
FieldWhat it holds
idThe ID of the report.
targetWhat was scanned.
createdWhen the scan finished.
verdictready, almost_ready or not_ready.
findingsHow many findings there are at each level.
fix_firstThe fixes in order of importance. The full report adds the proof for each one.
urlThe report in your account.

List your reports

curl "https://platform.scancodebase.com/api/v1/reports?limit=20&target=myapp" \
  -H "Authorization: Bearer $SC_TOKEN"
ParameterWhat it does
limitHow many reports to return. From 1 to 100. The default is 20.
targetReturns only the reports of one repository.
cursorContinues from the next_cursor of the previous answer.
{
  "reports": [
    {"id": "r_8f3k2a", "target": "myapp", "created": "2026-11-17T10:42:00Z", "verdict": "almost_ready"}
  ],
  "next_cursor": null
}

Download a report

curl -L "https://platform.scancodebase.com/api/v1/reports/r_8f3k2a/download?format=pdf" \
  -H "Authorization: Bearer $SC_TOKEN" \
  -o report.pdf
FormatWhat you get
pdfThe report as a document to send or file.
htmlThe report as a single page that opens in any browser.
jsonEvery finding as data, for your own tools.
sarifFindings for GitHub, GitLab and Azure DevOps code scanning.

Errors

StatusMeaning
400The request is not valid. The message says which field is wrong.
401The access token is missing, wrong or revoked.
403Your plan does not include what you asked for.
404There is no scan or report with that ID in your account.
429The 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.scancodebase.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["SC_TOKEN"]}

scan = requests.post(API + "/scans", headers=HEADERS, json={"repository": "https://github.com/you/myapp", "ref": "main"}).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.

Scan yours before the next merge.