REST API
To get started with the REST API, visit the projects’ API endpoint at http://localhost/api/projects/ or http://localhost:8001/api/projects/ if you run on a local development setup.
Authentication
When the authentication setting SCANCODEIO_REQUIRE_AUTHENTICATION
is enabled on a ScanCode.io instance (disabled by default), you will have to include
an authentication token API key
in the Authorization HTTP header of each request.
The key should be prefixed by the string literal “Token” with whitespace separating the two strings. For example:
Authorization: Token abcdef123456
Warning
Your API key is like a password and should be treated with the same care.
Example of a cURL-style command line using an API Key for authentication:
curl -X GET http://localhost/api/projects/ -H "Authorization:Token abcdef123456"
Example of a Python script:
import requests
api_url = "http://localhost/api/projects/"
headers = {
"Authorization": "Token abcdef123456",
}
params = {
"page": "2",
}
response = requests.get(api_url, headers=headers, params=params)
response.json()
Project list
An API endpoint that provides the ability to list, get, and create projects.
GET /api/projects/
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"name": "alpine/httpie",
"url": "/api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/",
"uuid": "6461408c-726c-4b70-aa7a-c9cc9d1c9685",
"created_date": "2021-07-27T08:43:06.058350+02:00",
"next_run": null,
"runs": []
}
]
}
The project list can be filtered by name
, uuid
, and is_archived
fields.
For example:
api_url="http://localhost/api/projects/"
content_type="Content-Type: application/json"
payload="name=project_name"
curl -X GET "$api_url?$payload" -H "$content_type"
Create a project
Using cURL:
api_url="http://localhost/api/projects/"
content_type="Content-Type: application/json"
data='{
"name": "project_name",
"input_urls": "https://download.url/package.archive",
"pipeline": "scan_single_package",
"execute_now": true
}'
curl -X POST "$api_url" -H "$content_type" -d "$data"
Note
To upload a file as the input of the project, you have to use the cURL “form emulation” mode with the following syntax:
api_url="http://localhost/api/projects/"
upload_file="/path/to/the/archive.zip"
curl -F "name=project_name" \
-F "pipeline=scan_single_package" \
-F "execute_now=True" \
-F "upload_file=@$upload_file" \
"$api_url"
Tip
To upload more than one file, you can use the Add input endpoint of the project.
Tip
To tag the upload_file
, you can provide the tag value using the
upload_file_tag
field.
Tip
You can declare multiple pipelines to be executed at the project creation using a list of pipeline names:
"pipeline": ["scan_single_package", "scan_for_virus"]
Tip
Use the “pipeline_name:option1,option2” syntax to select optional steps:
"pipeline": "map_deploy_to_develop:Java,JavaScript"
Using Python and the “requests” library:
import requests
api_url = "http://localhost/api/projects/"
data = {
"name": "project_name",
"input_urls": "https://download.url/package.archive",
"pipeline": "scan_single_package",
"execute_now": True,
}
response = requests.post(api_url, data=data)
response.json()
Note
To upload a file as the input of the project, you have to provide the files
argument to the requests.post
call:
import requests
api_url = "http://localhost/api/projects/"
data = {
"name": "project_name",
"pipeline": "scan_single_package",
"execute_now": True,
}
files = {"upload_file": open("/path/to/the/archive.zip", "rb")}
response = requests.post(api_url, data=data, files=files)
response.json()
You have the flexibility to explicitly set the filename, content_type, and headers for your uploaded files using the following code:
files = {"upload_file": ("inventory.json", file_contents, "application/json")}
For more information on this topic, refer to the following link: https://docs.python-requests.org/en/latest/user/quickstart/#post-a-multipart-encoded-file
When creating a project, the response will include the project’s details URL value among the returned data. You can make a GET request to this URL, which returns all available information about the project, including the status of any pipeline run:
{
"name": "project_name",
"url": "/api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/",
"uuid": "6461408c-726c-4b70-aa7a-c9cc9d1c9685",
"created_date": "2021-07-21T16:06:29.132795+02:00"
}
Adding webhooks
When creating a project, you can also register webhook subscriptions that will notify external services about pipeline execution events.
- You can either provide:
A single webhook URL using the
webhook_url
field.A list of detailed webhook configurations using the
webhooks
field.
- Webhook fields:
webhook_url
(string, optional): A single webhook URL to be notified.webhooks
(list, optional): A list of webhook configurations.target_url
(string, required): The URL to which the webhook will send aPOST
request.trigger_on_each_run
(boolean, optional): Iftrue
, the webhook will be triggered after each individual pipeline run. Default isfalse
.include_summary
(boolean, optional): Iftrue
, the webhook payload will include the summary data of the pipeline execution. Default isfalse
.include_results
(boolean, optional): Iftrue
, the webhook payload will include the full results data of the pipeline execution. Default isfalse
.is_active
(boolean, optional): Iftrue
, the webhook is active and will be triggered when the specified conditions are met. Default istrue
.
Using cURL to register a webhook:
api_url="http://localhost/api/projects/"
content_type="Content-Type: application/json"
data='{
"name": "project_name",
"webhook_url": "https://example.com/webhook"
}'
curl -X POST "$api_url" -H "$content_type" -d "$data"
{
"name": "project_name",
"webhook_url": "https://example.com/webhook"
}
Using cURL to register multiple webhooks:
api_url="http://localhost/api/projects/"
content_type="Content-Type: application/json"
data='{
"name": "project_name",
"webhooks": [
{
"target_url": "https://example.com/webhook1",
"trigger_on_each_run": true,
"include_summary": false,
"include_results": true,
"is_active": true
},
{
"target_url": "https://example.com/webhook2",
"trigger_on_each_run": false,
"include_summary": true,
"include_results": false,
"is_active": true
}
]
}'
curl -X POST "$api_url" -H "$content_type" -d "$data"
Project details
The project details view returns all information available about a project.
GET /api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/
{
"name": "alpine/httpie",
"url": "/api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/",
"uuid": "6461408c-726c-4b70-aa7a-c9cc9d1c9685",
"created_date": "2021-07-27T08:43:06.058350+02:00",
"[...]": "[...]",
"codebase_resources_summary": {
"application-package": 1
},
"discovered_packages_summary": {
"total": 1,
"with_missing_resources": 0,
"with_modified_resources": 0
}
}
Managing projects
Multiple actions are available to manage projects:
Add input
This action adds provided input_urls
or upload_file
to the project
.
POST /api/projects/d4ed9405-5568-45ad-99f6-782a9b82d1d2/add_input/
- Data:
input_urls
: A list of URLs to downloadupload_file
: A file to uploadupload_file_tag
: An optional tag to add on the uploaded file
Using cURL to provide download URLs:
api_url="http://localhost/api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/add_input/"
content_type="Content-Type: application/json"
data='{
"input_urls": [
"https://github.com/aboutcode-org/debian-inspector/archive/refs/tags/v21.5.25.zip",
"https://github.com/package-url/packageurl-python/archive/refs/tags/0.9.4.tar.gz"
]
}'
curl -X POST "$api_url" -H "$content_type" -d "$data"
{
"status": "Input(s) added."
}
Using cURL to upload a local file:
api_url="http://localhost/api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/add_input/"
upload_file="/path/to/the/archive.zip"
curl -X POST "$api_url" -F "upload_file=@$upload_file"
{
"status": "Input(s) added."
}
Add pipeline
This action adds a selected pipeline
to the project
.
If the execute_now
value is True, the pipeline execution will start immediately
during the pipeline addition.
POST /api/projects/d4ed9405-5568-45ad-99f6-782a9b82d1d2/add_pipeline/
- Data:
pipeline
: The pipeline nameexecute_now
:true
orfalse
Tip
Use the “pipeline_name:option1,option2” syntax to select optional steps:
"pipeline": "map_deploy_to_develop:Java,JavaScript"
Using cURL:
api_url="http://localhost/api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/add_pipeline/"
content_type="Content-Type: application/json"
data='{
"pipeline": "analyze_docker_image",
"execute_now": true
}'
curl -X POST "$api_url" -H "$content_type" -d "$data"
{
"status": "Pipeline added."
}
Add webhook
This action adds a webhook subscription to the project
.
A webhook allows external services to receive real-time notifications about project
pipeline execution events.
POST /api/projects/d4ed9405-5568-45ad-99f6-782a9b82d1d2/add_webhook/
- Data:
target_url
(string, required): The URL to which the webhook will send aPOST
request when triggered.trigger_on_each_run
(boolean, optional): Iftrue
, the webhook will be triggered after each individual pipeline run. Default isfalse
.include_summary
(boolean, optional): Iftrue
, the webhook payload will include the summary data of the pipeline execution. Default isfalse
.include_results
(boolean, optional): Iftrue
, the webhook payload will include the full results data of the pipeline execution. Default isfalse
.is_active
(boolean, optional): Iftrue
, the webhook is active and will be triggered when the specified conditions are met. Default istrue
.
Using cURL:
api_url="http://localhost/api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/add_webhook/"
content_type="Content-Type: application/json"
data='{
"target_url": "https://example.com/webhook",
"trigger_on_each_run": true,
"include_summary": true,
"include_results": false,
"is_active": true
}'
curl -X POST "$api_url" -H "$content_type" -d "$data"
{
"status": "Webhook added."
}
Note
Webhooks will only be triggered for active subscriptions.
If
trigger_on_each_run
is set tofalse
, the webhook will only trigger after all pipeline runs are completed.The
include_summary
andinclude_results
fields allow customization of the webhook payload.
Archive
This action archive a project and remove selected work directories.
POST /api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/archive/
- Data:
remove_input
:true
remove_codebase
:true
remove_output
:false
{
"status": "The project project_name has been archived."
}
Compliance
This action returns a list of compliance alerts for a project,
filtered by severity level.
The severity level can be customized using the fail_level
query parameter.
Defaults to ERROR
if not provided.
GET /api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/compliance/?fail_level=WARNING
- Data:
fail_level
:ERROR
,WARNING
,MISSING
.
{
"compliance_alerts": {
"packages": {
"warning": [
"pkg:generic/package@1.0",
"pkg:generic/package@2.0"
],
"error": [
"pkg:generic/package@3.0"
]
}
}
}
Reset
This action will delete all related database entries and all data on disks except for the input/ directory.
POST /api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/reset/
{
"status": "All data, except inputs, for the project_name project have been removed."
}
Errors
This action lists all errors that were logged during any pipeline execution
on a given project
.
GET /api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/errors/
[
{
"uuid": "d4ed9405-5568-45ad-99f6-782a9b82d1d2",
"model": "CodebaseResource",
"[...]": "[...]",
"message": "ERROR: for scanner: packages:",
"created_date": "2021-04-27T22:38:30.762731+02:00"
}
]
File content
This displays the content of a project
file resource provided using the
?path=<resource_path>
argument.
GET /api/projects/d4ed9405-5568-45ad-99f6-782a9b82d1d2/file_content/?path=setup.py
{
"file_content": "#!/usr/bin/env python\n# -*- encoding: utf-8 -*-\n\n..."
}
Packages
Lists all packages
of a given project
.
GET /api/projects/d4ed9405-5568-45ad-99f6-782a9b82d1d2/packages/
[
{
"purl": "pkg:deb/debian/libdb5.3@5.3.28%2Bdfsg1-0.5?arch=amd64",
"type": "deb",
"namespace": "debian",
"name": "libdb5.3",
"version": "5.3.28+dfsg1-0.5",
"[...]": "[...]"
}
]
The list supports filtering by most fields using the ?field_name=value
query
parameter syntax.
Resources
This action lists all resources
of a given project
.
GET /api/projects/d4ed9405-5568-45ad-99f6-782a9b82d1d2/resources/
[
{
"for_packages": [
"pkg:deb/debian/bash@5.0-4?arch=amd64"
],
"path": "/bin/bash",
"size": 1168776,
"[...]": "[...]"
}
]
The list supports filtering by most fields using the ?field_name=value
query
parameter syntax.
Dependencies
Lists all dependencies
of a given project
.
GET /api/projects/d4ed9405-5568-45ad-99f6-782a9b82d1d2/dependencies/
[
{
"purl": "pkg:pypi/appdirs@1.4.4",
"extracted_requirement": "==1.4.4",
"scope": "test",
"is_runtime": true,
"is_optional": true,
"is_pinned": true,
"is_direct": true,
"dependency_uid": "pkg:pypi/appdirs@1.4.4?uuid=0033a678-2003-420d-8c83-c4071e646f4e",
"for_package_uid": "pkg:pypi/platformdirs@4.2.1?uuid=6d90ce5b-a3f8-4110-a4bd-2da5a8930d29",
"resolved_to_package_uid": null,
"datafile_path": "platformdirs-4.2.1.dist-info/METADATA",
"datasource_id": "pypi_wheel_metadata",
"package_type": "pypi",
"[...]": "[...]"
},
]
The list supports filtering by most fields using the ?field_name=value
query
parameter syntax.
Results
Displays the results as JSON content compatible with ScanCode data format.
GET /api/projects/d4ed9405-5568-45ad-99f6-782a9b82d1d2/results/
{
"headers": [
{
"tool_name": "scanpipe",
"tool_version": "21.8.2",
"[...]": "[...]"
}
]
}
Results (Download)
Finally, use this action to download the project results in the provided
output_format
as an attachment file.
- Data:
output_format
:json
,xlsx
,spdx
,cyclonedx
,attribution
GET /api/projects/d4ed9405-5568-45ad-99f6-782a9b82d1d2/results_download/?output_format=cyclonedx
Tip
Refer to Output Files to learn more about the available output formats.
Run details
The run details view returns all information available about a pipeline run.
GET /api/runs/c4d09fe5-c133-4c03-8286-6894ee5ffaab/
{
"url": "http://localhost/api/runs/8d5c3962-5fca-47d7-b8c8-47a19247714e/",
"pipeline_name": "scan_single_package",
"status": "success",
"description": "A pipeline to scan a single package archive with ScanCode-toolkit.",
"project": "http://localhost/api/projects/cd5b0459-303f-4e92-99c4-ea6d0a70193e/",
"uuid": "8d5c3962-5fca-47d7-b8c8-47a19247714e",
"created_date": "2021-10-01T08:44:05.174487+02:00",
"task_exitcode": 0,
"[...]": "[...]",
"execution_time": 12
}
Managing pipeline runs
Multiple actions are available to manage pipeline runs:
Start pipeline
This action starts (send to the task queue) a pipeline run for execution.
POST /api/runs/8d5c3962-5fca-47d7-b8c8-47a19247714e/start_pipeline/
{
"status": "Pipeline pipeline_name started."
}
Stop pipeline
This action stops a “running” pipeline.
POST /api/runs/8d5c3962-5fca-47d7-b8c8-47a19247714e/stop_pipeline/
{
"status": "Pipeline pipeline_name stopped."
}
Delete pipeline
This action deletes a “not started” or “queued” pipeline run.
POST /api/runs/8d5c3962-5fca-47d7-b8c8-47a19247714e/delete_pipeline/
{
"status": "Pipeline pipeline_name deleted."
}
XLSX Report
Generates an XLSX report for selected projects based on specified criteria. The
model
query parameter is required to determine the type of data to include in the
report.
Endpoint:
GET /api/projects/report/?model=MODEL
Parameters:
model
: Defines the type of data to include in the report. Accepted values:package
,dependency
,resource
,relation
,message
,todo
.
Note
You can apply any available filters to select the projects to include in the report. Filters can be based on project attributes, such as a substring in the name or specific labels.
Example Usage:
Generate a report for projects tagged with “d2d” and include the
TODOS
worksheet:GET /api/projects/report/?model=todo&label=d2d
Generate a report for projects whose names contain “audit” and include the
PACKAGES
worksheet:GET /api/projects/report/?model=package&name__contains=audit