GitClear Public API Beta 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".
GET
https://www.gitclear.com/api/v1/api_tokens
curl https://www.gitclear.com/api/v1/api_tokens \ -H "Authorization: Bearer {your_token}"
Response
{ "action_em": "action_get_resource", "response_em": "response_success", "response_detail": "Your token is ready for use 👍" }

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

required
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
required
One of commits, issues, pull_requests or tags

The type of resource you want to audit

Integer

The page number to retrieve, starting from page 1 (the default). 50 records are shown per page.

String

The username of the contributor you wish to get commits/issues/pull requests for.

DateTime (String)

The starting date for the audit, given as YYYY-MM-DD, if a custom date range is desired.

DateTime (String)

The ending date for audit, given as YYYY-MM-DD, if a custom date range is desired.

Name (String)

(For tags) A substring for the specific tag(s) you want to match

SHA (String)

(For commits) The sha of the specific commit you wish to look up.

Integer

(For pull requests) The number of the pull request that you wish to look up, within repos that are in resource scope.

String, or Integer

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

GET
https://www.gitclear.com/api/v1/audits
curl -H "Authorization: Bearer {your token}" \ "https://www.gitclear.com/api/v1/audits?\ resource_type=commits&\ resource_path=your_resource_path&\ team_slug=all-contributors"
Response
{ "commits": [ { "authored_at": "2023-06-26 17:45:03 UTC", "child_shas": [], "contributor": { "full_name": "Jane Doe", "username": "jdoe123" }, "diff_delta": 0.0, "entered_gitclear_at": "2023-06-27T00:46:08.546Z", "message": "Fix a critical bug", "presence": "existent", "repo": "example/repo", "sha": "20ce1e96e94e25f4911d4c7bff9fed47820033de", "sites": [], "state": "analysis_complete" } ], "page": 1, "per_page": 50, "total_count": 4178 }

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

required
ResourcePath (String)

The resource path (specifically, the slug of the entity you wish to import your repo into).

my-entity
required
String

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.

some-org/some-repo
GET
https://www.gitclear.com/api/v1/imports
curl -H "Authorization: Bearer {your token}" -POST \ "https://www.gitclear.com/api/v1/imports" \ -d "resource_path=your-entity" \ -d "repo_path=your-org-slug/your-repo-slug"
Response
{ "imported": true, "errors": null }

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

required
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
required
String

The slug form of the team you wish to get stats for, as it appears in your page URLs

Boolean

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.

String

The username of the contributor you wish to get stats for. You may only specify contributors that have you have stats access granted to.

String (specific values)

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.

  • hours_to_last_repair

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

DateTime (String)

The starting date for stats, given as YYYY-MM-DD, if a custom date range is desired.

DateTime (String)

The ending date for stats, given as YYYY-MM-DD, if a custom date range is desired.

Integer

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

GET
https://www.gitclear.com/api/v1/reports
curl -H "Authorization: Bearer {your token}" \ "https://www.gitclear.com/api/v1/reports? \ resource_path=your_resource_path&\ team_slug=all-contributors"
Response
{ "context": { "entity": "some-entity", "organization": "some-org" }, "interval_em": "weekly", "series_segments": { "Your Repo": [ { "url": "https://www.gitclear.com/your_commits?end_date=2022-03-28", "x": "March 28", "y": 11182.76 }, { "url": "https://www.gitclear.com/your_commits?end_date=2022-04-04", "x": "April 4", "y": 7728.65 } ] }, "unit": "Diff Delta" }

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.

Endpoints
POST
https://www.gitclear.com/api/v1/critical_defects

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

required
String

A customer-provided alphanumeric identifier used to subsequently refer to this defect

required
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
DateTime (String)

A datetime string providing the time at which the defect initially occurred. Required for the Critical Defect to be created.

Boolean

Mark the defect as occurring upon receiving the API call. This param can act as a simpler substitute for the 'detected_at' param

String

Title or description of the defect, for postmortem review

DateTime (String)

A datetime string providing the time at which a fix was released for the defect

Boolean

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

SHA (String)

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

Integer

A numeric value the customer can use to record the severity of the defect (i.e., for later correlation analysis)

POST
https://www.gitclear.com/api/v1/critical_defects
curl https://www.gitclear.com/api/v1/critical_defects \ -H "Authorization: Bearer {your token}" \ -d detected_at="Jan 1, 2021 at 5:40pm PST" \ -d defect_key="JIRA-123" \ -d description="Site outage for 15 minutes" \ -d fix_released_at="Jan 2, 2021 8:35am EST" \ -d resource_path="{your resource path}" \ -d severity=2 \ -X POST
Response
{ "action_em": "action_defect_created", "response_em": "response_success", "response_detail": "Successfully ensured creation of defect release at Jan 1, 2021 5:40pm", }

Releases

Designating a release allows us to GitClear to indicate when tickets or commits have been deployed to production. Each release will ultimately be associated with a commit that immediately precedes the release. This is designated to be the "release commit" for the purposes of comparing what changed from release to release.
Endpoints
POST
https://www.gitclear.com/api/v1/releases

Create a Repo Release

This API endpoint will ensure that a Repo Release has been recorded.

Parameters

required
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
SHA (String)

Alias of 'release_sha', enabling Heroku users to send an HTTP post hook without renaming a parameter

String

An optional name of the release

v2.3 beta
DateTime (String)

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

Boolean

Mark the release as occurring upon receiving of the API call. This param can act as a simpler substitute for the 'released_at' param

SHA (String)

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.

POST
https://www.gitclear.com/api/v1/releases
curl https://www.gitclear.com/api/v1/releases \ -H "Authorization: Bearer {your token}" \ -d name="v3.1 beta" -d released_at='May 25, 2023 at 4:20pm' -d release_sha='541a8b28d08405aa961f9de1d7c8fcd5c3da3218' -d resource_path="{your repo path}" \ -X POST
Response
{ "action_em": "action_release_created", "response_em": "response_success", "response_detail": "Release ensured to exist at May 25 at 4:20 pm in 'alloy/gitclear/libinput'", }