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.

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"
}

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 download
upload_file: A file to upload
upload_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/nexB/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 name
execute_now: true or false

Tip

Use the “pipeline_name:group1,group2” syntax to select steps groups:

"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."
}

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."
}

Reset

This action will delete all related database entrie 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",
        "[...]": "[...]"
    }
]

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,
        "[...]": "[...]"
    }
]

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."
}