Public API

We are expanding the API with every release to make more analysis information available. Contact Codescene, and we are happy to share our detailed plans and get your feedback.

You can get the following information from the API:

Using CodeScene’s REST API

The REST API documentation URL

You can browse the REST API functions here CodeScene RestAPI Functions . Before trying any functionality, use the Authorize button then fill in the value with ‘Bearer <your_token>’ to authenticate.
The version in use is v2.

The REST API token

CodeScene lets you create a token intended to consume the API. Login then create a new token as illustrated in Fig. 183 and Fig. 184.
List Api tokens

Fig. 183 List Api tokens

Add Api token

Fig. 184 Add Api token

Api token

Fig. 185 Api token created

To consume the REST API, you need to authenticate by adding the http header 'Authorization: Bearer <your token>'.

Filter queries

The API endpoints that returns file lists support an optional filter parameter. This makes it possible to specify queries for returning objects in a flexible manner.

Query structure and terminology

A query clause consists of a field followed by an operator followed by a value, optionally quoted:

clause

owner:"Igor Lavrov"

field

email

operator

:

value

Igor Lavrov

You can combine multiple query clauses in a search by separating them with a space. When multiple query clauses are specified, the API combines them with AND logic. Quotation marks around values are optional, but must be used for values containing spaces.

Query Clause Syntax

The following table lists the operators that you can use to construct a query clause.

OPERATOR

USAGE

DESCRIPTION

:

field:value

Exact match operator (case insensitive)

~

field~value

Substring match operator (case insensitive)

>, <, =

field<value

Greater than/less than/equals operators. Supported only for numbers.

Any field present on the returned items can be used in a clause. Nested fields are specified using dot notation, as in code_health.current_score. For fields that are lists, the clause will be true if it is fulfilled by any item in the list.

Project endpoints

Projects list

 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects'

New Project

 curl -X POST --header 'Content-Type: application/json' --header 'Authorization: Bearer <token>' \
 --data "@./project.json" 'https://api.codescene.io/v2/projects/new'

  • Replace ./project.json with a valid a path to your project configuration.

  • Example of ./project.json

{
   "config": {
   "name" : "test",
   "repo-paths" : ["https://yourprovider.com/mycompany/myproject.git"],
   "developer-configuration" : 99
   }
}

  • name is optional, if missing CodeScene will use the project name from the first repository

  • the repo paths must contain only urls accessible by the user which created the token

  • developer-configuration is optional, replace 99 with a valid id taken from the developer settings list results.

Analysis List of a project

 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses'

  • Replace {project-id} with a valid id taken from the project list results.

Single analysis details

Single analysis details using its id
 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {analysis-id} with a valid id taken from the analysis list results.

Latest analysis details
 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/latest'

  • Replace {project-id} with a valid id taken from the project list results.

Files list from an analysis

File list in descending order based on order_by value for given analysis id
 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/files?page={page}&page_size={page_size}&order_by={order_by}'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {analysis-id} with a valid id taken from the analysis list results.

  • Replace {page} with required page to return. If page parameter is omitted the default value is 1.

  • Replace {page_size} with the number of files to return for a page. If page_size parameter is omitted the default value is 100.

  • Replace {order_by} with one of the following values: “lines_of_code”, “change_frequency”, “number_of_defects”, “code_health” or “cost”. If order_by parameter is omitted the default value is “change_frequency”.

Files list in descending order based on order_by value for latest analysis
 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/files?page={page}&page_size={page_size}&order_by={order_by}'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {page} with required page to return. If page parameter is omitted the default value is 1.

  • Replace {page_size} with the number of files to return for a page. If page_size parameter is omitted the default value is 100.

  • Replace {order_by} with one of the following values: “lines_of_code”, “change_frequency”, “number_of_defects”, “code_health” or “cost”. If order_by parameter is omitted the default value is “change_frequency”.

Components list from an analysis

Components list using analysis id
 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/components'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {analysis-id} with a valid id taken from the analysis list results.

Latest analysis components list
 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/components'

  • Replace {project-id} with a valid id taken from the project list results.

Single components details from an analysis

Component details using analysis id
 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/components/{component-name}'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {analysis-id} with a valid id taken from the analysis list results.

  • Replace {component-name} with a valid name taken from the components list results.

Latest analysis component detail
 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/components/{component-name}'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {component-name} with a valid name taken from the components list results.

Component file list from an analysis

Component file list in descending order based on order_by value for given analysis id
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/components/{component-name}/files?page={page}&page_size={page_size}&order_by={order_by}'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {analysis-id} with a valid id taken from the analysis list results.

  • Replace {component-name} with a valid id taken from the component list results.

  • Replace {page} with required page to return. If page parameter is omitted the default value is 1.

  • Replace {page_size} with the number of files to return for a page. If page_size parameter is omitted the default value is 100.

  • Replace {order_by} with one of the following values: “lines_of_code”, “change_frequency”, “number_of_defects”, “code_health” or “cost”. If order_by parameter is omitted the default value is “change_frequency”.

Component files list in descending order based on order_by value for latest analysis
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/components/{component-name}/files?page={page}&page_size={page_size}&order_by={order_by}'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {component-name} with a valid id taken from the component list results.

  • Replace {page} with required page to return. If page parameter is omitted the default value is 1.

  • Replace {page_size} with the number of files to return for a page. If page_size parameter is omitted the default value is 100.

  • Replace {order_by} with one of the following values: “lines_of_code”, “change_frequency”, “number_of_defects”, “code_health” or “cost”. If order_by parameter is omitted the default value is “change_frequency”.

Delta Analyses List of a project

 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/delta-analyses'

  • Replace {project-id} with a valid id taken from the project list results.

Single delta analysis details

Single delta analysis details using its id
 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/delta-analyses/{delta-analysis-id}'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {delta-analysis-id} with a valid id taken from the delta analysis list results.

Commit activity trend from an analysis

Commit activity trend for given analysis id
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/commit-activity'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {analysis-id} with a valid id taken from the analysis list results.

Commit activity trend for latest analysis
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/commit-activity'

  • Replace {project-id} with a valid id taken from the project list results.

Author statistics from an analysis

Author statistics for given analysis id
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/author-statistics'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {analysis-id} with a valid id taken from the analysis list results.

Author statistics for latest analysis
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/author-statistics'

  • Replace {project-id} with a valid id taken from the project list results.

Branch statistics from an analysis

Branch statistics for given analysis id
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/branch-statistics'

  • Replace {project-id} with a valid id taken from the project list results.

  • Replace {analysis-id} with a valid id taken from the analysis list results.

Branch statistics for latest analysis
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/branch-statistics'

  • Replace {project-id} with a valid id taken from the project list results.

Get Project Badge Status

CodeScene support the following badges: code-health, missed-goals, system-mastery

 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project_id}/badges'

  • Replace {project_id} with a valid id taken from the project list results.

Update Project Badge Status

 curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
 --header 'Authorization: Bearer <token>' -d '{"code-health":true, "missed-goals": true ,"system-mastery": false}' \
 'https://api.codescene.io/v2/projects/{project_id}/badges'

  • Replace {project_id} with a valid id taken from the project list results.

Run Analysis

 curl -X POST --header 'Content-Type: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects//{project_id}/run-analysis'

  • Replace {project_id} with a valid id taken from the project list results.

  • Note that it is strongly recommended that analysis scheduling be turned off if this endpoint is used as a continuous trigger of analysis.

Teams and Developers endpoints

Developer Settings list

 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/developer-settings'

Teams list

 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/developer-settings/{developer_setting_id}/teams'

  • Replace {developer_setting_id} with a valid id taken from the developer settings list results.

Create team

 curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
 --header 'Authorization: Bearer <token>' -d '{ "team_name": "my-new-team"}' \
 'https://api.codescene.io/v2/developer-settings/{developer_setting_id}/teams/new'

  • Replace {developer_setting_id} with a valid id taken from the developer settings list results.

Update team

 curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
 --header 'Authorization: Bearer <token>' -d '{ "team_name": "my-updated-team"}' \
 'https://api.codescene.io/v2/developer-settings/{developer_setting_id}/teams/{team_id}'

  • Replace {developer_setting_id} with a valid id taken from the developer settings list results.

  • Replace {team_id} with a valid id taken from the teams list results.

Delete team

 curl -X DELETE --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/developer-settings/{developer_setting_id}/teams/{team_id}'

  • Replace {developer_setting_id} with a valid id taken from the developer settings list results.

  • Replace {team_id} with a valid id taken from the teams list results.

Developer list

 curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/developer-settings/{developer_setting_id}/developers'

  • Replace {developer_setting_id} with a valid id taken from the developer settings list results.

Update developer

 curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
 --header 'Authorization: Bearer <token>' -d '{ "team_id": 12, "former_contributor": true, "exclude_from_all_analyses": true}' \
 'https://api.codescene.io/v2/developer-settings/{developer_setting_id}/developers/{developer_id}'

  • Replace {developer_setting_id} with a valid id taken from the developer settings list results.

  • Replace {developer_id} with a valid id taken from the developers list results.

  • Set the team_id to a valid id taken from teams list if you need to assign the current developer to that team.

  • The only updateable attributes of a developer are the team_id, former_contributor and exclude_from_all_analyses

  • The payload can contain any of the attributes or only some of them.

Delete developer

 curl -X DELETE --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/developer-settings/{developer_setting_id}/developers/{developer_id}'

  • Replace {developer_setting_id} with a valid id taken from the developer settings list results.

  • Replace {developer_id} with a valid id taken from the developers list results.

Remove Developer from Team

 curl -X DELETE --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/developer-settings/{developer_setting_id}/developers/{developer_id}/team'

  • Replace {developer_setting_id} with a valid id taken from the developer settings list results.

  • Replace {developer_id} with a valid id taken from the developers list results.

Remove Developer Settings

 curl -X DELETE --header 'Accept: application/json' --header 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/developer-settings/{developer_setting_id}'

  • Replace {developer_setting_id} with a valid id taken from the developer settings list results.

Code Coverage endpoints

The Code Coverage endpoints lets you upload code coverage data for use during analysis.

Upload Data

The code coverage data upload uses two endpoints, one for requesting an upload and specifying some metadata necessary for analysis and one for doing the actual upload.

  • Given that you have code coverage data on disc, first request an upload:

 curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
 --header 'Authorization: Bearer <token>' -d "{\"commit-sha\": \"$(git rev-parse HEAD)\", \"repo-url\": \"$(git config --get remote.origin.url)\", \"repo-path\": \"$(pwd)\", \"format\": \"open-clover\", \"metric\": \"statement-coverage\"}"
 'https://api.codescene.io/v2/code-coverage/upload'

 => {"ok":"upload request accepted","ref":"/api/v2/code-coverage/upload/65","id":65}

  • And then use the returned ref in a subsequent call to do the actual upload of the data (compressed in gz format)

 curl -X PUT --header "Content-Type: text/plain" --header 'Accept: application/json' \
 --header 'Authorization: Bearer <token>' --data-binary @coverage/clover.xml.gz
 'https://api.codescene.io/v2/code-coverage/upload/{id}'

 => {"ok":"Successfully parsed open-clover data for 829 files."}

Delete Data

All code coverage data for a specific repository can be deleted like this:

 curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' \
 --header 'Authorization: Bearer <token>' -d "{\"repo-url\": \"$(git config --get remote.origin.url)\"}"
 'https://api.codescene.io/v2/code-coverage'

 => {"ok":"Deleted 2 coverage data entries."}