REST 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:

• Projects list

• Import Project Configuration

• Export Project Configuration

• Update Project Configuration

• Single project details

• Delete project

• Update Project by importing development teams

• Get Projects Usage Activity

• Get Project Default Role

• Set Project Default Role

• Analysis List of a project

• Single analysis details

• Files list from an analysis

• Components list from an analysis

• Single components details from an analysis

• Component file list from an analysis

• Commit activity trend from an analysis

• Author statistics from an analysis

• Branch statistics from an analysis

• Skills inventory: programming language experience and distribution

• Delta Analyses List of a project

• Single delta analysis details

• Groups list

• Projects in group list

• Get Group Default Role

• Set Group Default Role

• Users and Roles endpoints

• Create User

• Get User by username

• Developer Settings list

• Teams list

• Create team

• Update team

• Delete team

• Developer list

• Update developer

• Delete developer

• Remove Developer from Team

• Remove Developer Settings

• Roles list

• Authentication providers list

• Get authentication provider

• Update authentication provider

• Authentication provider role mapping list

• Add role mapping to authentication provider

• Remove role mapping from authentication provider

• Get Authentication Provider Default Role

• Set Authentication Provider Default Role

• Get Project PR Integration with webhooks list

• Update Project PR Integration

• Disable Project PR Integration

• Get Project Badge Status

• Update Project Badge Status

• KPI trends endpoints

• Project PM Integration endpoints

• Maintenance endpoints

• Version endpoint

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 your username and password to authenticate.

The version in use is v2. Version v1 is deprecated

The REST API user

CodeScene lets you create a user intended to consume the REST API. Login as administrator then create a new user and assign RestApi role to it as illustrated in Fig. 52.

Any user with role Admin, Architect or RestApi can consume the REST API

If you are using LDAP, you need to assign the Admin, Architect or RestApi role. Follow the instructions from LDAP Roles Settings to assign a role to a LDAP user.

OAuth user accounts are not supported.

Fig. 52 Configure a RestApi user to consume the REST API.

To consume the REST API, you need to authenticate using http basic authentication.

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' -u username:password \
 'http://localhost:3003/api/v2/projects'

Import Project Configuration

curl -X POST --header 'Content-Type: application/json' -u username:password \
--data "@./project-config.json" 'http://localhost:3003/api/v2/projects/new'

• Replace ./project-config.json with a valid a path to your project configuration, the format is the one exported by CodeScene

• Minimal example for a project where you specify the local path ./specifiy-path-project-config.json

{
  "config": {
    "repo-paths": [
      "/path/to/my/project"
    ],
    "analysis-destination": "/path/to/save/analisys"
  }
}

• Minimal example for a project where you specify the remote git repository urls ./specifiy-remotes-project-config.json

{
  "config": {
    "repo-paths": [
      "https://my.company.com/mycompany/project1.git",
      "https://my.company.com/mycompany/project2.git",
      "https://my.company.com/mycompany/project3.git"
    ],
    "local-path-for-remotes": "/path/to/save/repository/",
    "analysis-destination": "/path/to/save/analisys"
  }
}

Export Project Configuration

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project-id}/export/configuration/json'

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

Update Project Configuration

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
--data '{"config" : {"description" : "this a project description"}}' \
'http://localhost:3003/api/v2/projects/{project-id}'

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

• The body payload can contain one or multiple attributes from the list below

{
  "config": {
    "branch-name-exclusion-pattern": "string",
    "global-code-health-custom-rules": "string",
    "complexitytrendwarninglookbackinmonths": "int",
    "delta-always-comment": "boolean",
    "team-analysis-sliding-window-time": "1 month/3 months/6 months/1 year/2 years/full",
    "whitelistcontent": "string",
    "ticketidpattern": "string",
    "modus-commit-message-pattern": "string",
    "selectdistinctcommits": "int",
    "delivery-performance-strategy": "by-pm-transitions/by-git-tags",
    "pair-programming-pattern": "string",
    "temporal_coupling_across_minrevs": "int"0,
    "max_historic_age": "int",
    "exclusionfilter": "string",
    "code-health-alert-level": "int",
    "use-parallel-code-health-strategy": "boolean",
    "git-rename-limit": "int",
    "delivery-performance-release-tag": "string",
    "delta-recommend-review-level": "boolean",
    "temporal_coupling_archlevel_across_minrevs": "int",
    "hotspots-sliding-window-time": "1 month/3 months/6 months/1 year/2 years/full",
    "hotspots-defect-mining-pattern": "string",
    "spottrendspan": "int",
    "age-is-last-commit": "boolean",
    "maxchangesetsize": "int",
    "disable-code-health-custom-rules": "boolean",
    "pair-programming-author-message-pattern": "string",
    "temporal_coupling_across_maxchangesetsize": "int",
    "complete-history-for-social": "boolean",
    "lookup-copied-content": "boolean",
    "name": "string",
    "calculate-branch-statistics": "boolean",
    "modus_commit_message_pattern": "string",
    "present-x-ray-overloads-separately": "boolean",
    "scan-all-code-in-project": "boolean",
    "max_branch_risk_history_depth": "int",
    "temporal-coupling-strategy": "by-ticket-id/by-time",
    "ticket-id-uri-template": "string",
    "project_owner": "string",
    "minrevs": "int",
    "update-repositories": "boolean",
    "excludecontent": "string",
    "rollingaveragedays": "int",
    "auto-detect-text-files": "boolean",
    "code_comment_enabled": "boolean",
    "exdevcontribenabled": "int",
    "limit_branch_prediciton_commits": "boolean",
    "xrayallrevisions": "int",
    "start-date": "string",
    "max_history_depth": "int",
    "branches-analysis-lookback-weeks": "int",
    "analysis-start-date": "string",
    "description": "string",
    "combine-authors-field-and-commit-msg-to-deduce-pairs?": "boolean",
    "pm-data-sliding-window-time": "1 month/3 months/6 months/1 year/2 years/full",
    "minexdevcontribtime": "int",
    "team-analysis-start-date": "string",
    "code-ownership-source-file-names": "string",
    "group-id": "int",
    "developer-configuration": "int"
  }
}

Single project details

 curl -X GET --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/v2/projects/{project-id}'

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

Delete project

Delete the project by id, the project analyses result and associated developer settings, you can add the query parameter developer-settings=false if you want skip the deletion of associated developer settings. The delete of developer settings is skiped if it used buy other project even if developer-settings=true.

All project repositories are removed only if env variable CODESCENE_CLONED_REPOSITORIES_ROOT is set.

 curl -X DELETE --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/v2/projects/{project-id}'

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

List git repositories

 curl -X GET --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/v2/projects/{project-id}/repositories'

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

Add git repositories

 curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
 --data '{"repositories":[{"url": "https://mycompany.com/projects/p1.git", "branch": "main"}, {"url": "https://mycompany.com/projects/p2.git", "branch": "1.0.x"}]}' \
 'http://localhost:3003/api/v2/projects/{project-id}/repository'

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

• The body can contain one or multiple Git repositories with url and branch(is optional, if missing default repository branch will be used). By default, an architectural component for each repository will be created. This behaviour can be changed by adding the boolean parameter “generate-architectural-component”. Here is an example of a payload:

 '{"repositories":[{"url": "https://mycompany.com/projects/p1.git", "branch": "main"}], \
 "generate-architectural-component":false }'

Edit git repository branch

 curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
 --data '{"repositories":[{"url": "https://mycompany.com/projects/p1.git", "branch": "v.0.1"}]}' \
 'http://localhost:3003/api/v2/projects/{project-id}/repository'

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

• the url must be already registered to the project

• The body can contain one or multiple Git repositories with url and branch

Remove git repository url’s

 curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
 --data '{"urls":["https://mycompany.com/projects/p1.git", "https://mycompany.com/projects/p2.git"]}' \
 'http://localhost:3003/api/v2/projects/{project-id}/repository/remove'

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

• the body can contain one or multiple git repository url’s

Add git repository url’s (deprecated)

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
--data '{"urls":["https://mycompany.com/projects/p1.git", "https://mycompany.com/projects/p2.git"]}' \
'http://localhost:3003/api/v1/projects/{project-id}/repository/add'

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

• The body can contain one or multiple Git repository URLs. By default, an architectural component for each repository will be created. This behaviour can be changed by adding the boolean parameter “generate-architectural-component”. Here is an example of a payload:

'{"urls":["https://mycompany.com/projects/p1.git", "https://mycompany.com/projects/p2.git"], \
"generate-architectural-component":false }'

Update Project by importing development teams

curl -X POST --header 'Content-Type: text/csv' --header 'Accept: application/json' -u username:password \
--data "@./teams.csv" 'http://localhost:3003/api/v2/projects/{project-id}/teams/import'

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

• Replace ./teams.csv with a valid a path to your teams configuration, the format is the one exported by CodeScene, first row of the file is the header

• Example file ./teams.csv

author,team
max,backend
john,backend
sherri,ui

Get Project PR Integration with webhooks list

CodeScene support PR integration with following providers: github, bitbucket-server, gitlab, azure, github-app, bitbucket, gerrit

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project_id}/pr-integration'

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

Update Project PR Integration

Each provider require a custom configuration to be set.

github example

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
      "github-token": "Specify a GitHub API token with repo and repo_hook:write permissions.", \
      "github-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used. ", \
      "github-api-url": "Specify the GitHub API URL. If left blank, a default API URL is constructed from the repository paths." \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/github'

bitbucket-server example

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
      "bitbucket-server-api-url": "Specify the Bitbucket API URL. If left blank, a default API URL is constructed from the repository paths.", \
      "bitbucket-server-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.", \
      "bitbucket-server-token": "Specify a Bitbucket API token with Projects:read and Repositories:admin permissions.The token must be created by a user with the REPO_ADMIN permission." \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/bitbucket-server'

gitlab example

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
      "gitlab-api-url": "Specify the GitLab API URL. If left blank, a default API URL is constructed from the repository paths.", \
      "gitlab-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.", \
      "gitlab-token": "Specify a GitLab API token with api permissions." \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/gitlab'

azure example

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
      "azure-api-url": "Specify the Azure API URL. If left blank, a default API URL is constructed from the repository paths.", \
      "azure-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.", \
      "azure-token": "Specify an Azure API token with Code:Read & Write and Service Connections:Read, query, & manage permissions." \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/azure'

github-app example

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
      "github-app-app-id": "Specify the app id for the app you create on GitHub.", \
      "github-app-private-ke": "The content of the .pem file you download by generating a private key for the app on GitHub.", \
      "github-app-secret": "Specify the webhook secret for the app you create on GitHub.", \
      "github-app-annotations": "Boolean, if true annotations will be added to CheckRun.", \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/github-app'

bitbucket example

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
      "bitbucket-api-url": "Specify the Bitbucket API URL. If left blank, a default API URL is constructed from the repository paths. ", \
      "bitbucket-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.", \
      "bitbucket-token": "Specify a Bitbucket App Password with Pull requests:write and Webhooks:write permissions.", \
      "bitbucket-username": "Specify the Bitbucket Username." \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/bitbucket'

gerrit example

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ \
      "gerrit-api-url": "Specify the Gerrit API URL. If left blank, a default API URL is constructed from the repository paths.", \
      "gerrit-host-url": "The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.", \
      "gerrit-token": "Specify the Gerrit Http Password.", \
      "gerrit-username": "Specify the Gerrit Username.", \
      "gerrit-origin-url": "Specify the Gerrit Origin URL to use for fetching changes, if different from the configured repository origin URL. " \
}' 'http://localhost:3003/api/v2/projects/{project_id}/pr-integration/gerrit'

Disable Project PR Integration

curl -X DELETE --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project_id}/pr-integration'

• 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' -u username:password \
 'http://localhost:3003/api/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' \
 -u username:password -d '{"code-health":true, "missed-goals": true ,"system-mastery": false}' \
 'http://localhost:3003/api/v2/projects/{project_id}/badges'

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

Get Projects Usage Activity

Check the last time a specific project was accessed, the number of active authors, the duration of the last analysis

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/usage-activity'

Get Project Default Role

Get the default role for the given project id

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project_id}/default-role'

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

Set Project Default Role

Set the default role for the given project id

curl -X PUT --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project_id}/default-role/{role_id}'

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

• Replace {role_id} with a valid id taken from the role list results.

Analyses endpoints

Analysis List of a project

 curl -X GET --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
'http://localhost:3003/api/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' -u username:password \
'http://localhost:3003/api/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”.

Commit activity trend from an analysis

Commit activity trend for given analysis id

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/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' -u username:password \
'http://localhost:3003/api/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' -u username:password \
'http://localhost:3003/api/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' -u username:password \
'http://localhost:3003/api/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' -u username:password \
'http://localhost:3003/api/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' -u username:password \
'http://localhost:3003/api/v2/projects/{project-id}/analyses/latest/branch-statistics'

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

Skills inventory: programming language experience and distribution

Successful software maintenance requires the organization to maintain system mastery of the codebase. One aspect of that mastery is to make sure you have people who know all the implementation technologies and that there aren’t any bottlenecks (e.g. “we cannot finish that feature, because our only APL programmer is on a 3 months vacation”). CodeScene’s skills inventory analysis provides input to system mastery discussions and planning.

In general, CodeScene answers the following questions:

1. How many developers know language X?

2. Who are those developers, and what are their relative contribution experience in that technology?

The analysis info is available both for the whole codebase as well as for specific sub-systems and components. Use this information as input to discussions on:

• Do we need to train more people in a specific programming language?

• Do we have to hire people for a specific programming language?

• Do we have enough C#/C++/Java/Python programmers in that critical sub-system where we plan lots of new features?

Before we look at the specific endpoints, lets explain the contribution fields that you will find in the responses:

Fig. 53 CodeScene calculates both total and relative contribution experience for each developer.

In combination with CodeScene’s on- and off-boarding simulation module, you can also use this information to see the effects of rotating staff between different sub-systems or components and identify key personnel on a technical level.

There are two main REST endpoints:

Get a list of all programming languages and active contributors with their relative contributions

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project-id}/analyses/latest/experience/languages'

Limit the query to developers working in a specific programming language

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project-id}/analyses/latest/experience/languages/{language}'

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

• Replace {language} with the name of a programming language, e.g. JavaScript, Python, etc.

Both of these endpoints also exist on a component level. The response format is identical, only limited to programming languages and contribution statistics withing the given component:

Get a list of all programming languages and active contributors with their relative contributions in a given component/sub-system

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project_id}/analyses/latest/components/{component}/experience/languages'

Limit the query to developers working in a specific programming language within the given component/sub-system

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/projects/{project_id}/analyses/latest/components/{component}/experience/languages/{language}'

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

• Replace {language} with the name of a programming language, e.g. JavaScript, Python, etc.

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

Delta Analyses List of a project

 curl -X GET --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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.

Groups endpoints

Groups list

To call this endpoint you must be authenticated with an admin username.

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/groups'

Projects in group list

To call this endpoint you must be authenticated with an admin username.

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/groups/{groups-id}/projects'

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

Get Group Default Role

Get the default role for the given group id

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/groups/{group_id}/default-role'

• Replace {group_id} with a valid id taken from the group list results.

Set Group Default Role

Set the default role for the given group id

curl -X PUT --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/groups/{group_id}/default-role/{role_id}'

• Replace {group_id} with a valid id taken from the group list results.

• Replace {role_id} with a valid id taken from the role list results.

Users and Roles endpoints

Users list

To call this endpoint you must be authenticated with an admin username.

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/users'

Create User

To call this endpoint you must be authenticated with an admin username.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-u username:password -d '{ "username": "my_new_username", "password": "qwerty"}' \
'http://localhost:3003/api/v2/users/new'

• the body must contain the username and password as json, the newly created user will have the default role “Full Read-Only Access”.

Get User by username

To call this endpoint you must be authenticated with an admin username.

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/users/{username}'

• Replace {username} with a valid username taken from the users list results.

Roles list

To call this endpoint you must be authenticated with an admin username.

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/roles'

Authentication providers list

To call this endpoint you must be authenticated with an admin username.

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/authentication-providers'

Get authentication provider

To call this endpoint you must be authenticated with an admin username.

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}'

• Replace {provider_id} with a valid provider id taken from the authentication providers list results.

Update authentication provider

To call this endpoint you must be authenticated with an admin username.

Only authentication providers of type ldap and oauth2 can be updated.

Example of updating ldap authentication provider

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{ "active?": true, \
      "codescene_default_role": 1, \
      "auth_provider_config": { \
          "search_base": "(|(OU=people,OU=Internal,DC=medtronic,DC=com)(ou=serviceaccounts,ou=internal,dc=mycomapny,dc=com))" \
          "connection_timeout": "5000", \
          "response_timeout": "5000", \
          "port": "636", \
          "host": "ldap.mycompany.com", \
          "ssl?": true, \
          "bind_dn_format": "uid={username},OU=people,OU=Internal,DC=mycomapny,DC=com"} \
    }' \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}'

• Replace {provider_id} with a valid provider id taken from the authentication providers list results.

• The body must contain the active? true/false, codescene_default_role the id must be a valid role id taken from the roles list results and auth_provider_config map with all the fields like in the example above, please adapt the values according to you setup.

Example of updating oauth2 authentication provider

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -u username:password \
-d '{"active?": true, \
      "codescene_default_role": 1, \
      "auth_provider_config": { \
          "teams_url": "http://my.oauth2.com/protocol/openid-connect/teaminfo", \
          "teamname_field": "$.group[*]", \
          "access_token_url": "http://my.oauth2.com/protocol/openid-connect/token", \
          "scope": "email roles profile", \
          "provider_name": "mycompany", \
          "authorization_url": "http://my.oauth2.com/protocol/openid-connect/auth", \
          "username_field": "$.email", \
          "client_id": "app-codescene", \
          "client_secret": "my-client-secret", \
          "user_url": "http://my.oauth2.com/protocol/openid-connect/userinfo" \
      }}' \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}'

• Replace {provider_id} with a valid provider id taken from the authentication providers list results.

• The body must contain the active? true/false, codescene_default_role the id must be a valid role id taken from the roles list results and auth_provider_config map with all the fields like in the example above, please adapt the values according to you setup.

Authentication provider role mapping list

To call this endpoint you must be authenticated with an admin username. If no query parameters are present the result represent the role mappings at global level. Use either group-id or project-id to get the role mappings at group or project level.

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}/role-mappings?group-id={group_id}&project-id={project_id}'

• Replace {provider_id} with a valid provider id taken from the authentication propviders list results.

• Replace {group_id} with a valid id taken from the groups list results, the result represent the role mappings at the group level.

• Replace {project_id} with a valid id taken from the projects list results, the result represent the role mappings at the project level.

Add role mapping to authentication provider

To call this endpoint you must be authenticated with an admin username.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-u username:password -d '{ "identifier": "my-identifier", "role_id": 8, "group_id": 1, "project_id: 2"}' \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}/role-mappings'

• replace {provider_id} with a valid provider id taken from the authentication providers list results.

• omit the group_id and project_id parameters to add a mapping at the global level.

• use the group_id or project_id parameters to add a mapping at group or project level.

• the body must contain the identifier(user or group name) and role_id as json, the role_id must be a valid role id taken from the roles list results.

Remove role mapping from authentication provider

To call this endpoint you must be authenticated with an admin username.

curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' \
-u username:password -d '{ "identifier": "my-identifier", "group_id": 1, "project_id: 2"}' \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}/role-mappings'

• replace {provider_id} with a valid provider id taken from the authentication providers list results.

• omit the group_id and project_id parameters to remove the mapping from the global level.

• use the group_id or project_id parameters to remove the mapping from group or project level.

Get Authentication Provider Default Role

Get the default role for the given authentication provider id

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}/default-role'

• replace {provider_id} with a valid provider id taken from the authentication providers list results.

Set Authentication Provider Default Role

Set the default role for the given authentication provider id

curl -X PUT --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/authentication-providers/{provider_id}/default-role/{role_id}'

• replace {provider_id} with a valid provider id taken from the authentication providers list results.

• replace {role_id} with a valid id taken from the role list results.

Teams and Developers endpoints

Developer Settings list

 curl -X GET --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/v2/developer-settings'

Teams list

 curl -X GET --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/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' \
 -u username:password -d '{ "team_name": "my-new-team"}' \
 'http://localhost:3003/api/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' \
 -u username:password -d '{ "team_name": "my-updated-team"}' \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' \
 -u username:password -d '{ "team_id": 12, "former_contributor": true, "exclude_from_all_analyses": true}' \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/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' -u username:password \
 'http://localhost:3003/api/v2/developer-settings/{developer_setting_id}'

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

• to call this endpoint you must be authenticated with an admin username.

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.

Project PM Integration endpoints

Get project’s PM Integration configuration

 curl -X GET --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/v2/projects/{project_id}/pm-integration'

• Replace {project_id} with a valid project ID

• Returns a list of all configured PM integrations for the project

Set project’s Project Management settings

• Replace {project_id} with a valid project id.

• You can only submit one PM integration via REST API

Setting a Jira integration

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
 -u username:password -d '[{"active?":true,"cost_field":"timespent","map_commits_to_pull_request_issues":true,"password":".....","name":"Untitled","username":"jirauser@company.com","external_project_ids":["CT"],"work_done_transition_names":["Done"],"type":"jira","excluded_work_types":"Epic","rename_work_types":{},"defect_and_failure_labels":["Bug"],"api_url":"https://test.atlassian.net","cost_unit":"issues","use_labels_as_work_types":false,"supported_work_types":[],"project_aliases":{"CT":"CT"},"map_subtasks_to_parent_issues":false,"uses_supported_work_types":false,"work_in_progress_transition_names":["In Progress"],"uses_excluded_work_types":"TRUE"}]' \
 'http://localhost:3003/api/v2/projects/{project_id}/pm-integration'

Setting a Trello integration

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
 -u username:password -d '[{"active?":true,"cost_field":"","password":"ssss","name":"Trello Project","username":"username","external_project_ids":["Trello-Project"],"work_done_transition_names":["Done"],"type":"trello","rename_work_types":{},"defect_and_failure_labels":["Bug","Bug/Problematic","Support issue","Support Issue","Security issue"],"api_url":"","cost_unit":"issues","supported_work_types":["Feature","Bug","Bug/Problematic","Support issue","Security issue"],"project_aliases":{"product":"Trello-Project"},"uses_supported_work_types":true,"work_in_progress_transition_names":[]}]' \
 'http://localhost:3003/api/v2/projects/{project_id}/pm-integration'

Disable project’s Project Management settings

 curl -X DELETE --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/v2/projects/{project_id}/pm-integration'

• Replace {project_id} with a valid project id.

Get project’s Pull Request data provider for PM Integration

 curl -X GET --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/v2/projects/{project_id}/pm-integration/pr-data-provider'

• Replace {project_id} with a valid project ID

• Returns a list of all configured PM integrations for the project

Set project’s Pull Request data provider for PM Integration

• Replace {project_id} with a valid project id.

• You can only submit one PM integration via REST API

Setting PR provider for PM Integration to be GitHub.com itself. Note that we don’t need to specify api_url as github.com is default.

 curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
 -u username:password -d '[{"type":"github","password":"....","active?":true}]' \
 'http://localhost:3003/api/v2/projects/{project_id}/pm-integration/pr-data-provider'

Same thing but Bitbucket:

 curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
 -u username:password -d '[{"type":"github","password":"....","username":"user",active?":true}]' \
 'http://localhost:3003/api/v2/projects/{project_id}/pm-integration/pr-data-provider'

Disable project’s Pull Request data provider for PM Integration

 curl -X DELETE --header 'Accept: application/json' -u username:password \
 'http://localhost:3003/api/v2/projects/{project_id}/pm-integration/pr-data-provider'

• Replace {project_id} with a valid project id.

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' \
 -u username:password -d "{\"commit-sha\": \"$(git rev-parse HEAD)\", \"repo-url\": \"$(git config --get remote.origin.url)\", \"repo-path\": \"$(pwd)\", \"format\": \"open-clover\", \"metric\": \"statement-coverage\"}"
 'http://localhost:3003/api/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' \
 -u username:password --data-binary @coverage/clover.xml.gz
 'http://localhost:3003/api/v2/code-coverage/upload/{id}'

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

List Data

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

 curl -X GET --header 'Accept: application/json' \
 -u username:password "http://localhost:3003/api/v2/code-coverage?repo-url=$(git config --get remote.origin.url)"

 => [
      {
        "subpath": null,
        "format": "edn",
        "id": 1,
        "repo": "github.com/mycompany/myproject",
        "commit_sha": "12348bd683bfa5db8227a281a4a295d6d0281234",
        "repo_path": "/users/test/myproject",
        "created_at": "2025-01-07T10:00:00.000Z",
        "metric": "line-coverage"
      }
    ]

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' \
 -u username:password -d "{\"repo-url\": \"$(git config --get remote.origin.url)\"}"
 'http://localhost:3003/api/v2/code-coverage'

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

Maintenance endpoints

DB Backup

To call this endpoint you must be authenticated as an admin. This endpoint is intended to be used only if db engine is H2.

curl -X POST --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/maintenance/db-backup'

• the backup will generate a zip file in the same location as the original db file and will contain the timestamp in the name

• to get more information regarding the location of the database file see: define-root-path-for-persistent-data .

Version endpoint

Get the version information:

• running_version: the current running version

• latest_version: the latest version available for download

curl -X GET --header 'Accept: application/json' -u username:password \
'http://localhost:3003/api/v2/version'

Examples: Use Cases and Scripts

We use CodeScene’s REST API ourselves, and in this section we’d like to share some of the scripts we use. These scripts are particularly useful on large codebases as a basis for custom reports.

These examples are based on the following strategy:

• Invoke the REST API using curl.

• Parse the reply with the jq tool.

• Pipe the response to other shell functions when needed.

As such, everything below is built using existing command line tools.

Let’s start by defining a helper function for calling the REST API:

call_api(){ curl -sS -u api:secret http://localhost:3003/api/v2$1 ${@:2}; }
export -f call_api

Using the call_api utility, we can now query the REST API for specific purposes as illustrated in the following paragraphs.

Project Statistics

List project names and ids:

call_api /projects | jq -r '.projects[] | [.name,.id] | @csv' | sort

Calculate the total lines of code in the 10 most changed files:

call_api /projects/1/analyses/latest/files | jq -r '.files | sort_by(.change_frequency)
 | .[0:10] | .[].lines_of_code' |  paste -sd+ - | bc

Maintenance and Housekeeping

List all local repository paths for all projects (a bit more complex since we call the API in a loop):

call_api /projects | jq -r '.projects[].id' | while read id;do call_api /projects/$id \
| jq -r '.repository_paths_on_disk[]'; done | sort -u

File-Level Analysis Information

You can get the following information for every file analysed:

• path

• lines_of_code

• author_contributions_fragmentation

• goals

• name

• last_modification_age_in_months

• teams_contributions_fragmentation

• code_health

• language

• primary_team

• ownership_percentage

• number_of_authors

• cost

• number_of_defects

• recommendations

• team_ownership

• owner

• knowledge_loss_percentage

• number_of_teams

• change_frequency

CSV export of all files with their name, path, language and owner:

#!/bin/bash
page=1
while : ; do
  result=`call_api /projects/1/analyses/latest/files\?page=${page}`
  if [[ "${result}" != *"error"* ]]; then
    maxpages=`echo ${result} | jq -r '.max_pages'`
    echo ${result} | jq -r '.files[] | [.name, .path, .language, .owner] | @csv'
  fi
  page=$((page+1))
  [[ ${page} -gt ${maxpages} ]] && break
done

List the top hotspot files by change frequency:

call_api /projects/1/analyses/latest/files\?order_by=change_frequency | jq -r '.files[]
 | [.change_frequency,.name] | @csv'

Get the current code health score + the number of defects for the top 25 hotspot files of a project:

call_api /projects/1/analyses/latest/files\?order_by=change_frequency\&page_size=25 \
| jq -r '.files[] | [.change_frequency,.code_health.current_score,.number_of_defects,.lines_of_code,.name] | @csv'

Get the analysis schedule in cron format for all projects:

call_api /projects | jq -r '.projects[].id' | while read id;do call_api /projects/$id/export/configuration/json \
| jq -r .config.analysisplan; done

Get a list of all the files having a supervise goal set and filetered by a path pattern

page=1
while : ; do
    result=`call_api /projects/100/analyses/latest/files\?filter=path~"my_custom_path"+goals.category:supervise\&page=${page}`
    if [[ "${result}" != *"error"* ]]; then
        maxpages=`echo ${result} | jq -r '.max_pages'`
        echo ${result} | jq -r '.files[] | [(now | strflocaltime("%F")), .path, .goals[].category, .code_health.current_score] | @csv'
    fi
    page=$((page+1))
    [[ ${page} -gt ${maxpages} ]] && break
done

the example above is extracting data from project with id=100 and the files are filetered by path containing “my_custom_path”, goals category supervise and iterating through all the available pages, each like have a prefix with current data and the output looks like the one below

"2023-10-25","my_custom_path/file1.ts","supervise",9.38
"2023-10-25","my_custom_path/file2.ts","supervise",6.37
"2023-10-25","my_custom_path/file3.ts","supervise",9.38
"2023-10-25","my_custom_path/file4.ts","supervise",8.34

Code Health Analysis

List the 100 most worked on files together with their code health trend, and sort by relevance:

call_api /projects/1/analyses/latest/files\?order_by=change_frequency\&page_size=100 \
| jq -r '.files[] | [.change_frequency,.code_health.current_score,.code_health.month_score,.code_health.year_score,.name] | @csv'

Code Health Rules

The /metadata endpoint lets you access global rules and information. Here’s how you retrieve a list of all the code health rules that you can come across in a Virtual Code Review:

call_api /metadata/code-health-rules \
| jq -r '.code_health_rules[] | [.code_health_rule] | @csv'

Architecture-Level Analysis Information

You can get the following information for every component analysed:

• lines_of_code

• team_fragmentation_percentage

• name

• last_modification_age_in_months

• system_mastery

• language

• primary_team

• ownership_percentage

• number_of_authors

• cost

• team_ownership

• system_health

• owner

• knowledge_loss_percentage

• change_frequency

CSV export of all components with their name, language owner and change_frequency:

#!/bin/bash
page=1
while : ; do
  result=`call_api /projects/1/analyses/latest/components\?page=${page}`
  if [[ "${result}" != *"error"* ]]; then
    maxpages=`echo ${result} | jq -r '.max_pages'`
    refs=`echo ${result} | jq -r '.components[] | [.ref] | @csv'`
    for ref in $refs
    do
     component=`echo ${ref##*/} | rev | cut -c2- | rev`
     result=`call_api /projects/1/analyses/latest/components/${component}`
     if [[ "${result}" != *"error"* ]]; then
       echo "${result}" | jq -r '[.name, .language, .owner, .change_frequency] | @csv'
     fi
    done
  fi
  page=$((page+1))
  [[ ${page} -gt ${maxpages} ]] && break
done

List a project’s architectural components sort by name:

call_api /projects/1/analyses/latest/components | jq -r '.components | sort_by(.name)| .[] | [.name, .ref] | @csv'

Get some metrics for the architectural component by name in a project:

call_api /projects/1/analyses/latest/components/`read -p "Enter component name: " name && echo $name` \
    | jq -r '[.last_modification_age_in_months,.change_frequency,.lines_of_code,.system_health.current_score,.name] | @csv'

Get some metrics for all architectural components order by name in a project :

call_api /projects/1/analyses/latest/components | jq -r '.components | sort_by(.name)| .[] | .name' \
   | xargs -I % bash -c "call_api /projects/1/analyses/latest/components/% | jq -r '[.age,.change_frequency,.lines_of_code,.system_health.current_score,.name] | @csv'"

Create New Project

CodeScene is using the following environment variables when creating a new project

• CODESCENE_ANALYSIS_RESULTS_ROOT

  • “/path/to/analysis/”

• CODESCENE_CLONED_REPOSITORIES_ROOT

  • “/path/to/repositories/”

Example of create a new project using git repo URL and using environment variables

call_api /projects/new -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
    -d '{ "config": { "repo-paths": ["https://github.com/my-project/my-project-1.git"] } }'

This will create a project with name ‘my-project-1’

Example of create a new project using git repo URL without setting environment variables, you need to provide in the config the “local-path-for-remotes” and “analysis-destination”

call_api /projects/new -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
    -d '{ "config": { "repo-paths": ["https://github.com/my-project/my-project-2.git"], \
                      "local-path-for-remotes": "/path/to/repositories/", \
                      "analysis-destination": "/path/to/analysis/"} \
        }'

This will create a project with name ‘my-project-2’

Example of create a new project using git repo URL and existing developer configuration (using environment variables)

call_api /projects/new -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
    -d '{ "config": { "repo-paths": ["https://github.com/my-project/my-project-3.git"]} \
                      "developer-configuration": 10
        }'

This will create a project with name ‘my-project-3’ and reusing existing developer configuration with id = 10

Update Existing Project

Example of setting group id for existing project

call_api /projects/1 -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
    -d '{ "config": { "group-id": 2}}'

This will set the group with id 2 to the project with id 1

Example of setting developer configuration for existing project

call_api /projects/1 -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
    -d '{ "config": { "developer-configuration": 10}}'

This will set the developer-configuration with id 10 to the project with id 1