The DeepCode analysis operates on bundles, each of them identified by a bundleId. Each bundle describes a set of files to be analyzed. One way to specify a bundle is by providing a git repository and a git commit hash. Another way is to upload a set of files and obtain a unique hash of these files. A bundle must first be created through the Create Bundle API (see below) in order to use its bundleId in the other APIs. The DeepCode API requests have a maximum allowed payload size of 4MB.

 

Get Filters

Requests current filtering options for uploaded bundles.

  • Path: /publicapi/filters
  • Method: GET
  • Request:
  • $ curl -X GET -H "Session-Token: string" https://www.deepcode.ai/publicapi/filters


Status CodeResponse
200
{
"extensions": [string, ...],
"configFiles": [string, ...]
}
401Missing sessionToken or incomplete login process



Returns the list of allowed extensions and configuration files for uploaded bundles. This information can be used to reduce the payload size of the Create Bundle (see below) request. Extensions begin with a dot (e.g. ".js") and config files begin with a slash (e.g. "/.eslintrc.js").

  

  

Create Bundle

Creates a new bundle.

  • Path: /publicapi/bundle
  • Method: POST
  • Request:
  • $ curl -X POST -H "Session-Token: string" -H "Content-Type: application/json" -d '{
    "owner": string,
    "repo": string,
    "oid": string (optional)
    }' https://www.deepcode.ai/publicapi/bundle

    $ curl -X POST -H "Session-Token: string" -H "Content-Type: application/json" -d '{
    "files": {
    filePath: fileHash,
    filePath: fileHash,
    ...
    }
    }' https://www.deepcode.ai/publicapi/bundle

Depending on the content of the request, this API creates a new bundle based on a git repository or uploaded files. For git bundles, the request must specify the repository's owner and the repository's name (repo). The oid parameter is optional and can either contain a commit hash or a branch name. If the oid is left undefined, the created bundle will point at the current latest commit of the default branch of the repository. Note that for Bitbucket repositories, due to privacy regulations, the request must specify the url-encoded user's uuid as owner instead of the respective username (e.g. "owner": "%7B33e297d1-567f-4c32-89b4-4b2759c5f5ae%7D"). 


For uploaded bundles, the files parameter must contain an object with slash-beginning file paths as keys and file hashes as values. An empty object is not allowed. The file hash must be computed by parsing the file in utf8, performing a SHA-256 on the resulting string and encoding the hash in hexadecimal (e.g. *"/.eslintrc.js": "4ed8e2973ddad1fe3eb6bbacd7b967ee8d5ef934763872c160d7cf708cc0c57e"*).


You can also skip the "Upload Files" step by passing an array in the files parameter and directly providing the file contents at bundle creation. In this case you don't need to compute the file hashes and the array must contain objects with filePath (same format as above) and fileContent items. Empty arrays are not allowed. The tradeoff for not having to compute hashes is that the client has to keep track of the uploaded files or it risks uploading files that have been already analyzed, wasting time and bandwidth. For large bundles, it's possible to create an initial sub-bundle with a first batch of files and then use the "Extend Bundle" (see below) API multiple times to add a new file batch to the previous step every time.


In order to reduce the payload size and the time required to compute the hash of every file in a project, the "Get Filters" API above can be used to pre-filter only the meaningful files. Note that old uploaded bundles can expire over time if unused.


All uploaded bundles can only be accessed by the user who uploaded them.


Status CodeResponse
200
{
"bundleId": string,
"missingFiles": [filePath, ...] (optional)
"uploadURL": string (uri, optional),
}
400Request content doesn't match the specifications
401Missing sessionToken or incomplete login process
403Unauthorized access to requested repository
404Unable to resolve requested oid
413Payload too large

Returns the bundleId required to access all the following APIs and, in case of uploaded bundles, a list of file paths that still have to be uploaded (missingFiles) and where the missing files should be uploaded to (uploadURL). When creating an uploaded bundle by directly passing the file contents in the array, missingFiles will be an empty array and the uploadURL can therefore be ignored.

 

  

Check Bundle

Checks the status of a bundle.

  • Path: /publicapi/bundle/:bundleId
  • Method: GET
  • Request:
  • $ curl -X GET -H "Session-Token: string" https://www.deepcode.ai/publicapi/bundle/:bundleId


Status CodeResponse
200
{
"bundleId": string,
"missingFiles": [filePath, ...] (optional)
"uploadURL": string (uri, optional),
}
401Missing sessionToken or incomplete login process
403Unauthorized access to requested bundle
404Uploaded bundle has expired

Returns the bundleId and, in case of uploaded bundles, the current missingFiles and the uploadURL. This API can be used to check if an old uploaded bundle has expired (status code 404), or to check if there are still missing files after uploading ("Upload Files").

 

Extend Bundle

Creates a new bundle based on a previously uploaded one.

  • Path: /publicapi/bundle/:bundleId
  • Method: PUT
  • Request:
  • $ curl -X PUT -H "Session-Token: string" -H "Content-Type: application/json" -d '{
    "files": {
    filePath: fileHash,
    filePath: fileHash,
    ...
    },
    "removedFiles": [
    filePath,
    filePath,
    ...
    ]
    }' https://www.deepcode.ai/publicapi/bundle/:bundleId


The newly created child bundle will have the same files as the parent bundle (identified by the bundleId in the request) except for what is defined in the payload. The removedFiles are parsed before the files, therefore if the same filePath appears in both of them it will not be removed. The entries in the files object can either replace an old file with a new version (if the paths match) or add a new file to the child bundle. This API is only available for extending uploaded bundles (not git bundles).


As per the "Create Bundle" API, it is possible to pass either an object or an array in the file parameter, with the same semantics as previously described.


Extending a bundle by removing all the parent bundle's files is not allowed.


Status CodeResponse
200
{
"bundleId": string,
"missingFiles": [filePath, ...]
"uploadURL": string (uri),
}
400Attempted to extend a git bundle, or ended up with an empty bundle after the extension
401Missing sessionToken or incomplete login process
403Unauthorized access to parent bundle
404Parent bundle has expired
413Payload too large

Returns the bundleId required to access the newly created child bundle, the list of file paths that still have to be uploaded (missingFiles) and where the missing files should be uploaded to (uploadURL). When extending a bundle by directly passing the file contents in the array, missingFiles could still be non-empty if the parent bundle has missing files which have not been removed nor uploaded.

    

Upload files

Uploads missing files to a bundle.

  • Path: /publicapi/file/:bundleId
  • Method: POST
  • Request:
  • $ curl -X POST -H "Session-Token: string" -H "Content-Type: application/json;charset=utf-8" -d '{
    "fileHash": fileHash,
    "fileContent": string
    }' https://www.deepcode.ai/publicapi/file/:bundleId

    $ curl -X POST -H "Session-Token: string" -H "Content-Type: application/json;charset=utf-8" -d '[
    {
    "fileHash": fileHash,
    "fileContent": string
    },
    {
    "fileHash": fileHash,
    "fileContent": string
    },
    ...
    ]' https://www.deepcode.ai/publicapi/file/:bundleId

Small files should be uploaded in batches to avoid excessive overhead due to too many requests. The file contents must be utf-8 parsed strings and the file hashes must be computed over these strings, matching the "Create Bundle" request.


Status CodeResponse
200Upload succeeded
400Content and hash mismatch or attempted to upload files to a git bundle
401Missing sessionToken or incomplete login process
403Unauthorized access to requested bundle
413Payload too large

Get Analysis

Starts a new bundle analysis or checks its current status and available results.

  • Path: /publicapi/analysis/:bundleId
  • Method: GET
  • Request:
  • $ curl -X GET -H "Session-Token: string" https://www.deepcode.ai/publicapi/analysis/:bundleId

    $ curl -X GET -H "Session-Token: string" https://www.deepcode.ai/publicapi/analysis/:bundleId?linters

The linters query parameter is optional and can be used to ask the server to also provide linters analysis.


Status CodeResponse
200
{
"status": "FETCHING" | "ANALYZING" | "DC_DONE" | "DONE" | "FAILED",
"progress": number,
"analysisURL": string (uri),
"analysisResults": analysisResults (optional),
}
401Missing sessionToken or incomplete login process.
403Unauthorized access to requested bundle.

Returns the current analysis status, the relative progress (between 0 and 1) within the current status, the analysisURL that you can access on your browser to see the interactive analysis on DeepCode, and the analysisResults if available. The status is defined as follows:


  • FETCHING: The analysis has just begun and it is currently cloning/fetching the git repository or checking missing files.
  • ANALYZING: DeepCode is analyzing every file in the bundle to check for bugs and create suggestions.
  • DC_DONE: DeepCode has finished analyzing the files but external linter tools are still computing.
  • DONE: All analyses have been computed and are available.
  • FAILED: Something went wrong with the analysis. For uploaded bundles this occurs when attempting to analyze bundles with missing files. If caused by a transient error, further calls to this API will reset the analysis status and start from the "FETCHING" phase again.

The analysisResults object is only available in the "DONE" status. It contains all the suggestions and the relative positions in the following structure:



{
"suggestions": {
suggestionIndex: {
"id": string,
"message": string,
"severity": 1 | 2 | 3
},
...
},
"files": {
filePath: {
suggestionIndex: [
{
"cols": [number, number],
"rows": [number, number],
"markers": [marker, ...]
},
...
],
...
},
...
}
}

To map the many-to-many relationship between suggestions and files, each suggestion is identified by a short suggestionIndex string (e.g. "0", "1", etc). Every suggestion object contains the respective id, the description message, and a numeric severity (1 for Info suggestions, 2 for Warnings, or 3 for Critical issues). Each file is identified by its path, and maps all the matching suggestions with the respective array of positions in the files. A position uses two ranges [ from , to ], one for the rows and one for the columns (cols), to describe an area of the file included between two characters. Each position also has an array of markers with the following structure:



{
"msg": [number, number],
"pos": [
{
"cols": [number, number],
"rows": [number, number]
},
...
]
}

Each marker object maps a substring of the suggestion's message, identified by the msg property as a [ from , to ] range between two characters, to an array of positions in the code (pos) where that substring has a meaningful match.


 

Get Diff Analysis

Starts a new diff analysis or checks its current status and available results.

  • Path: /publicapi/analysis/:bundleId/:bundleId
  • Method: GET
  • Request:
  • $ curl -X GET -H "Session-Token: string" https://www.deepcode.ai/publicapi/analysis/:bundleId/:bundleId

    $ curl -X GET -H "Session-Token: string" https://www.deepcode.ai/publicapi/analysis/:bundleId/:bundleId?linters


The first bundleId identifies the base bundle to which the second target bundle is compared. The linters query parameter is optional as for "Get Analysis".



Status CodeResponse
200
{
"status": "FETCHING" | "ANALYZING" | "DC_DONE" | "DONE" | "FAILED",
"progress": number,
"analysisURL": string (uri),
"analysisResults": analysisResults (optional),
}
401Missing sessionToken or incomplete login process.
403Unauthorized access to requested bundle.

Returns the current analysis status, the relative progress (between 0 and 1) within the current status, the analysisURL, and the analysisResults if available (see "Get Analysis"). Only new suggestions found in the target bundle and not in the base bundle are returned in the analysisResults object.