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

Sending email

Authenticated users with REST read and write scopes can submit email through POST /api/mail (unversioned) on the CodeScene application host, using the configured Cloud sender. No organization administrator role is required. These outreach operations require MCP statistics access. projectId is required, the caller must have read access to that project, and every recipient must be a known author or user of the project, including historical authors.

From uses the authenticated user’s sanitized display name with the configured Cloud mailbox; the transport sender does not change. The optional boolean replyToInitiator defaults to true. Set it to false to opt out. Reply-To is resolved server-side from the authenticated user. When a usable reply address exists, the body ends with Reply to this email to reach <sender-name>. Otherwise, the message is sent without Reply-To or the footer and a warning is logged.

{
  "projectId": 1,
  "emails": ["developer@example.com"],
  "subject": "Code review",
  "body": "Hi {{email}}, {{sender-name}} asks you to review {{project}}.",
  "format": "text"
}

format is optional; only text is supported. HTML is removed. Requests accept 1-100 recipient addresses, a subject of 1-998 characters without line breaks, and a body of 1-1048576 characters, including after substitution. The response is {"deliveries": [{"email": "developer@example.com", "status": "submitted"}]}. submitted means the transport accepted the message, not confirmed delivery. Each address is submitted independently; failures return send-failed for that address. Retrying an entire partially successful request can send duplicate messages. Unauthenticated requests return 401, insufficient scopes return 403, and invalid request bodies return 400.

Body placeholders and allowed links

GET /api/mail/placeholders returns a JSON array of supported variable names, descriptions, and illustrative example values, without looking up customer data:

[
  {
    "name": "sender-name",
    "description": "The sender's sanitized display name.",
    "example": "Alex Morgan"
  }
]

The full Cloud mail list is sender-name, project, org-name, and email. Write a name between double braces, for example {{project}}. GET /api/invitations/placeholders additionally lists invite-link. instance-url is on-prem only; invite-link cannot be used in ordinary mail. Discovery requires the same feature access and REST read scope as other outreach reads, but no project or recipient parameters.

Body substitution is literal, once per recipient; there are no template filters or executable expressions. Unsupported or malformed placeholders return 400 with an error identifying the unsupported syntax and listing supported variables, before any invitation is stored or email is submitted. Sender, project, and organization labels are stripped of HTML and links, collapsed to one line, and limited to 100 characters. If the sender has no usable name, a neutral CodeScene label is used and a warning is logged.

Subject links are removed. Body links are removed unless their exact HTTPS origin is configured in the server’s :outreach-allowed-link-origins vector, for example ["https://docs.example.com"]. The default is []. Subdomains, different ports, HTTP, and URLs with user credentials are not implicitly trusted. Operators can change this configuration without releasing new application code. The server-generated invitation link is trusted independently of this allowlist.

Invitation email replies

Email invitations created through POST /api/invitations also accept the optional boolean replyToInitiator, defaulting to true. When enabled, Reply-To uses the original requester’s email address, including when an administrator approves or resends the invitation. The choice is stored with the invitation; the address is resolved from the stored requester identity at sending time. The original requester’s sanitized name is used in From and the subject, You're invited to CodeScene via <sender-name>. The authorized project context and custom template are also retained through approval and resends, while {{invite-link}} resolves to a fresh server-generated link. If that user no longer has a usable email address, the invitation is sent without Reply-To or the reply footer and a warning is logged.

These sender and reply defaults apply only to these outreach operations. Other product emails are unaffected.

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. 158 and Fig. 159.
List Api tokens

Fig. 158 List Api tokens

Add Api token

Fig. 159 Add Api token

Api token

Fig. 160 Api token created

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

Filter queries

All API endpoints that return paged data 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.

^

field^validator
Validate that the field meets the criteria specified by the validator.
Supported validators:

  • empty: the collection is empty

  • not-empty: the collection is not empty

  • some: at least one value is non-null (useful for nested fields)

  • none: all values are null (useful for nested fields)

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 -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects?page={page}&order_by={order_by}&filter={filter}&fields={fields}'

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

  • Replace {order_by} with one of the following values to sort projects in descending order:

    • name - project name

    • analysis.code_health.now - current code health score

    • analysis.code_health.month - code health from a month ago

    • analysis.code_health.year - code health from a year ago

    • analysis.code_health.change_month - code health change over last month

    • analysis.code_health.change_year - code health change over last year

    • analysis.hotspot_code_health.now - current hotspot code health

    • analysis.hotspot_code_health.month - hotspot code health from a month ago

    • analysis.hotspot_code_health.year - hotspot code health from a year ago

    • analysis.hotspot_code_health.change_month - hotspot code health change over last month

    • analysis.hotspot_code_health.change_year - hotspot code health change over last year

    • analysis.authors.total - total number of authors

    • analysis.authors.active - number of active authors

    • analysis.delivery.unplanned_work_percent - percentage of unplanned work (requires PM integration)

    • analysis.delivery.avg_development_time_minutes - average development time in minutes (requires PM integration)

    • analysis.code_coverage.line_coverage_percent - line coverage percentage from test coverage data

  • The optional filter parameter can be used to filter the results.

  • The optional fields parameter is a comma-separated list of field names used to limit the fields returned for each project.

New Project

 curl -X POST -H 'Content-Type: application/json' -H '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.

Single project details

 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/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.

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

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

Get the Project Architectural Components

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

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

Update the Project Architectural Components

Replace the current project architectural components with the one set on the POST payload below

 curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' \
 -H 'Authorization: Bearer <token>' -d '[{"name":"ui", "patterns":["/src/ui/**"]},{"name":"core", "patterns":["/src/main/**", "/src/test/**"]}]' \
 'https://api.codescene.io/v2/projects/{project_id}/components'

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

List git repositories

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

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

Add git repositories

 curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 --data '{"repositories":[{"url": "https://mycompany.com/projects/p1.git", "branch": "main"}, {"url": "https://mycompany.com/projects/p2.git", "branch": "1.0.x"}]}' \
 'https://api.codescene.io/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 -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 --data '{"repositories":[{"url": "https://mycompany.com/projects/p1.git", "branch": "v.0.1"}]}' \
 'https://api.codescene.io/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 -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 --data '{"urls":["https://mycompany.com/projects/p1.git", "https://mycompany.com/projects/p2.git"]}' \
 'https://api.codescene.io/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

Analysis List of a project

 curl -X GET -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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}&fields=path,code_health'

  • 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”.

  • The optional fields parameter can be used to limit the fields returned for each file. In the example above only the path and code_health fields are returned.

Files list in descending order based on order_by value for latest analysis
 curl -X GET -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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.

Commits list from an analysis

Commits list for given analysis id
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/commits?page={page}&page_size={page_size}'

  • 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 commits to return for a page. If page_size parameter is omitted the default value is 200.

Commits list for latest analysis
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/commits?page={page}&page_size={page_size}'

  • 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 commits to return for a page. If page_size parameter is omitted the default value is 200.

Issues list from an analysis

Issues list for given analysis id
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/issues?page={page}&page_size={page_size}'

  • 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 issues to return for a page. If page_size parameter is omitted the default value is 200.

Issues list for latest analysis
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/issues?page={page}&page_size={page_size}'

  • 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 issues to return for a page. If page_size parameter is omitted the default value is 200.

Commit activity trend from an analysis

Commit activity trend for given analysis id
curl -X GET -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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.

Technical debt friction from an analysis

Technical debt friction for given analysis id
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/technical-debt'

  • 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.

Technical debt friction for latest analysis
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/technical-debt'

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

Technical debt hotspots from an analysis

Technical debt hotspots for given analysis id
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/{analysis-id}/technical-debt?refactoring_targets=true'

  • 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.

Technical debt hotspots for latest analysis
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/projects/{project-id}/analyses/latest/technical-debt?refactoring_targets=true'

  • 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 -H 'Accept: application/json' -H '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 -H 'Content-Type: application/json' -H 'Accept: application/json' \
 -H '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 -H 'Content-Type: application/json' -H '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 -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/developer-settings'

Teams list

 curl -X GET -H 'Accept: application/json' -H '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 -H 'Content-Type: application/json' -H 'Accept: application/json' \
 -H '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 -H 'Content-Type: application/json' -H 'Accept: application/json' \
 -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Content-Type: application/json' -H 'Accept: application/json' \
 -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 -H 'Accept: application/json' -H '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 Health Engineering Outcomes

Estimate the engineering impact of moving from one Code Health score to another. The estimates are based on CodeScene’s empirical Code Health research and return a 90% interval for each supported outcome.

For background on the methodology, see Benchmarking Code Health Refactoring ROI.

 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/code-health/engineering-outcomes?baseline=6.2&target=8.1'

  • Required query parameters: baseline and target.

  • Optional query parameter: initial_unplanned_work_pct.

  • Both values must be valid Code Health scores between 1.0 and 10.0.

  • When initial_unplanned_work_pct is omitted, CodeScene uses baseline-dependent defaults: 50 below 4.0, 30 below 7.0, otherwise 10.

  • If you want to provide initial_unplanned_work_pct, you can retrieve it from CodeScene’s Delivery analysis.

  • The endpoint is independent of projects and analyses, so it can be used for project, component, or file level Code Health changes.

Example response:

{
  "baseline_code_health": 6.2,
  "target_code_health": 8.1,
  "unit": "percent",
  "confidence_level": 90,
  "assumptions": {
    "initial_unplanned_work_pct": 30.0,
    "initial_unplanned_work_pct_source": "default"
  },
  "summary": "Improving Code Health from 6.2 to 8.1 is associated with 7% to 22% fewer defects and 11% to 23% less development time for future changes to this code. Combined, that is 18% to 37% higher productivity, assuming 30% of current work is unplanned. Ranges are 90% confidence intervals.",
  "outcomes": {
    "defects": {
      "lower": -21.85,
      "upper": -6.69,
      "direction": "decrease",
      "interpretation": "7% to 22% fewer defects"
    },
    "development_time": {
      "lower": -22.79,
      "upper": -11.46,
      "direction": "decrease",
      "interpretation": "11% to 23% less development time"
    },
    "combined_productivity_impact": {
      "lower": 18.32,
      "upper": 37.31,
      "direction": "increase",
      "interpretation": "18% to 37% higher productivity"
    }
  }
}

The summary explains the result in plain language: improving Code Health from 6.2 to 8.1 is associated with 7% to 22% fewer defects and 11% to 23% less development time for any future changes touching that part of the code. The combined productivity impact rolls together less unplanned work from defects and more delivery capacity from shorter development time.

Note: The range (e.g. 7% to 22%) shows the 90% confidence interval. This means the model reports a range that is expected to contain the likely effect, rather than pretending to predict one exact outcome.

Response includes:

  • baseline_code_health and target_code_health - the input scores used for the estimate.

  • unit - the unit of every interval bound: a relative change from the baseline, in percent.

  • confidence_level - the confidence level of the intervals, in percent.

  • assumptions.initial_unplanned_work_pct - the initial unplanned work share used for the combined productivity impact, and assumptions.initial_unplanned_work_pct_source - provided when it came from the request, default when it was derived from the baseline.

  • summary - a human-readable summary of the whole estimate. Show it as-is to present the result the same way as CodeScene’s own clients.

  • outcomes.defects - the estimated 90% interval for relative defect reduction.

  • outcomes.development_time - the estimated 90% interval for relative development time reduction.

  • outcomes.combined_productivity_impact - the estimated 90% interval for the combined effect of lower defect-driven unplanned work and faster delivery capacity.

Each outcome also includes:

  • direction - decrease or increase when the whole interval lies on one side of zero, mixed when it spans zero, and unchanged when both bounds are zero.

  • interpretation - a short phrase for the interval, such as 7% to 22% fewer defects. Percentages are rounded to whole numbers and ordered by magnitude. Changes below 1% are described as less than 1%.

Lowering the target below the baseline reverses the wording, for example 7% to 28% more defects and 13% to 24% lower productivity.

Code Coverage endpoints

The Code Coverage endpoints lets you list or delete uploaded code coverage data.

List Data

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

 curl -X GET -H 'Accept: application/json' \
 -H 'Authorization: Bearer <token>' "https://api.codescene.io/v2/code-coverage?repo-url=$(git config --get remote.origin.url)"

 => [
      {
        "id": 1,
        "repo": "github.com/mycompany/myproject",
        "commit_sha": "12348bd683bfa5db8227a281a4a295d6d0281234",
        "created_at": "2025-01-07T10:00:00.000Z",
        "summary": {
          "files": 412,
          "metrics": ["line-coverage", "method-coverage"],
          "path_prefix": "services/api"
        }
      }
    ]

 ``summary`` tells what the data of the upload contains: the number of files, the
 metrics, and the directory that all the files are in (empty when they have no
 common directory). It is missing for uploads made before it was added.

Delete Data

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

 curl -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/json' \
 -H '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."}

Insights

Fetch the code coverage results insights for a particular period, if form is missing the previous month will be used, if to is missing the currend date will be used:

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

 curl -X GET -H 'Accept: application/json' \
 -H 'Authorization: Bearer <token>' "https://api.codescene.io/v2/code-coverage/projects/{project-id}/gate-results/insights?from=yyyy-MM-dd&to=yyyy-MM-dd"

 => {
       "meta": {
         "project_id": <project-id>,
         "from": "yyyy-MM-dd",
         "to": "yyyy-MM-dd",
         "generated_at": "yyyy-MM-ddTHH:mm:ss.SSSZ"
       },
       "summary": {
         "evaluated_gates": 8,
         "pass": 8,
         "fail": 0,
         "pass_rate": 1
       },
       "gates": [{
           "name": "overall_coverage",
           "coverage_metric": "line_coverage",
           "enabled_count": 4,
           "threshold_distribution": [{
              "threshold": 80,
              "count": 4
           }]},
         {
           "name": "new_and_changed_code",
           "coverage_metric": "line_coverage",
           "enabled_count": 4,
           "threshold_distribution": [{
              "threshold": 95,
              "count": 4
           }]
         }]
    }

Outcomes

Fetch the code coverage results outcomes for a particular period, if form is missing the previous month will be used, if to is missing the currend date will be used, if page is missing the first page will be fetched, if page-size is missing the default page size is 100:

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

 curl -X GET -H 'Accept: application/json' \
 -H 'Authorization: Bearer <token>' "https://api.codescene.io/v2/code-coverage/projects/{project-id}/gate-results/outcomes?from=yyyy-MM-dd&to=yyyy-MM-dd"

 => {
      "page": 1,
      "max_pages": 1,
      "outcomes": [
        {
          "coverage_results": {
            "all_gates_pass": false,
            "result_per_gate": [
              {
                "name": "overall_coverage",
                "measured_coverage": 49,
                "threshold": 80,
                "details": {
                  "pass_or_fail_reason": "The overall coverage gate was checked for all code in backend/, ui/ and is too small: 49.0% covered < threshold = 80%",
                  "action": {
                    "description": "Start by adding tests to the following files (optionally, exclude content from the coverage gates via CodeScene's configuration): ",
                    "files": [
                      {
                        "cc_details": "782 uncovered lines",
                        "file_name": "ui/src/foo/bar/index.js"
                      }
                    ]
                  }
                },
                "coverage_metric": "line_coverage",
                "pass": false,
                "enabled": true
              },
              {
                "name": "new_and_changed_code",
                "measured_coverage": 0,
                "threshold": 95,
                "details": {
                  "pass_or_fail_reason": "New or changed code lacks code coverage: 0.0% covered < threshold = 95%",
                  "action": {
                    "description": "Add tests to: ",
                    "files": [
                      {
                        "cc_details": "uncovered line(s) = [16-55,57-69,71-80,82-99,101-114]",
                        "file_name": "ui/foo/bar/index.tsx"
                      }
                    ]
                  }
                },
                "coverage_metric": "line_coverage",
                "pass": false,
                "enabled": true
              }
            ]
          },
          "pr_context": false,
          "created_at": "yyyy-MM-ddTHH:mm:ssZ"
        }
      ]
    }

Code Health Safeguards endpoints

The Code Health Safeguards API provides insights into how code health is being maintained across pull requests and MCP (CodeScene MCP Server) usage.

On-prem MCP events can include git-author-email in their event properties. Project safeguards use this email as a fallback when the authenticated identity does not already match a developer. Matching covers all known Git-email aliases of configured developers, ignoring case and surrounding whitespace. This connects MCP activity to developer names and adoption cohorts even when the CodeScene login is not an email address.

Each login represents one person: the latest event’s Git email associates that login’s user-list entry and history with a developer. Project insights also use matching event emails to connect the login’s older activity. Unmatched emails remain separate from configured developers; usernames are not guessed from email prefixes. The login remains the identity used for access control and /me endpoints; Git metadata does not grant access. Emails are retained locally for attribution and hashed before telemetry leaves the installation.

There are two families of endpoints:

  • PR Safeguards — project-scoped, surfacing aggregated and per-PR data from delta analyses.

  • MCP Safeguards — user or organization-scoped, tracking usage of CodeScene’s MCP server tools.

Pagination

The examples below use the v2 API, which retains numbered pagination: page (default: 1), page-size (default: 100), and response fields page and max_pages. Out-of-range pages on nonempty results return 404.

The corresponding Reborn endpoints under /api use cursor pagination instead. For PR outcomes, MCP outcomes, and MCP user lists:

  • Send pageSize (default: 100, maximum: 15000) for the first request.

  • If the response includes nextPageToken, send it as pageToken on the next request.

  • Keep filters and sort options unchanged when using a token; changing them returns 400.

  • You may change pageSize between requests.

  • The final page omits nextPageToken. Empty or out-of-range results return an empty list.

Reborn responses retain the outcomes or users list and applicable domain metadata, but do not include page, maxPages, or totalCount.

PR Safeguards: Insights

Aggregated view of PR safeguard activity over a time range for a project.
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/code-health/projects/{project-id}/safeguards/pr/insights?from=2026-01-01&to=2026-04-30'

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

  • Optional query parameters: from (YYYY-MM-DD, default: 1 month ago), to (YYYY-MM-DD, default: today).

Response includes:

  • summary — total PR analyses, findings detected, fixed, ignored, and suppressed across the date range.

  • interpretation — a high-level verdict: no-issues, stable, or degrading.

  • monthly-trends — the same summary broken out per calendar month.

PR Safeguards: Outcomes

Individual PR-level outcomes showing what happened in each analyzed pull request.
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/code-health/projects/{project-id}/safeguards/pr/outcomes?from=2026-01-01&to=2026-04-30'

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

  • Optional query parameters: from, to, page (default: 1), page-size (default: 100).

Each outcome includes the PR identifier, analysis date, repository, authors, finding statistics, and a per-PR interpretation (no-issues, resolved, or unresolved).

MCP Safeguards: User Insights

Aggregated MCP safeguard activity for the authenticated user.
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/code-health/safeguards/mcp/insights/me'

Response includes the user’s most-used MCP tools, number of safeguard checks, code health uplifts, degradations prevented, and installation info.

MCP Safeguards: User Outcomes

Paginated list of individual MCP safeguard events for the authenticated user.
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/code-health/safeguards/mcp/outcomes/me?page=1&page-size=100'

  • Optional query parameters: page (default: 1), page-size (default: 100).

Each outcome includes the event type, timestamp, event properties (file hash, version, instance ID), and optionally a code health score and detected code smell categories.

MCP Safeguards: Organization Insights (Admin)

Organization-wide aggregated MCP safeguard insights. Requires admin access.
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/code-health/safeguards/mcp/insights'

Same structure as the user insights endpoint, with additional fields: number-of-users, number-of-active-users, number-of-paid-seats, and adoption-percentage.

MCP Safeguards: Organization Outcomes (Admin)

Organization-wide paginated MCP event outcomes. Requires admin access.
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/code-health/safeguards/mcp/outcomes?page=1&page-size=100'

  • Optional query parameters: page (default: 1), page-size (default: 100).

Same structure as user outcomes. The user-identity field is included when available.

MCP Safeguards: Per-User Breakdown (Admin)

Per-user breakdown of MCP safeguard activity across the organization. Requires admin access.
 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
 'https://api.codescene.io/v2/code-health/safeguards/mcp/users?page=1&page-size=100'

  • Optional query parameters: page (default: 1), page-size (default: 100).

Each user entry includes their identity, user ID, and a summary with safeguard check count, uplifts, degradations prevented, and most-used tools.

Active authors

The active authors across the projects you can access, together with the projects each author has contributed to. An active author is anyone who has committed code over the past three months (a sliding window ending at the date of the most recent commit).
Only projects you are allowed to access are included in the results.
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \
'https://api.codescene.io/v2/active-authors?page={page}&page_size={page_size}&filter={filter}'

  • The optional page parameter selects the page to return. If omitted the default value is 1.

  • The optional page_size parameter sets the number of authors per page. If omitted the default value is 100.

  • The optional filter parameter can be used to filter the results, for example author:<name> to match an author or projects.name:<name> to match a project.

The response is a paginated list of authors and the projects they contribute to:

{
  "page": 1,
  "max_pages": 1,
  "active_authors": [
    {
      "author": "Author name",
      "projects": [
        {
          "id": 1,
          "name": "Project name",
          "ref": "/api/v2/projects/1"
        }
      ]
    }
  ]
}

  • ref is an API link to the project resource (see Projects list).