GitClear Public API Reference
Welcome to the reference for GitClear's Public API. This API is initially being launched to accommodate customers who need to submit details about Repo Releases and Critical Defects, but it will be trivial to extend the API to grab more types of data, or designate when important events occur in your repos.
Do you have data that you would like to access or create via the GitClear API? Email [email protected] -- if you're a paying subscriber, we'll add your request to our API queue. We can usually add new API actions within two weeks.
Reference quick links
API endpoints
Submitting an authenticated request
To submit a request to the GitClear API, include the Bearer token that can be found after you have created an API token in your entity in "Settings" -> "API Dashboard".
Variable type formatting
In the GitClear API reference, we specify the type for each input after the name of the key. Below, find details on the meaning of the variable types used by the GitClear API.
| Input type | Description | Examples |
|---|---|---|
| Boolean | A string or JSON-native boolean |
"true"
true
"false"
|
| DateTime (String) |
A string that describes, at a minimum, the date an event. Generally this input should also include a time and time zone associated with it. While the GitClear API can parse a variety of DateTime formats, it's generally recommended to pass in an ISO 8601 date, since it's ubiquitous across most programming languages. |
2022-02-01T14:40:15Z
February 1, 2022 at 8:42am CST
20-12-1990
|
| ResourcePath (String) | A forward-slash delineated path starting from the entity slug, optionally including the organization and repo slug of the resource. You can see your entity, organization and repo slugs by looking at the path shown when you visit GitClear reports. The resource path is what starts after '/entities/'. |
alloy-dev/gitclear/omniauth-azure-activedirectory
alloy-dev
your_entity_slug/your_organization_slug/your_repo_slug
|
| SHA (string) | A 40-character checksum hash used to uniquely identify a git commit, also known as the "SHA-1 hash" |
114edf26fb7fb3064092200591bb84fb7c464f07
2c823f9d52ef900f4228e9881d9c04846d6434db
|
Critical Defects
The Critical Defect API endpoints allows you to record when a Critical Defect occurs or is fixed. You generate the the key that we'll use to refer to the defect, so it can be a Jira issue like "BANANA-123" or it could be generated from scripts that monitor Devops infrastructure.
It's not uncommon that one discovers a Critical Defect before knowing which repo was responsible for it. This is why we allow a Critical Defect to be created with an Entity or an Organization as the resource. A Critical Defect can only be designated as "fixed" (by submitting fix_released_at or fix_released_sha) in a call that specifies a repo as the resource_path param (not an organization or entity).
It is expected that sometimes the team will release a fix for a defect, but the fix will be insufficient to completely eliminate the problem. For these cases, you can continue to make API calls that mark additional commits, times, or repos where the Critical Defect has another fix released. We will consider the defect "resolved" at the latest time a fix has been marked released across all repos.
Create or Update a Critical Defect
This API endpoint will ensure that a Critical Defect has been recorded, and designate when a fix is released for it.
Parameters
A forward-slash delineated path starting from the entity slug, optionally including the organization and repo slug of the resource.
You can see your entity, organization and repo slugs by looking at the path shown when you visit GitClear reports. The resource path is what starts after '/entities/'.
A customer-provided alphanumeric identifier used to subsequently refer to this defect
A category for the defect, for later correlation analysis
A datetime string providing the time at which the defect initially occurred. Required for the Critical Defect to be created.
Mark the defect as occurring upon receiving the API call. This param can act as a simpler substitute for the 'detected_at' param
Markdown description of the defect, for postmortem review
The time that the team pushed a fix for this defect to the applicable repo
A datetime string providing the time when a fix was released to production. If a fix_released_sha is given, this will be ignored in favor of the release date implied by the commit.
Mark the defect as having a fix released upon receiving the API call. This param can act as a simpler substitute for the 'fix_released_at' param
The sha of the commit that deployed the fix for the defect. The authorship stamp of this commit will be used as the release time if 'fix_released_at' and 'fix_released_now' are not given
The path to the repo where the fix was applied
A numeric value the customer can use to record the severity of the defect (i.e., for later correlation analysis)
Developers
The Developers API allows you to record time off for developers. Recording time off is important for reducing unwarranted notifications regarding expected activity.
Record or Remove Days Off (Excused Absences)
This API endpoint allows a team to record when a developer has logged PTO, so that notifications regarding expected activity can be reduced.
Parameters
A forward-slash delineated path starting from the entity slug, optionally including the organization and repo slug of the resource.
You can see your entity, organization and repo slugs by looking at the path shown when you visit GitClear reports. The resource path is what starts after '/entities/'.
The username of the developer that the request concerns
The starting date for the time off, given as YYYY-MM-DD.
The ending date for the time off, given as YYYY-MM-DD (optional).
Data Audits
The Data Audits API allows you to look at the raw data that GitClear has processed for your entity. Since this data feeds into charts, it can be helpful to have a quick, automated means of checking what we have on file, when we processed it, and what we have on file for it. This can only be accessed by admins of the resource being audited.
Parameters
A forward-slash delineated path starting from the entity slug, optionally including the organization and repo slug of the resource.
You can see your entity, organization and repo slugs by looking at the path shown when you visit GitClear reports. The resource path is what starts after '/entities/'.
The type of resource you want to audit
The username of the developer that the request concerns
The ending date for audit, given as YYYY-MM-DD, if a custom date range is desired.
(For issues) The issue key or number you wish to look up. This will be in the form PROJ-1234 if using Jira, or 1234 if using GitHub issues.
(For tags) A substring for the specific tag(s) you want to match
(For pull requests) The number of the pull request that you wish to look up, within repos that are in resource scope.
The page number to retrieve, starting from page 1 (the default). 50 records are shown per page.
(For commits) The sha of the specific commit you wish to look up.
The starting date for the audit, given as YYYY-MM-DD, if a custom date range is desired.
Imports
The Imports API allows you to dynamically import new repos into your entity. You can, with a callback under your source code provider, import repos as they are created and come into scope.
Parameters
The resource path (specifically, the slug of the entity you wish to import your repo into).
The path to the repo - this will be your organization or account slug (on GitHub/GitLab) or project key (on Bitbucket), followed by the slug of the repo you wish to import.
Releases
Create a Repo Release
This API endpoint will ensure that a Repo Release has been recorded.
Parameters
A forward-slash delineated path starting from the entity slug, optionally including the organization and repo slug of the resource.
You can see your entity, organization and repo slugs by looking at the path shown when you visit GitClear reports. The resource path is what starts after '/entities/'.
One or more defect_keys associated with critical defects that have been submitted via the defect endpoint (used for calculating DORA Lead Time and MTTR)
The git provider user name (e.g., their GitHub user name) of the committer who deployed the release
Alias of 'release_sha', enabling Heroku users to send an HTTP post hook without renaming a parameter
One or more issue keys that are known to be deployed in this release (used for calculating DORA Lead Time). When issue type is 'Bug' or 'Hotfix', the resolved issue will be marked as a defect
An optional name of the release
A datetime string providing the time at which the release occurred. This parameter is required unless 'release_sha', 'head_long', or 'release_now' are given. Can be either a string datetime like "Jan 1, 2024 at 3:30am" or "Feb 2, 2024 17:35" or "2024-03-21T22:50:03Z" or an integer representing seconds since 1970
Mark the release as occurring upon receiving of the API call. This param can act as a simpler substitute for the 'released_at' param
The sha of the commit that made the release. When present, this must be a commit that occurred within the repo specified via 'resource_path'.
The authorship timestamp of this commit will be used as the released_at time if a released_at is not provided.
Reports
The Reports API is an exact equvalent to the API that renders our timeline charts on various pages. It gives you the ability to see a historical breakdown of various stats - Diff Delta, comments on PRs, releases - and how that changes over time. Stats can be be segmented by various factors, such as repos, issue types, and code domain.
Callers can optionally include the a set of summarized stats for the chart in question. The particulars of what stats are summarized will depend on the stat segmentation chosen.
Parameters
A forward-slash delineated path starting from the entity slug, optionally including the organization and repo slug of the resource.
You can see your entity, organization and repo slugs by looking at the path shown when you visit GitClear reports. The resource path is what starts after '/entities/'.
The username or comma-separated user names of the contributor(s) you wish to get stats for. You may only specify contributors that have you have stats access granted to.
The number of days in the past to get stats for, relative to the current day. If this, start_date and end_date are both blank, defaults to 90.
The ending date for stats, given as YYYY-MM-DD, if a custom date range is desired.
If set to 'true', we will generate a set of additional, summarized stats for this time period. This will appear under 'calculated_summary_stats' in the response.
The data type to segment the graph by. Defaults to 'none' (no segmentation, showing total Diff Delta over time) if not given.
-
bug_work_percent
What fraction of time is spent on bugfixing commits?
-
churn_line_percent
What fraction of lines were churn?
-
code_category
The types of code that have generated the most Diff Delta
-
commit_count
How many git commits were authored?
-
copy_move_percent
Lower effort change types
-
days_to_first_deploy
Business days until first deploy
-
days_to_first_pr
Business days until first PR
-
defect_detected_count
Based on your release tracking settings
-
delta_velocity
Diff Delta output per development hour over time
-
dora_change_lead_time
DORA's "Change Lead Time" per issue: days from first commit to deployed
-
duplicate_block_line_count
How many lines in duplicate blocks were detected?
-
hours_to_fix_activity
Business hours between defect opened and first commit activity to resolve it
-
hours_to_fix_merged
Business hours between defect opened and PR merged to resolve it
-
issue_external_identifier
The highest Diff Delta issues over this time period
-
line_operation_counts
What operation types make up the bulk of your development?
-
mean_hours_to_first_repair
Business hours from "defect detected" until any fix is deployed
-
mean_hours_to_resolved
Business hours between "defect detected" and "final fix deployed"
-
minutes_used
Estimated hours spent working on code
-
operation
Beyond additions and deletions
-
provenance
How old is the code being changed?
-
pull_request_phase
How old is the code being changed?
-
pr_comments_left
Volume of feedback over time
-
pr_cycle
Average days from first commit to PR merge
-
pr_lead_time
DORA's "Change Lead Time" per PR: days from first commit to PR deployed
-
pr_open_time_days
Total languishing days open for PRs in resource
-
pr_resolved_days
Average days from when PR is open until merge
-
quality_cornerstones_percent
Percent work dedicated to tests and documentation
-
release_count
Release counts broken down over time
-
release_defect_percent
Percent of releases that harbored a critical defect
-
release_phase
See which releases have had the highest Diff Delta.
-
release_resolves_defect_count
Releases that attempt to resolve a critical defect
-
repo
Diff Delta by repos
-
story_points_resolved
How many story points have been resolved?
-
story_points_resolved_estimated
Of resolved tickets, how many story points had been estimated?
-
ticket_type
What types of tickets are being worked on?
The starting date for stats, given as YYYY-MM-DD, if a custom date range is desired.
Override normal behavior, which is to project the final data point for segment_by values whose values can be multiplied by the percent of the final interval pending in order to produce a plausible value.
The slug form of the team you wish to get stats for, as it appears in your page URLs
Teams
Create a Team
This API endpoint will enable a team to be created with specific developers and managers.
Parameters
The name of the team you wish to create, update or retrieve
The git provider user names (e.g., 'octocat') or email addresses of developer members of this team
When a developer has not yet joined GitClear, email them an invitation. Requires specifying developer members by email address. Default is false.
When a manager has not yet joined GitClear, email them an invitation Requires specifying manager members by email address. Default is false.
The git provider user names (e.g., 'octocat') or email addresses of manager members of this team
The git provider user names (e.g., 'octocat') or email addresses of team members to be removed from a team
The paths (e.g., "organization-name/repo-name") of repos that this team should include in its stats. If not specified, team will include all repos worked by its committers