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
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
|
Audits
The 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 page number to retrieve, starting from page 1 (the default). 50 records are shown per page.
The username of the developer that the request concerns
The starting date for the audit, given as YYYY-MM-DD, if a custom date range is desired.
The ending date for audit, given as YYYY-MM-DD, if a custom date range is desired.
(For tags) A substring for the specific tag(s) you want to match
(For commits) The sha of the specific commit you wish to look up.
(For pull requests) The number of the pull request that you wish to look up, within repos that are in resource scope.
(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.
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).
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.
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 slug form of the team you wish to get stats for, as it appears in your page URLs
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 username of the contributor you wish to get stats for. You may only specify contributors that have you have stats access granted to.
The data type to segment the graph by. Defaults to 'none' (no segmentation, showing total Diff Delta over time) if not given.
-
code_category
The code category (or code domain) of Diff Delta under scope. Learn about code domains here.
-
commit_count
The total number of commits over time.
-
committer_count
The number of contributors to each segmented repo under scope.
-
defect_detected_count
The number of critical defects detected under scope.
-
mean_hours_to_resolved
The average number of hours until repair (otherwise known as MTTR).
-
issue_external_identifier
The top Diff Delta-based issues worked on.
-
operation
Diff Delta, sorted by operation type (added, removed, updated, etc.)
-
pr_open_time_days
The open time per merged pull request.
-
pull_request_phase
Diff Delta, sorted into pull request phases.
-
pr_cycle
The cycle time (first commit to PR merged) time, in days, per merged pull request.
-
pr_comments_left
The number of comments left across all PRs.
-
pr_resolved_days
The average days from when a PR is opened to closed
-
provenance
Diff Delta, organized by provenance (age of code being changed).
-
release_phase
Diff Delta, organized into specific releases (as determined by your release tracking settings).
-
repo
Diff Delta, by repo under scope.
-
story_points_resolved
Story points, within resolved issues, over time.
-
team
Diff Delta segmented by team (only allowed if the user is a Manager or above on multiple teams).
-
ticket_type
Diff Delta, organized by ticket type, as determined by your issue tracking settings.
The starting date for stats, given as YYYY-MM-DD, if a custom date range is desired.
The ending date for stats, given as YYYY-MM-DD, if a custom date range is desired.
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.
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 customer-provided alphanumeric identifier used to subsequently refer to this defect
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 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
Title or 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)
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/'.
Alias of 'release_sha', enabling Heroku users to send an HTTP post hook without renaming a parameter
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
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.