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¶
The REST API token¶
![List Api tokens](../_images/ApiTokenList.png)
Fig. 178 List Api tokens¶
![Add Api token](../_images/ApiTokenAdd.png)
Fig. 179 Add Api token¶
![Api token](../_images/ApiTokenCreated.png)
Fig. 180 Api token created¶
'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 |
|
field |
|
operator |
|
value |
|
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 |
---|---|---|
|
|
Exact match operator (case insensitive) |
|
|
Substring match operator (case insensitive) |
|
|
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 repositorythe repo paths must contain only urls accessible by the user which created the token
developer-configuration
is optional, replace99
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¶
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.
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¶
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”.
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¶
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.
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¶
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.
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¶
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”.
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¶
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¶
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.
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.
Branch statistics from an analysis¶
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.
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.
KPI trends endpoints¶
The KPI trends endpoints lets you get the data behind the graphs and metrics found on CodeScenes 4-factors dashboards, as described in From Code to Delivery: the 4 factors model.
A full and current documentation of the endpoints can be found at the REST API documentation URL, see above for usage and authorization.
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/upload'
=> {"ok":"Deleted 2 coverage data entries."}